[extjs.git] / extjs / packages / core / src / data / Session.js

/**\r
 * This class manages models and their associations. Instances of `Session` are typically\r
 * associated with some `Component` (perhaps the Viewport or a Window) and then used by\r
 * their `{@link Ext.app.ViewModel view models}` to enable data binding.\r
 *\r
 * The primary job of a Session is to manage a collection of records of many different\r
 * types and their associations. This often starts by loading records when requested (via\r
 * bind - see below) and culminates when it is time to save to the server.\r
 *\r
 * Because the Session tracks all records it loads, it ensures that for any given type of\r
 * model, only one record exists with a given `id`. This means that all edits of that\r
 * record are properly targeted at that one instance.\r
 *\r
 * Similarly, when associations are loaded, the `Ext.data.Store` created to hold the\r
 * associated records is tracked by the Session. So all requests for the "OrderItems" of\r
 * a particular Order id will result in the same Store. Adding and removing items from\r
 * that Order then is sure to remain consistent.\r
 *\r
 * # Data\r
 *\r
 * Since the Session is managing all this data, there are several methods it provides\r
 * to give convenient access to that data. The most important of these is `update` and\r
 * `getChanges`.\r
 *\r
 * The `update` and `getChanges` methods both operate on object that contains a summary\r
 * of records and associations and different CRUD operations.\r
 *\r
 * ## Saving\r
 *\r
 * There are two basic ways to save the contents of a Session: `getChanges` and\r
 * `getSaveBatch`. We've already seen `getChanges`. The data contained in the CRUD object\r
 * can be translated into whatever shape is needed by the server.\r
 *\r
 * To leverage the `{@link Ext.data.Model#proxy proxy}` facilities defined by each Model\r
 * class, there is the `getSaveBatch` method. That method returns an `Ext.data.Batch`\r
 * object populated with the necessary `create`, `update` and `destory` operations to\r
 * save all of the changes in the Session.\r
 * \r
 * @since 5.0.0\r
 */\r
Ext.define('Ext.data.Session', {\r
    requires: [\r
        'Ext.data.schema.Schema',\r
        'Ext.data.Batch',\r
        'Ext.data.matrix.Matrix',\r
        'Ext.data.session.ChangesVisitor',\r
        'Ext.data.session.ChildChangesVisitor',\r
        'Ext.data.session.BatchVisitor'\r
    ],\r
\r
    isSession: true,\r
\r
    config: {\r
        /**\r
         * @cfg {String/Ext.data.schema.Schema} schema\r
         */\r
        schema: 'default',\r
\r
        /**\r
         * @cfg {Ext.data.Session} parent\r
         * The parent session for this session.\r
         */\r
        parent: null,\r
\r
        /**\r
         * @cfg {Boolean} autoDestroy\r
         * `true` to automatically destroy this session when a component it is attached\r
         * to is destroyed. This should be set to false if the session is intended to be\r
         * used across multiple root level components.\r
         *\r
         * @since 5.0.1\r
         */\r
        autoDestroy: true,\r
\r
        crudProperties: {\r
            create: 'C',\r
            read:   'R',\r
            update: 'U',\r
            drop:   'D'\r
        }\r
    },\r
\r
    destroyed: false,\r
\r
    crudOperations: [{\r
        type: 'R',\r
        entityMethod: 'readEntities'\r
    }, {\r
        type: 'C',\r
        entityMethod: 'createEntities'\r
    }, {\r
        type: 'U',\r
        entityMethod: 'updateEntities'\r
    }, {\r
        type: 'D',\r
        entityMethod: 'dropEntities'\r
    }],\r
\r
    crudKeys: {\r
        C: 1,\r
        R: 1,\r
        U: 1,\r
        D: 1\r
    },\r
\r
    constructor: function (config) {\r
        var me = this;\r
\r
        /*\r
         * {\r
         *     User: {\r
         *         1: {\r
         *             record: user1Instance,\r
         *             refs: {\r
         *                 posts: {\r
         *                     101: post101Instance,\r
         *                     102: post202Instance\r
         *                 }\r
         *             }\r
         *         }\r
         *     }\r
         * }\r
         */\r
        me.data = {};\r
\r
        /*\r
         *  {\r
         *      UserGroups: new Ext.data.matrix.Matrix({\r
         *          association: UserGroups\r
         *      })\r
         *  }\r
         */\r
        me.matrices = {};\r
\r
        me.identifierCache = {};\r
\r
        // Bind ourselves so we're always called in our own scope.\r
        me.recordCreator = me.recordCreator.bind(me);\r
\r
        me.initConfig(config);\r
    },\r
\r
    destroy: function () {\r
        var me = this,\r
            matrices = me.matrices,\r
            data = me.data,\r
            entityName, entities,\r
            record, id;\r
\r
        for (id in matrices) {\r
            matrices[id].destroy();\r
        }\r
\r
        for (entityName in data) {\r
            entities = data[entityName];\r
            for (id in entities) {\r
                record = entities[id].record;\r
                if (record) {\r
                    // Clear up any source if we pushed one on, remove\r
                    // the session reference\r
                    record.$source = record.session = null;\r
                }\r
            }\r
        }\r
\r
        me.recordCreator = me.matrices = me.data = null;\r
        me.setSchema(null);\r
        me.callParent();\r
    },\r
\r
    /**\r
     * Adds an existing record instance to the session. The record\r
     * may not belong to another session. The record cannot be a phantom record, instead\r
     * use {@link #createRecord}.\r
     * @param {Ext.data.Model} record The record to adopt.\r
     */\r
    adopt: function(record) {\r
        var me = this,\r
            associations = record.associations,\r
            roleName;\r
\r
        //<debug>\r
        me.checkModelType(record.self);\r
        if (record.session && record.session !== me) {\r
            Ext.raise('Record already belongs to an existing session');\r
        }\r
        //</debug>\r
        if (record.session !== me) {\r
            record.session = me;\r
            me.add(record);\r
            if (associations) {\r
                for (roleName in associations) {\r
                    associations[roleName].adoptAssociated(record, me);\r
                }\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Marks the session as "clean" by calling {@link Ext.data.Model#commit} on each record\r
     * that is known to the session.\r
     *\r
     * - Phantom records will no longer be phantom.\r
     * - Modified records will no longer be dirty.\r
     * - Dropped records will be erased.\r
     *\r
     * @since 5.1.0\r
     */\r
    commit: function() {\r
        var data = this.data,\r
            matrices = this.matrices,\r
            entityName, entities, id, record;\r
\r
        for (entityName in data) {\r
            entities = data[entityName];\r
            for (id in entities) {\r
                record = entities[id].record;\r
                if (record) {\r
                    record.commit();\r
                }\r
            }\r
        }\r
\r
        for (id in matrices) {\r
            matrices[id].commit();\r
        }\r
    },\r
\r
    /**\r
     * Creates a new record and tracks it in this session.\r
     *\r
     * @param {String/Ext.Class} type The `entityName` or the actual class of record to create.\r
     * @param {Object} [data] The data for the record.\r
     * @return {Ext.data.Model} The new record.\r
     */\r
    createRecord: function (type, data) {\r
        //<debug>\r
        this.checkModelType(type);\r
        //</debug>\r
        var Model = type.$isClass ? type : this.getSchema().getEntity(type),\r
            parent = this.getParent(),\r
            id;\r
\r
        // If we have no data, we're creating a phantom\r
        if (data && parent) {\r
            id = Model.getIdFromData(data);\r
            if (parent.peekRecord(Model, id)) {\r
                Ext.raise('A parent session already contains an entry for ' + Model.entityName + ': ' + id);\r
            }\r
        }\r
        // By passing the session to the constructor, it will call session.add()\r
        return new Model(data, this);\r
    },\r
\r
    /**\r
     * Returns an object describing all of the modified fields, created or dropped records\r
     * and many-to-many association changes maintained by this session.\r
     *\r
     * @return {Object} An object in the CRUD format (see the intro docs). `null` if there are no changes.\r
     */\r
    getChanges: function () {\r
        var visitor = new Ext.data.session.ChangesVisitor(this);\r
        this.visitData(visitor);\r
        return visitor.result;\r
    },\r
\r
    /**\r
     * The same functionality as {@link #getChanges}, however we also take into account our\r
     * parent session.\r
     * \r
     * @return {Object} An object in the CRUD format (see the intro docs). `null` if there are no changes.\r
     *\r
     * @protected\r
     */\r
    getChangesForParent: function() {\r
        var visitor = new Ext.data.session.ChildChangesVisitor(this);\r
        this.visitData(visitor);\r
        return visitor.result;\r
    },\r
\r
    /**\r
     * Get a cached record from the session. If the record does not exist, it will\r
     * be created. If the `autoLoad` parameter is not set to `false`, the record will\r
     * be loaded via the {@link Ext.data.Model#proxy proxy} of the Model. \r
     * \r
     * If this session is configured with a `{@link #parent}` session, a *copy* of any existing record \r
     * in the `parent` will be adopted into this session. If the `parent` does not contain the record,\r
     * the record will be created and *not* inserted into the parent.\r
     * \r
     * See also {@link #peekRecord}.\r
     *\r
     * @param {String/Ext.Class/Ext.data.Model} type The `entityName` or the actual class of record to create.\r
     * This may also be a record instance, where the type and id will be inferred from the record. If the record is\r
     * not attached to a session, it will be adopted. If it exists in a parent, an appropriate copy will be made as\r
     * described.\r
     * @param {Object} id The id of the record.\r
     * @param {Boolean/Object} [autoLoad=true] `false` to prevent the record from being loaded if\r
     * it does not exist. If this parameter is an object, it will be passed to the {@link Ext.data.Model#load} call.\r
     * @return {Ext.data.Model} The record.\r
     */\r
    getRecord: function(type, id, autoLoad) {\r
        var me = this,\r
            wasInstance = type.isModel,\r
            record, Model, parent, parentRec;\r
\r
        if (wasInstance) {\r
            wasInstance = type;\r
            id = type.id;\r
            type = type.self;\r
        }\r
        record = me.peekRecord(type, id);\r
\r
        if (!record) {\r
            Model = type.$isClass ? type : me.getSchema().getEntity(type);\r
            parent = me.getParent();\r
            if (parent) {\r
                parentRec = parent.peekRecord(Model, id);\r
            }\r
            if (parentRec) {\r
                if (parentRec.isLoading()) {\r
                    // If the parent is loading, it's as though it doesn't have\r
                    // the record, so we can't copy it, but we don't want to\r
                    // adopt it either.\r
                    wasInstance = false;\r
                } else {\r
                    record = parentRec.copy(undefined, me);\r
                    record.$source = parentRec;\r
                }\r
            }\r
\r
            if (!record) {\r
                if (wasInstance) {\r
                    record = wasInstance;\r
                    me.adopt(record);\r
                } else {\r
                    record = Model.createWithId(id, null, me);\r
                    if (autoLoad !== false) {\r
                        record.load(Ext.isObject(autoLoad) ? autoLoad : undefined);\r
                    }\r
                }\r
            }\r
        }\r
        return record;\r
    },\r
\r
    /**\r
     * Returns an `Ext.data.Batch` containing the `Ext.data.operation.Operation` instances\r
     * that are needed to save all of the changes in this session. This sorting is based\r
     * on operation type, associations and foreign keys. Generally speaking the operations\r
     * in the batch can be committed to a server sequentially and the server will never be\r
     * sent a request with an invalid (client-generated) id in a foreign key field.\r
     *\r
     * @param {Boolean} [sort=true] Pass `false` to disable the batch operation sort.\r
     * @return {Ext.data.Batch}\r
     */\r
    getSaveBatch: function (sort) {\r
        var visitor = new Ext.data.session.BatchVisitor();\r
\r
        this.visitData(visitor);\r
\r
        return visitor.getBatch(sort);\r
    },\r
\r
    /**\r
     * Triggered when an associated item from {@link #update} references a record\r
     * that does not exist in the session.\r
     * @param {Ext.Class} entityType The entity type.\r
     * @param {Object} id The id of the model.\r
     *\r
     * @protected\r
     * @template\r
     */\r
    onInvalidAssociationEntity: function(entityType, id) {\r
        Ext.raise('Unable to read association entity: ' + this.getModelIdentifier(entityType, id));\r
    },\r
\r
    /**\r
     * Triggered when an drop block from {@link #update} tries to create a record\r
     * that already exists.\r
     * @param {Ext.Class} entityType The entity type.\r
     * @param {Object} id The id of the model.\r
     *\r
     * @protected\r
     * @template\r
     */\r
    onInvalidEntityCreate: function(entityType, id) {\r
        Ext.raise('Cannot create, record already not exists: ' + this.getModelIdentifier(entityType, id));\r
    },\r
\r
    /**\r
     * Triggered when an drop block from {@link #update} references a record\r
     * that does not exist in the session.\r
     * @param {Ext.Class} entityType The entity type.\r
     * @param {Object} id The id of the model.\r
     *\r
     * @protected\r
     * @template\r
     */\r
    onInvalidEntityDrop: function(entityType, id) {\r
        Ext.raise('Cannot drop, record does not exist: ' + this.getModelIdentifier(entityType, id));\r
    },\r
\r
    /**\r
     * Triggered when an drop block from {@link #update} tries to create a record\r
     * that already exists.\r
     * @param {Ext.Class} entityType The entity type.\r
     * @param {Object} id The id of the model.\r
     *\r
     * @protected\r
     * @template\r
     */\r
    onInvalidEntityRead: function(entityType, id) {\r
        Ext.raise('Cannot read, record already not exists: ' + this.getModelIdentifier(entityType, id));\r
    },\r
\r
    /**\r
     * Triggered when an update block from {@link #update} references a record\r
     * that does not exist in the session.\r
     * @param {Ext.Class} entityType The entity type.\r
     * @param {Object} id The id of the model.\r
     * @param {Boolean} dropped `true` if the record was dropped.\r
     *\r
     * @protected\r
     * @template\r
     */\r
    onInvalidEntityUpdate: function(entityType, id, dropped) {\r
        if (dropped) {\r
            Ext.raise('Cannot update, record dropped: ' + this.getModelIdentifier(entityType, id));\r
        } else {\r
            Ext.raise('Cannot update, record does not exist: ' + this.getModelIdentifier(entityType, id));\r
        }\r
    },\r
\r
    /**\r
     * Gets an existing record from the session. The record will *not* be created if it does\r
     * not exist.\r
     *\r
     * See also: {@link #getRecord}.\r
     * \r
     * @param {String/Ext.Class} type The `entityName` or the actual class of record to create.\r
     * @param {Object} id The id of the record.\r
     * @param {Boolean} [deep=false] `true` to consult \r
     * @return {Ext.data.Model} The record, `null` if it does not exist.\r
     */\r
    peekRecord: function(type, id, deep) {\r
        // Duplicate some of this logic from getEntry here to prevent the creation\r
        // of entries when asking for the existence of records. We may not need them\r
        //<debug>\r
        this.checkModelType(type);\r
        //</debug>\r
        var entityType = type.$isClass ? type : this.getSchema().getEntity(type),\r
            entityName = entityType.entityName,\r
            entry = this.data[entityName],\r
            ret, parent;\r
\r
        entry = entry && entry[id];\r
        ret = entry && entry.record;\r
\r
        if (!ret && deep) {\r
            parent = this.getParent();\r
            ret = parent && parent.peekRecord(type, id, deep);\r
        }\r
        return ret || null;\r
    },\r
\r
    /**\r
     * Save any changes in this session to a {@link #parent} session.\r
     */\r
    save: function() {\r
        //<debug>\r
        if (!this.getParent()) {\r
            Ext.raise('Cannot commit session, no parent exists');\r
        }\r
        //</debug>\r
        var visitor = new Ext.data.session.ChildChangesVisitor(this);\r
        this.visitData(visitor);\r
        this.getParent().update(visitor.result);\r
    },\r
\r
    /**\r
     * Create a child session with this session as the {@link #parent}.\r
     * @return {Ext.data.Session} The copied session.\r
     */\r
    spawn: function () {\r
        return new this.self({\r
            schema: this.getSchema(),\r
            parent: this\r
        });\r
    },\r
\r
    /**\r
     * Complete a bulk update for this session.\r
     * @param {Object} data Data in the CRUD format (see the intro docs).\r
     */\r
    update: function(data) {\r
        var me = this,\r
            schema = me.getSchema(),\r
            crudOperations = me.crudOperations,\r
            len = crudOperations.length,\r
            crudKeys = me.crudKeys,\r
            entityName, entityType, entityInfo, i,\r
            operation, item, associations, key, role, associationData;\r
\r
        // Force the schema to process any pending drops\r
        me.getSchema().processKeyChecks(true);\r
\r
        // Do a first pass to setup all the entities first\r
        for (entityName in data) {\r
            entityType = schema.getEntity(entityName);\r
            //<debug>\r
            if (!entityType) {\r
                Ext.raise('Invalid entity type: ' + entityName);\r
            }\r
            //</debug>\r
            entityInfo = data[entityName];\r
\r
            for (i = 0; i < len; ++i) {\r
                operation = crudOperations[i];\r
                item = entityInfo[operation.type];\r
                if (item) {\r
                    me[operation.entityMethod](entityType, item);\r
                }\r
            }\r
        }\r
\r
        // A second pass to process associations once we have all the entities in place\r
        for (entityName in data) {\r
            entityType = schema.getEntity(entityName);\r
            associations = entityType.associations;\r
            entityInfo = data[entityName];\r
\r
            for (key in entityInfo) {\r
                // Skip over CRUD, just looking for associations here\r
                if (crudKeys[key]) {\r
                    continue;\r
                }\r
                role = associations[key];\r
                //<debug>\r
                if (!role) {\r
                    Ext.raise('Invalid association key for ' + entityName + ', "' + key + '"');\r
                }\r
                //</debug>\r
                associationData = entityInfo[role.role];\r
                role.processUpdate(me, associationData);\r
            }\r
        }\r
    }, \r
\r
    //-------------------------------------------------------------------------\r
    privates: {\r
        /**\r
         * Add a record instance to this session. Called by model.\r
         * @param {Ext.data.Model} record The record.\r
         * \r
         * @private\r
         */\r
        add: function (record) {\r
            var me = this,\r
                id = record.id,\r
                entry = me.getEntry(record.self, id),\r
                associations, roleName;\r
\r
            //<debug>\r
            if (entry.record) {\r
                Ext.raise('Duplicate id ' + record.id + ' for ' + record.entityName);\r
            }\r
            //</debug>\r
\r
            entry.record = record;\r
\r
            me.registerReferences(record);\r
            associations = record.associations;\r
            for (roleName in associations) {\r
                associations[roleName].checkMembership(me, record);\r
            }\r
        },\r
\r
        /**\r
         * Template method, will be called by Model after a record is dropped.\r
         * @param {Ext.data.Model} record The record.\r
         *\r
         * @private\r
         */\r
        afterErase: function(record) {\r
            this.evict(record);\r
        },\r
\r
        /**\r
         * @private\r
         */\r
        applySchema: function (schema) {\r
            return Ext.data.schema.Schema.get(schema);\r
        },\r
\r
        //<debug>\r
        /**\r
         * Checks if the model type being referenced is valid for this session. That includes checking\r
         * if the model name is correct & is one used in this {@link #schema} for this session. Will raise\r
         * an exception if the model type is not correct.\r
         * @param {String/Ext.Class} name The model name or model type.\r
         *\r
         * @private\r
         */\r
        checkModelType: function(name) {\r
            if (name.$isClass) {\r
                name = name.entityName;\r
            }\r
\r
            if (!name) {\r
                Ext.raise('Unable to use anonymous models in a Session');\r
            } else if (!this.getSchema().getEntity(name)) {\r
                Ext.raise('Unknown entity type ' + name);\r
            }\r
        },\r
        //</debug>\r
\r
        /**\r
         * Process a create block of entities from the {@link #update} method.\r
         * @param {Ext.Class} entityType The entity type.\r
         * @param {Object[]} items The data objects to create.\r
         *\r
         * @private\r
         */\r
        createEntities: function(entityType, items) {\r
            var len = items.length,\r
                i, data, rec, id;\r
\r
            for (i = 0; i < len; ++i) {\r
                data = items[i];\r
                id = entityType.getIdFromData(data);\r
                rec = this.peekRecord(entityType, id);\r
                if (!rec) {\r
                    rec = this.createRecord(entityType, data);\r
                } else {\r
                    this.onInvalidEntityCreate(entityType, id);\r
                }\r
                // This record has been marked as being created, so we must\r
                // be a phantom\r
                rec.phantom = true;\r
            }\r
        },\r
\r
        /**\r
         * Process a drop block for entities from the {@link #update} method.\r
         * @param {Ext.Class} entityType The entity type.\r
         * @param {Object[]} ids The identifiers of the items to drop.\r
         *\r
         * @private\r
         */\r
        dropEntities: function(entityType, ids) {\r
            var len = ids.length,\r
                i, rec, id, extractId;\r
\r
            if (len) {\r
                // Handle writeAllFields here, we may not have an array of raw ids\r
                extractId = Ext.isObject(ids[0]);\r
            }\r
\r
            for (i = 0; i < len; ++i) {\r
                id = ids[i];\r
                if (extractId) {\r
                    id = entityType.getIdFromData(id);\r
                }\r
                rec = this.peekRecord(entityType, id);\r
                if (rec) {\r
                    rec.drop();\r
                } else {\r
                    this.onInvalidEntityDrop(entityType, id);\r
                }\r
            }\r
        },\r
\r
        /**\r
         * Remove a record and any references from the session.\r
         * @param {Ext.data.Model} record The record\r
         *\r
         * @private\r
         */\r
        evict: function(record) {\r
            var entityName = record.entityName,\r
                entities = this.data[entityName],\r
                id = record.id,\r
                entry;\r
\r
            if (entities) {\r
                delete entities[id];\r
            }\r
        },\r
\r
        /**\r
         * Transforms a list of ids into a list of records for a particular type.\r
         * @param {Ext.Class} entityType The entity type.\r
         * @param {Object[]} ids The ids to transform.\r
         * @return {Ext.data.Model[]} The models corresponding to the ids.\r
         */\r
        getEntityList: function(entityType, ids) {\r
            var len = ids.length,\r
                i, id, rec, invalid;\r
\r
            for (i = 0; i < len; ++i) {\r
                id = ids[i];\r
                rec = this.peekRecord(entityType, id);\r
                if (rec) {\r
                    ids[i] = rec;\r
                } else {\r
                    invalid = true;\r
                    ids[i] = null;\r
                    this.onInvalidAssociationEntity(entityType, id);\r
                }\r
            }\r
            if (invalid) {\r
                ids = Ext.Array.clean(ids);\r
            }\r
            return ids;\r
        },\r
\r
        /**\r
         * Return an entry for the data property for a particular type/id.\r
         * @param {String/Ext.Class} type The entity name or model type.\r
         * @param {Object} id The id of the record\r
         * @return {Object} The data entry.\r
         *\r
         * @private\r
         */\r
        getEntry: function(type, id) {\r
            if (type.isModel) {\r
                id = type.getId();    \r
                type = type.self;\r
            }\r
\r
            var entityType = type.$isClass ? type : this.getSchema().getEntity(type),\r
                entityName = entityType.entityName,\r
                data = this.data,\r
                entry;\r
\r
            entry = data[entityName] || (data[entityName] = {});\r
            entry = entry[id] || (entry[id] = {});\r
\r
            return entry;\r
        },\r
\r
        getRefs: function(record, role, includeParent) {\r
            var entry = this.getEntry(record),\r
                refs = entry && entry.refs && entry.refs[role.role],\r
                parent = includeParent && this.getParent(),\r
                parentRefs, id, rec;\r
\r
            if (parent) {\r
                parentRefs = parent.getRefs(record, role);\r
                if (parentRefs) {\r
                    for (id in parentRefs) {\r
                        rec = parentRefs[id];\r
                        if ((!refs || !refs[id])) {\r
                            // We don't know about this record but the parent does. We need to\r
                            // pull it down so it may be edited as part of the collection\r
                            this.getRecord(rec.self, rec.id);\r
                        }\r
                    }\r
                    // Recalculate our refs after we pull down all the required records\r
                    refs = entry && entry.refs && entry.refs[role.role];\r
                }\r
            }\r
\r
            return refs || null;\r
        },\r
\r
        getIdentifier: function (entityType) {\r
            var parent = this.getParent(),\r
                cache, identifier, key, ret;\r
\r
            if (parent) {\r
                ret = parent.getIdentifier(entityType);\r
            } else {\r
                cache = this.identifierCache;\r
                identifier = entityType.identifier;\r
                key = identifier.id || entityType.entityName;\r
                ret = cache[key];\r
\r
                if (!ret) {\r
                    if (identifier.clone) {\r
                        ret = identifier.clone({\r
                            cache: cache\r
                        });\r
                    } else {\r
                        ret = identifier;\r
                    }\r
\r
                    cache[key] = ret;\r
                }\r
            }\r
\r
            return ret;\r
        },\r
\r
        getMatrix: function (matrix, preventCreate) {\r
            var name = matrix.isManyToMany ? matrix.name : matrix,\r
                matrices = this.matrices,\r
                ret;\r
\r
            ret = matrices[name];\r
            if (!ret && !preventCreate) {\r
                ret = matrices[name] = new Ext.data.matrix.Matrix(this, matrix);\r
            }\r
            return ret || null;\r
        },\r
\r
        getMatrixSlice: function (role, id) {\r
            var matrix = this.getMatrix(role.association),\r
                side = matrix[role.side];\r
\r
            return side.get(id);\r
        },\r
\r
        /**\r
         * Gets a user friendly identifier for a Model.\r
         * @param {Ext.Class} entityType The entity type.\r
         * @param {Object} id The id of the entity.\r
         * @return {String} The identifier.\r
         */\r
        getModelIdentifier: function(entityType, id) {\r
            return id + '@' + entityType.entityName;\r
        },\r
\r
        onIdChanged: function (record, oldId, newId) {\r
            var me = this,\r
                matrices = me.matrices,\r
                entityName = record.entityName,\r
                id = record.id,\r
                bucket = me.data[entityName],\r
                entry = bucket[oldId],\r
                associations = record.associations,\r
                refs = entry.refs,\r
                setNoRefs = me._setNoRefs,\r
                association, fieldName, matrix, refId, role, roleName, roleRefs, key;\r
\r
            //<debug>\r
            if (bucket[newId]) {\r
                Ext.raise('Cannot change ' + entityName + ' id from ' + oldId +\r
                                ' to ' + newId + ' id already exists');\r
            }\r
            //</debug>\r
\r
            delete bucket[oldId];\r
            bucket[newId] = entry;\r
\r
            for (key in matrices) {\r
                matrices[key].updateId(record, oldId, newId);\r
            }\r
\r
            if (refs) {\r
                for (roleName in refs) {\r
                    roleRefs = refs[roleName];\r
                    role = associations[roleName];\r
                    association = role.association;\r
\r
                    if (!association.isManyToMany) {\r
                        fieldName = association.field.name;\r
\r
                        for (refId in roleRefs) {\r
                            roleRefs[refId].set(fieldName, id, setNoRefs);\r
                        }\r
                    }\r
                }\r
            }\r
\r
            me.registerReferences(record, oldId);\r
        },\r
\r
        processManyBlock: function(entityType, role, items, processor) {\r
            var me = this,\r
                id, record, records, store;\r
\r
            if (items) {\r
                for (id in items) {\r
                    record = me.peekRecord(entityType, id);\r
                    if (record) {\r
                        records = me.getEntityList(role.cls, items[id]);\r
                        store = role.getAssociatedItem(record);\r
                        me[processor](role, store, record, records);\r
                    } else {\r
                        me.onInvalidAssociationEntity(entityType, id);\r
                    }\r
                }\r
            }\r
        },\r
\r
        processManyCreate: function(role, store, record, records) {\r
            if (store) {\r
                // Will handle any duplicates\r
                store.add(records);\r
            } else {\r
                record[role.getterName](null, null, records);\r
            }\r
                 \r
        },\r
\r
        processManyDrop: function(role, store, record, records) {\r
            if (store) {\r
                store.remove(records);\r
            }\r
        },\r
\r
        processManyRead: function(role, store, record, records) {\r
            if (store) {\r
                store.setRecords(records);\r
            } else {\r
                // We don't have a store. Create it and add the records.\r
                record[role.getterName](null, null, records);\r
            }\r
        },\r
\r
        /**\r
         * Process a read block of entities from the {@link #update} method.\r
         * @param {Ext.Class} entityType The entity type.\r
         * @param {Object[]} items The data objects to read.\r
         *\r
         * @private\r
         */\r
        readEntities: function(entityType, items) {\r
            var len = items.length,\r
                i, data, rec, id;\r
\r
            for (i = 0; i < len; ++i) {\r
                data = items[i];\r
                id = entityType.getIdFromData(data);\r
                rec = this.peekRecord(entityType, id);\r
                if (!rec) {\r
                    rec = this.createRecord(entityType, data);\r
                } else {\r
                    this.onInvalidEntityRead(entityType, id);\r
                }\r
                // We've been read from a "server", so we aren't a phantom,\r
                // regardless of whether or not we have an id\r
                rec.phantom = false;\r
            }\r
        },\r
\r
        recordCreator: function (data, Model) {\r
            var me = this,\r
                id = Model.getIdFromData(data),\r
                record = me.peekRecord(Model, id, true);\r
\r
            // It doesn't exist anywhere, create it\r
            if (!record) {\r
                // We may have a stub that is loading the record (in fact this may be the\r
                // call coming from that Reader), but the resolution is simple. By creating\r
                // the record it is registered in the data[entityName][id] entry anyway\r
                // and the stub will deal with it onLoad.\r
                record = new Model(data, me);\r
            } else {\r
                //TODO no easy answer here... we are trying to create a record and have\r
                //TODO some (potentially new) data. We probably should check for mid-air\r
                //TODO collisions using versionProperty but for now we just ignore the\r
                //TODO new data in favor of our potentially edited data.\r
                \r
                // Peek checks if it exists at any level, by getting it we ensure that the record is copied down\r
                record = me.getRecord(Model, id);\r
            }\r
\r
            return record;\r
        },\r
\r
        registerReferences: function (record, oldId) {\r
            var entityName = record.entityName,\r
                id = record.id,\r
                recordData = record.data,\r
                remove = oldId || oldId === 0,\r
                entry, i, fk, len, reference, references, refs, roleName;\r
\r
            // Register this records references to other records\r
            len = (references = record.references).length;\r
\r
            for (i = 0; i < len; ++i) {\r
                reference = references[i];  // e.g., an orderId field\r
                fk = recordData[reference.name];  // the orderId\r
\r
                if (fk || fk === 0) {\r
                    reference = reference.reference; // the "order" association role\r
                    entityName = reference.type;\r
                    roleName = reference.inverse.role;\r
\r
                    // Track down the entry for the associated record\r
                    entry = this.getEntry(reference.cls, fk);\r
                    refs = entry.refs || (entry.refs = {});\r
                    refs = refs[roleName] || (refs[roleName] = {});\r
\r
                    refs[id] = record;\r
                    if (remove) {\r
                        delete refs[oldId];\r
                    }\r
                }\r
            }\r
        },\r
\r
        /**\r
         * Process an update block for entities from the {@link #update} method.\r
         * @param {Ext.Class} entityType The entity type.\r
         * @param {Object[]} items The data objects to update.\r
         *\r
         * @private\r
         */\r
        updateEntities: function(entityType, items) {\r
            var len = items.length,\r
                i, data, rec, id, modified;\r
\r
            // Repeating some code here, but we want to optimize this for speed\r
            if (Ext.isArray(items)) {\r
                for (i = 0; i < len; ++i) {\r
                    data = items[i];\r
                    id = entityType.getIdFromData(data);\r
                    rec = this.peekRecord(entityType, id);\r
                    if (rec) {\r
                        rec.set(data);\r
                    } else {\r
                        this.onInvalidEntityUpdate(entityType, id);\r
                    }\r
                }\r
            } else {\r
                for (id in items) {\r
                    data = items[id];\r
                    rec = this.peekRecord(entityType, id);\r
                    if (rec && !rec.dropped) {\r
                        modified = rec.set(data);\r
                    } else {\r
                        this.onInvalidEntityUpdate(entityType, id, !!rec);\r
                    }\r
                }\r
            }\r
        },\r
\r
        updateReference: function (record, field, newValue, oldValue) {\r
            var reference = field.reference,\r
                entityName = reference.type,\r
                roleName = reference.inverse.role,\r
                id = record.id,\r
                entry, refs;\r
\r
            if (oldValue || oldValue === 0) {\r
                // We must be already in this entry.refs collection\r
                refs = this.getEntry(entityName, oldValue).refs[roleName];\r
                delete refs[id];\r
            }\r
\r
            if (newValue || newValue === 0) {\r
                entry = this.getEntry(entityName, newValue);\r
                refs = entry.refs || (entry.refs = {});\r
                refs = refs[roleName] || (refs[roleName] = {});\r
                refs[id] = record;\r
            }\r
        },\r
\r
        /**\r
         * Walks the internal data tracked by this session and calls methods on the provided\r
         * `visitor` object. The visitor can then accumulate whatever data it finds important.\r
         * The visitor object can provide a number of methods, but all are optional.\r
         *\r
         * This method does not enumerate associations since these can be traversed given the\r
         * records that are enumerated. For many-to-many associations, however, this method\r
         * does enumerate the changes because these changes are not "owned" by either side of\r
         * such associations.\r
         *\r
         * @param {Object} visitor\r
         * @param {Function} [visitor.onCleanRecord] This method is called to describe a record\r
         * that is known but unchanged.\r
         * @param {Ext.data.Model} visitor.onCleanRecord.record The unmodified record.\r
         * @param {Function} [visitor.onDirtyRecord] This method is called to describe a record\r
         * that has either been created, dropped or modified.\r
         * @param {Ext.data.Model} visitor.onDirtyRecord.record The modified record.\r
         * @param {Function} [visitor.onMatrixChange] This method is called to describe a\r
         * change in a many-to-many association (a "matrix").\r
         * @param {Ext.data.schema.Association} visitor.onMatrixChange.association The object\r
         * describing the many-to-many ("matrix") association.\r
         * @param {Mixed} visitor.onMatrixChange.leftId The `idProperty` of the record on the\r
         * "left" of the association.\r
         * @param {Mixed} visitor.onMatrixChange.rightId The `idProperty` of the record on the\r
         * "right" of the association.\r
         * @param {Number} visitor.onMatrixChange.state A negative number if the two records\r
         * are being disassociated or a positive number if they are being associated. For\r
         * example, when adding User 10 to Group 20, this would be 1. When removing the User\r
         * this argument would be -1.\r
         * @return {Object} The visitor instance\r
         */\r
        visitData: function (visitor) {\r
            var me = this,\r
                data = me.data,\r
                matrices = me.matrices,\r
                all, assoc, id, id2, matrix, members, name, record, slice, slices, state;\r
\r
            // Force the schema to process any pending drops\r
            me.getSchema().processKeyChecks(true);\r
\r
            for (name in data) {\r
                all = data[name];  // all entities of type "name"\r
\r
                for (id in all) {\r
                    record = all[id].record;\r
\r
                    if (record) {\r
                        if (record.phantom || record.dirty || record.dropped) {\r
                            if (visitor.onDirtyRecord) {\r
                                visitor.onDirtyRecord(record);\r
                            }\r
                        } else if (visitor.onCleanRecord) {\r
                            visitor.onCleanRecord(record);\r
                        }\r
                    }\r
                }\r
            }\r
\r
            if (visitor.onMatrixChange) {\r
                for (name in matrices) {\r
                    matrix = matrices[name].left;  // e.g., UserGroups.left (Users)\r
                    slices = matrix.slices;\r
                    assoc = matrix.role.association;\r
\r
                    for (id in slices) {\r
                        slice = slices[id];\r
                        members = slice.members;\r
\r
                        for (id2 in members) {\r
                            state = (record = members[id2])[2];\r
\r
                            if (state) {\r
                                visitor.onMatrixChange(assoc, record[0], record[1], state);\r
                            }\r
                        }\r
                    }\r
                }\r
            }\r
\r
            return visitor;\r
        },\r
\r
        //---------------------------------------------------------------------\r
        // Record callbacks called because we are the "session" for the record.\r
\r
        _setNoRefs: {\r
            refs: false\r
        }\r
    }\r
});\r