add extjs 6.0.1 sources

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

/**\r
 * This type of association describes the case where one entity is referenced by zero or\r
 * more other entities typically using a "foreign key" field.\r
 * \r
 * The way this is defined is for one entity to have a field that holds the unique id (also\r
 * known as "Primary Key" or, more specifically, as the {@link Ext.data.Model#idProperty}\r
 * field) of the related entity. These fields have a {@link Ext.data.field.Field#reference}\r
 * in their definition. The value in the `reference` field of an entity instance holds the\r
 * value of the id of the related entity instance. Since many entities can hold the same\r
 * value in a `reference` field, this allows many entities to reference one entity.\r
 * OrderItem has a foreign key to Order.\r
 * \r
 *      OrderItem -> Order\r
 * \r
 * OrderItem is on the "left" and Order is on the "right". This is because the owner of\r
 * the foreign key is always on the "left". Many OrderItems refer to one Order. The\r
 * default name of this association would be "Order_OrderItems".\r
 * \r
 *      var Order_OrderItems = {\r
 *          name: 'Order_OrderItems',\r
 *          owner: Order_OrderItems.right,\r
 *          left: {\r
 *              cls: OrderItem,\r
 *              type: 'OrderItem',\r
 *              association: Order_OrderItems,\r
 *              left: true,\r
 *              owner: false,\r
 *              autoLoad: true,\r
 *              isMany: true,\r
 *              inverse: Order_OrderItems.right,\r
 *              role: 'orderItems'\r
 *          },\r
 *          right: {\r
 *              cls: Order,\r
 *              type: 'Order',\r
 *              association: Order_OrderItems,\r
 *              left: false,\r
 *              owner: true,\r
 *              autoLoad: true,\r
 *              isMany: false,\r
 *              inverse: Order_OrderItems.left,\r
 *              role: 'order'\r
 *          }\r
 *      };\r
 *      \r
 *      OrderItem.associations.order = Order_OrderItems.left;\r
 *      Order.associations.orderItems = Order_OrderItems.right;\r
 */\r
Ext.define('Ext.data.schema.ManyToOne', {\r
    extend: 'Ext.data.schema.Association',\r
\r
    isManyToOne: true,\r
\r
    isToOne: true,\r
\r
    kind: 'many-to-one',\r
\r
    Left: Ext.define(null, {\r
        extend: 'Ext.data.schema.Role',\r
\r
        isMany: true,\r
\r
        onDrop: function(rightRecord, session) {\r
            var me = this,\r
                store = me.getAssociatedItem(rightRecord),\r
                leftRecords, len, i, refs, id;\r
\r
            if (store) {\r
                // Removing will cause the foreign key to be set to null.\r
                leftRecords = store.removeAll();\r
                if (leftRecords && me.inverse.owner) {\r
                    // If we're a child, we need to destroy all the "tickets"\r
                    for (i = 0, len = leftRecords.length; i < len; ++i) {\r
                        leftRecords[i].drop();\r
                    }\r
                }\r
\r
                store.destroy();\r
                rightRecord[me.getStoreName()] = null;\r
            } else if (session) {\r
                leftRecords = session.getRefs(rightRecord, me);\r
                if (leftRecords) {\r
                    for (id in leftRecords) {\r
                        leftRecords[id].drop();\r
                    }\r
                }\r
            }\r
        },\r
\r
        processUpdate: function(session, associationData) {\r
            var me = this,\r
                entityType = me.inverse.cls,\r
                items = associationData.R,\r
                id, rightRecord, store, leftRecords;\r
\r
            if (items) {\r
                for (id in items) {\r
                    rightRecord = session.peekRecord(entityType, id);\r
                    if (rightRecord) {\r
                        leftRecords = session.getEntityList(me.cls, items[id]);\r
                        store = me.getAssociatedItem(rightRecord);\r
                        if (store) {\r
                            store.loadData(leftRecords);\r
                            store.complete = true;\r
                        } else {\r
                            // We don't have a store. Create it and add the records.\r
                            rightRecord[me.getterName](null, null, leftRecords);\r
                        }\r
                    } else {\r
                        session.onInvalidAssociationEntity(entityType, id);\r
                    }\r
                }\r
            }\r
        },\r
\r
        findRecords: function(session, rightRecord, leftRecords, allowInfer) {\r
            var ret = leftRecords,\r
                refs = session.getRefs(rightRecord, this, true),\r
                field = this.association.field,\r
                fieldName = field.name,\r
                leftRecord, id, i, len, seen;\r
\r
            if (!rightRecord.phantom) {\r
                ret = [];\r
                if (refs || allowInfer) {\r
                    if (leftRecords) {\r
                        seen = {};\r
                        // Loop over the records returned by the server and\r
                        // check they all still belong. If the session doesn't have any prior knowledge\r
                        // and we're allowed to infer the parent id (via nested loading), only do so if\r
                        // we explicitly have an id specified\r
                        for (i = 0, len = leftRecords.length; i < len; ++i) {\r
                            leftRecord = leftRecords[i];\r
                            id = leftRecord.id;\r
                            if (refs && refs[id]) {\r
                                ret.push(leftRecord);\r
                            } else if (allowInfer && leftRecord.data[fieldName] === undefined) {\r
                                ret.push(leftRecord);\r
                                leftRecord.data[fieldName] = rightRecord.id;\r
                                session.updateReference(leftRecord, field, rightRecord.id, undefined);\r
                            }\r
                            seen[id] = true;\r
                        }\r
                    }\r
\r
                    // Loop over the expected set and include any missing records.\r
                    if (refs) {\r
                        for (id in refs) {\r
                            if (!seen || !seen[id]) {\r
                                ret.push(refs[id]);\r
                            }\r
                        }\r
                    }\r
                }\r
            }\r
            return ret;\r
        },\r
\r
        processLoad: function(store, rightRecord, leftRecords, session) {\r
            var ret = leftRecords;\r
\r
            if (session) {\r
                // Allow infer here, we only get called when loading an associated store\r
                ret = this.findRecords(session, rightRecord, leftRecords, true);\r
            }\r
            this.onLoadMany(rightRecord, ret, session);\r
            return ret;\r
        },\r
\r
        adoptAssociated: function(rightRecord, session) {\r
            var store = this.getAssociatedItem(rightRecord),\r
                leftRecords, i, len;\r
            if (store) {\r
                store.setSession(session);\r
                leftRecords = store.getData().items;\r
                for (i = 0, len = leftRecords.length; i < len; ++i) {\r
                    session.adopt(leftRecords[i]);\r
                }\r
            }\r
        },\r
\r
        createGetter: function() {\r
            var me = this;\r
            return function (options, scope, leftRecords) {\r
                // 'this' refers to the Model instance inside this function\r
                return me.getAssociatedStore(this, options, scope, leftRecords, me, true);\r
            };\r
        },\r
\r
        createSetter: null, // no setter for an isMany side\r
\r
        onAddToMany: function (store, leftRecords) {\r
            this.syncFK(leftRecords, store.getAssociatedEntity(), false);\r
        },\r
\r
        onLoadMany: function(rightRecord, leftRecords, session) {\r
            var instanceName = this.inverse.getInstanceName(),\r
                id = rightRecord.getId(),\r
                field = this.association.field,\r
                i, len, leftRecord, oldId, data, name;\r
\r
            if (field) {\r
                for (i = 0, len = leftRecords.length; i < len; ++i) {\r
                    leftRecord = leftRecords[i];\r
                    leftRecord[instanceName] = rightRecord;\r
                    if (field) {\r
                        name = field.name;\r
                        data = leftRecord.data;\r
                        oldId = data[name];\r
                        if (oldId !== id) {\r
                            data[name] = id;\r
                            if (session) {\r
                                session.updateReference(leftRecord, field, id, oldId);\r
                            }\r
                        }\r
                    }\r
                }\r
            }\r
        },\r
\r
        onRemoveFromMany: function (store, leftRecords) {\r
            this.syncFK(leftRecords, store.getAssociatedEntity(), true);\r
        },\r
\r
        read: function(rightRecord, node, fromReader, readOptions) {\r
            var me = this,\r
                // We use the inverse role here since we're setting ourselves\r
                // on the other record\r
                instanceName = me.inverse.getInstanceName(),\r
                leftRecords = me.callParent([rightRecord, node, fromReader, readOptions]),\r
                store, len, i;\r
            \r
            if (leftRecords) {\r
                // Create the store and dump the data\r
                store = rightRecord[me.getterName](null, null, leftRecords);\r
                // Inline associations should *not* arrive on the "data" object:\r
                delete rightRecord.data[me.role];\r
\r
                leftRecords = store.getData().items;\r
\r
                for (i = 0, len = leftRecords.length; i < len; ++i) {\r
                    leftRecords[i][instanceName] = rightRecord;\r
                }\r
            }\r
        },\r
\r
        syncFK: function (leftRecords, rightRecord, clearing) {\r
            // We are called to set things like the FK (ticketId) of an array of Comment\r
            // entities. The best way to do that is call the setter on the Comment to set\r
            // the Ticket. Since we are setting the Ticket, the name of that setter is on\r
            // our inverse role.\r
\r
            var foreignKeyName = this.association.getFieldName(),\r
                inverse = this.inverse,\r
                setter = inverse.setterName, // setTicket\r
                instanceName = inverse.getInstanceName(),\r
                i = leftRecords.length,\r
                id = rightRecord.getId(),\r
                different, leftRecord, val;\r
\r
            while (i-- > 0) {\r
                leftRecord = leftRecords[i];\r
                different = !leftRecord.isEqual(id, leftRecord.get(foreignKeyName));\r
\r
                val = clearing ? null : rightRecord;\r
                if (different !== clearing) {\r
                    // clearing === true\r
                    //      different === true  :: leave alone (not associated anymore)\r
                    //   ** different === false :: null the value (no longer associated)\r
                    //\r
                    // clearing === false\r
                    //   ** different === true  :: set the value (now associated)\r
                    //      different === false :: leave alone (already associated)\r
                    //\r
                    leftRecord.changingKey = true;\r
                    leftRecord[setter](val);\r
                    leftRecord.changingKey = false;\r
                } else {\r
                    // Ensure we set the instance, we may only have the key\r
                    leftRecord[instanceName] = val;\r
                }\r
            }\r
        }\r
    }),\r
\r
    Right: Ext.define(null, {\r
        extend: 'Ext.data.schema.Role',\r
\r
        left: false,\r
        side: 'right',\r
\r
        onDrop: function(leftRecord, session) {\r
            // By virtue of being dropped, this record will be removed\r
            // from any stores it belonged to. The only case we have\r
            // to worry about is if we have a session but were not yet\r
            // part of any stores, so we need to clear the foreign key.\r
            var field = this.association.field;\r
            if (field) {\r
                leftRecord.set(field.name, null);\r
            }\r
            leftRecord[this.getInstanceName()] = null;\r
        },\r
\r
        createGetter: function() {\r
            // As the target of the FK (say "ticket" for the Comment entity) this\r
            // getter is responsible for getting the entity referenced by the FK value.\r
            var me = this;\r
\r
            return function (options, scope) {\r
                // 'this' refers to the Comment instance inside this function\r
                return me.doGetFK(this, options, scope);\r
            };\r
        },\r
        \r
        createSetter: function() {\r
            var me = this;\r
\r
            return function (rightRecord, options, scope) {\r
                // 'this' refers to the Comment instance inside this function\r
                return me.doSetFK(this, rightRecord, options, scope);\r
            };\r
        },\r
\r
        checkMembership: function(session, leftRecord) {\r
            var field = this.association.field,\r
                store;\r
\r
            store = this.getSessionStore(session, leftRecord.get(field.name));\r
            // Check we're not in the middle of an add to the store.\r
            if (store && !store.contains(leftRecord)) {\r
                store.add(leftRecord);\r
            }\r
        },\r
\r
        onValueChange: function(leftRecord, session, newValue, oldValue) {\r
            // If we have a session, we may be able to find the new store this belongs to\r
            // If not, the best we can do is to remove the record from the associated store/s.\r
            var me = this,\r
                instanceName = me.getInstanceName(),\r
                cls = me.cls,\r
                hasNewValue,\r
                joined, store, i, len, associated, rightRecord;\r
\r
            if (!leftRecord.changingKey) {\r
                hasNewValue = newValue || newValue === 0;\r
                if (!hasNewValue) {\r
                    leftRecord[instanceName] = null;\r
                }\r
                if (session) {\r
                    // Find the store that holds this record and remove it if possible.\r
                    store = me.getSessionStore(session, oldValue);\r
                    if (store) {\r
                        store.remove(leftRecord);\r
                    }\r
                    // If we have a new value, try and find it and push it into the new store.\r
                    if (hasNewValue) {\r
                        store = me.getSessionStore(session, newValue);\r
                        if (store && !store.isLoading()) {\r
                            store.add(leftRecord);\r
                        }\r
                        if (cls) {\r
                            rightRecord = session.peekRecord(cls, newValue);\r
                        }\r
                        // Setting to undefined is important so that we can load the record later.\r
                        leftRecord[instanceName] = rightRecord || undefined;\r
                    }\r
                } else {\r
                    joined = leftRecord.joined;\r
                    if (joined) {\r
                        for (i = 0, len = joined.length; i < len; ++i) {\r
                            store = joined[i];\r
                            if (store.isStore) {\r
                                associated = store.getAssociatedEntity();\r
                                if (associated && associated.self === me.cls && associated.getId() === oldValue) {\r
                                    store.remove(leftRecord);\r
                                }\r
                            }\r
                        }\r
                    }\r
                }\r
            }\r
\r
            if (me.owner && newValue === null) {\r
                me.association.schema.queueKeyCheck(leftRecord, me);\r
            }\r
        },\r
\r
        checkKeyForDrop: function(leftRecord) {\r
            var field = this.association.field;\r
            if (leftRecord.get(field.name) === null) {\r
                leftRecord.drop();\r
            }\r
        },\r
\r
        getSessionStore: function(session, value) {\r
            // May not have the cls loaded yet\r
            var cls = this.cls,\r
                rec;\r
\r
            if (cls) {\r
                rec = session.peekRecord(cls, value);\r
\r
                if (rec) {\r
                    return this.inverse.getAssociatedItem(rec);\r
                }\r
            }\r
        },\r
        \r
        read: function(leftRecord, node, fromReader, readOptions) {\r
            var rightRecords = this.callParent([leftRecord, node, fromReader, readOptions]),\r
                rightRecord;\r
\r
            if (rightRecords) {\r
                rightRecord = rightRecords[0];\r
                if (rightRecord) {\r
                    leftRecord[this.getInstanceName()] = rightRecord;\r
                    delete leftRecord.data[this.role];\r
                }\r
            }\r
        }\r
    })\r
});\r