add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / data / schema / Association.js

/**\r
 * This class and its derivatives describe how two entities are related to each other.\r
 * Associations have the following forms:\r
 * \r
 *   * *{@link Ext.data.schema.ManyToOne many-to-one}*\r
 *   * *{@link Ext.data.schema.ManyToMany many-to-many}*\r
 *   * *{@link Ext.data.schema.OneToOne one-to-one}*\r
 *\r
 * Associations are first-class objects in a `{@link Ext.data.schema.Schema schema}` but\r
 * are not created directly. They are created based on {@link Ext.data.field.Field#reference}\r
 * properties but also on {@link Ext.data.schema.ManyToMany} declarations.\r
 * \r
 * Associations have unique names within the `schema` as do {@link Ext.data.Model entities}.\r
 * In many cases, the association names can be generated. These names have uses beyond the\r
 * basic needs of tracking such as when communicating with the server. If the generated\r
 * names are not satisfactory, they can be given explicitly or the default naming can be\r
 * replaced by implementing a custom `Ext.data.schema.Schema` class.\r
 *\r
 * # Life Cycle\r
 *\r
 * Intimately connected with many associations is the concept of life-cycle. It is often\r
 * the case that one entity is "owned" by another so that if the owner is to be deleted,\r
 * the owned entity must also be deleted.\r
 * \r
 * There are also associations that work in the reverse direction. That is, the presence of\r
 * an associated entity prevents the other entity from being deleted.\r
 * \r
 * Finally, some associations just need to be dissolved if one of the related entities is\r
 * deleted. This is the case in a {@link Ext.data.schema.ManyToMany many-to-many}\r
 * association, but can also be for others if the `reference` field can be set to `null`.\r
 * \r
 * # Left and Right\r
 *\r
 * Because associations are data that span entity types, they are not rightly viewed as\r
 * "belonging" to either entity. Instead, associations are owned by the `Schema`. Even so,\r
 * because belonging to an association effects both entities, associations are often\r
 * viewed from two perspectives or "sides". To distinguish them we call one "left" and the\r
 * other "right".\r
 * \r
 * The reason for this choice derives from {@link Ext.data.schema.ManyToMany many-to-many}\r
 * associations and their typical underlying "matrix" table. If you were to view the matrix\r
 * table in a grid, you would see one id on the left and the other id on the right. There\r
 * is no further significance to these labels.\r
 * \r
 * While the concept of left and right might makes sense in a matrix relationship, the\r
 * labels also apply to the other relationships. In those cases, the "left" entity is the\r
 * entity that contains the {@link Ext.data.Field#reference} (or foreign key).\r
 *\r
 * # Example\r
 * \r
 * To help illustrate the various associations, consider a data model with Users, Groups\r
 * and Organizations. The Users are owned by an Organization. Deleting an Organization,\r
 * should delete all of the Users it contains. The Users can also be added to one or more\r
 * Groups, for example, the "moderator" or "admin" Group. Further, a a Level is assigned\r
 * to each User. Levels represent the subscriber's or customer's rank, such as "premium"\r
 * or "basic".\r
 * \r
 * To summarize:\r
 * \r
 *  * Users are *{@link Ext.data.schema.ManyToOne many-to-one}* to Organizations\r
 *  * Users are *{@link Ext.data.schema.ManyToOne many-to-one}* to Levels\r
 *  * Users are *{@link Ext.data.schema.ManyToMany many-to-many}* to Groups\r
 */\r
Ext.define('Ext.data.schema.Association', {\r
    requires: [\r
        'Ext.data.schema.Role'\r
    ],\r
\r
    isOneToOne: false,\r
    isManyToOne: false,\r
    isManyToMany: false,\r
\r
    /**\r
     * @cfg {String} name\r
     * The name of this association.\r
     */\r
\r
    /**\r
     * @property {Object} owner\r
     * Points at either `left` or `right` objects if one is the owning party in this\r
     * association or is `null` if there is no owner.\r
     * @readonly\r
     */\r
    owner: null,\r
\r
    /**\r
     * @property {Ext.Class} definedBy\r
     * @readonly\r
     */\r
\r
    /**\r
     * @property {Ext.data.field.Field} field\r
     * @readonly\r
     */\r
    field: null,\r
\r
    /**\r
     * @property {Ext.data.schema.Schema} schema\r
     * @readonly\r
     */\r
\r
    /**\r
     * @property {Boolean} nullable\r
     * @readonly\r
     */\r
\r
    /**\r
     * @property {Ext.data.schema.Role} left\r
     * @readonly\r
     */\r
\r
    /**\r
     * @property {Ext.data.schema.Role} right\r
     * @readonly\r
     */\r
\r
    constructor: function (config) {\r
        var me = this,\r
            left, right;\r
\r
        Ext.apply(me, config);\r
\r
        me.left = left = new me.Left(me, me.left);\r
        me.right = right = new me.Right(me, me.right);\r
\r
        left.inverse = right;\r
        right.inverse = left;\r
    },\r
    \r
    hasField: function() {\r
        return !!this.field;    \r
    },\r
    \r
    getFieldName: function() {\r
        var field = this.field;\r
        return field ? field.name : '';\r
    }\r
});\r