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

/**\r
 * ProxyStore is a superclass of {@link Ext.data.Store} and {@link Ext.data.BufferedStore}. It's never used directly,\r
 * but offers a set of methods used by both of those subclasses.\r
 *\r
 * We've left it here in the docs for reference purposes, but unless you need to make a whole new type of Store, what\r
 * you're probably looking for is {@link Ext.data.Store}. If you're still interested, here's a brief description of what\r
 * ProxyStore is and is not.\r
 *\r
 * ProxyStore provides the basic configuration for anything that can be considered a Store. It expects to be\r
 * given a {@link Ext.data.Model Model} that represents the type of data in the Store. It also expects to be given a\r
 * {@link Ext.data.proxy.Proxy Proxy} that handles the loading of data into the Store.\r
 *\r
 * ProxyStore provides a few helpful methods such as {@link #method-load} and {@link #sync}, which load and save data\r
 * respectively, passing the requests through the configured {@link #proxy}.\r
 *\r
 * Built-in Store subclasses add extra behavior to each of these functions. Note also that each ProxyStore subclass\r
 * has its own way of storing data - in {@link Ext.data.Store} the data is saved as a flat {@link Ext.util.Collection Collection},\r
 * whereas in {@link Ext.data.BufferedStore BufferedStore} we use a {@link Ext.data.PageMap} to maintain a client side cache of pages of records.\r
 *\r
 * The store provides filtering and sorting support. This sorting/filtering can happen on the client side\r
 * or can be completed on the server. This is controlled by the {@link Ext.data.Store#remoteSort remoteSort} and\r
 * {@link Ext.data.Store#remoteFilter remoteFilter} config options. For more information see the {@link #method-sort} and\r
 * {@link Ext.data.Store#filter filter} methods.\r
 */\r
Ext.define('Ext.data.ProxyStore', {\r
    extend: 'Ext.data.AbstractStore',\r
\r
    requires: [\r
        'Ext.data.Model',\r
        'Ext.data.proxy.Proxy',\r
        'Ext.data.proxy.Memory',\r
        'Ext.data.operation.*'\r
    ],\r
\r
    config: {\r
        // @cmd-auto-dependency {aliasPrefix: "model.", mvc: true, blame: "all"}\r
        /**\r
         * @cfg {String/Ext.data.Model} model\r
         * Name of the {@link Ext.data.Model Model} associated with this store. See\r
         * {@link Ext.data.Model#entityName}.\r
         *\r
         * May also be the actual Model subclass.\r
         *\r
         * This config is required for the store to be able to read data unless you have defined\r
         * the {@link #fields} config which will create an anonymous `Ext.data.Model`.\r
         */\r
        model: undefined,\r
\r
        // @cmd-auto-dependency {aliasPrefix: "data.field."}\r
        /**\r
         * @cfg {Object[]/String[]} fields\r
         * @inheritdoc Ext.data.Model#cfg-fields\r
         * \r
         * @localdoc **Note:** In general, this configuration option should only be used \r
         * for simple stores like a two-field store of \r
         * {@link Ext.form.field.ComboBox ComboBox}. For anything more complicated, such \r
         * as specifying a particular id property or associations, a \r
         * {@link Ext.data.Model Model} should be defined and specified for the \r
         * {@link #model} config.\r
         * \r
         * @since 2.3.0\r
         */\r
        fields: null,\r
\r
        // @cmd-auto-dependency {aliasPrefix : "proxy."}\r
        /**\r
         * @cfg {String/Ext.data.proxy.Proxy/Object} proxy\r
         * The Proxy to use for this Store. This can be either a string, a config object or a Proxy instance -\r
         * see {@link #setProxy} for details.\r
         * @since 1.1.0\r
         */\r
        proxy: undefined,\r
\r
        /**\r
         * @cfg {Boolean/Object} autoLoad\r
         * If data is not specified, and if autoLoad is true or an Object, this store's load method is automatically called\r
         * after creation. If the value of autoLoad is an Object, this Object will be passed to the store's load method.\r
         *\r
         * It's important to note that {@link Ext.data.TreeStore Tree Stores} will  \r
         * load regardless of autoLoad's value if expand is set to true on the \r
         * {@link Ext.data.TreeStore#root root node}.\r
         * \r
         * @since 2.3.0\r
         */\r
        autoLoad: undefined,\r
\r
        /**\r
         * @cfg {Boolean} autoSync\r
         * True to automatically sync the Store with its Proxy after every edit to one of its Records. Defaults to false.\r
         */\r
        autoSync: false,\r
\r
        /**\r
         * @cfg {String} batchUpdateMode\r
         * Sets the updating behavior based on batch synchronization. 'operation' (the default) will update the Store's\r
         * internal representation of the data after each operation of the batch has completed, 'complete' will wait until\r
         * the entire batch has been completed before updating the Store's data. 'complete' is a good choice for local\r
         * storage proxies, 'operation' is better for remote proxies, where there is a comparatively high latency.\r
         */\r
        batchUpdateMode: 'operation',\r
       \r
        /**\r
         * @cfg {Boolean} sortOnLoad\r
         * If true, any sorters attached to this Store will be run after loading data, before the datachanged event is fired.\r
         * Defaults to true, ignored if {@link Ext.data.Store#remoteSort remoteSort} is true\r
         */\r
        sortOnLoad: true,\r
\r
        /**\r
         * @cfg {Boolean} [trackRemoved=true]\r
         * This config controls whether removed records are remembered by this store for\r
         * later saving to the server.\r
         */\r
        trackRemoved: true,\r
\r
        /**\r
         * @cfg {Boolean} [asynchronousLoad]\r
         * This defaults to `true` when this store's {@link #cfg-proxy} is asynchronous, such as an\r
         * {@link Ext.data.proxy.Ajax Ajax proxy}.\r
         *\r
         * When the proxy is synchronous, such as a {@link Ext.data.proxy.Memory} memory proxy, this\r
         * defaults to `false`.\r
         *\r
         * *NOTE:* This does not cause synchronous Ajax requests if configured `false` when an Ajax proxy\r
         * is used. It causes immediate issuing of an Ajax request when {@link #method-load} is called\r
         * rather than issuing the request at the end of the current event handler run.\r
         *\r
         * What this means is that when using an Ajax proxy, calls to \r
         * {@link #method-load} do not fire the request to the remote resource \r
         * immediately, but schedule a request to be made. This is so that multiple \r
         * requests are not fired when mutating a store's remote filters and sorters (as \r
         * happens during state restoration). The request is made only once after all \r
         * relevant store state is fully set.\r
         *\r
         * @since 6.0.1\r
         */\r
        asynchronousLoad: undefined\r
    },\r
\r
    onClassExtended: function(cls, data, hooks) {\r
        var model = data.model,\r
            onBeforeClassCreated;\r
\r
        if (typeof model === 'string') {\r
            onBeforeClassCreated = hooks.onBeforeCreated;\r
\r
            hooks.onBeforeCreated = function() {\r
                var me = this,\r
                    args = arguments;\r
\r
                Ext.require(model, function() {\r
                    onBeforeClassCreated.apply(me, args);\r
                });\r
            };\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     * @property {Boolean}\r
     * The class name of the model that this store uses if no explicit {@link #model} is given\r
     */\r
    implicitModel: 'Ext.data.Model',\r
\r
    /**\r
     * @property {Object} lastOptions\r
     * Property to hold the last options from a {@link #method-load} method call. This object is used for the {@link #method-reload}\r
     * to reuse the same options. Please see {@link #method-reload} for a simple example on how to use the lastOptions property.\r
     */\r
\r
    /**\r
     * @property {Number} autoSyncSuspended\r
     * A counter to track suspensions.\r
     * @private\r
     */\r
    autoSyncSuspended: 0,\r
\r
    //documented above\r
    constructor: function(config) {\r
        var me = this;\r
\r
        // <debug>\r
        var configModel = me.model;\r
        // </debug>\r
\r
        /**\r
         * @event beforeload\r
         * Fires before a request is made for a new data object. If the beforeload handler returns false the load\r
         * action will be canceled.\r
         * @param {Ext.data.Store} store This Store\r
         * @param {Ext.data.operation.Operation} operation The Ext.data.operation.Operation object that will be passed to the Proxy to\r
         * load the Store\r
         * @since 1.1.0\r
         */\r
\r
        /**\r
         * @event load\r
         * Fires whenever the store reads data from a remote data source.\r
         * @param {Ext.data.Store} this\r
         * @param {Ext.data.Model[]} records An array of records\r
         * @param {Boolean} successful True if the operation was successful.\r
         * @param {Ext.data.operation.Read} operation The \r
         * {@link Ext.data.operation.Read Operation} object that was used in the data \r
         * load call\r
         * @since 1.1.0\r
         */\r
\r
        /**\r
         * @event write\r
         * Fires whenever a successful write has been made via the configured {@link #proxy Proxy}\r
         * @param {Ext.data.Store} store This Store\r
         * @param {Ext.data.operation.Operation} operation The {@link Ext.data.operation.Operation Operation} object that was used in\r
         * the write\r
         * @since 3.4.0\r
         */\r
\r
        /**\r
         * @event beforesync\r
         * Fired before a call to {@link #sync} is executed. Return false from any listener to cancel the sync\r
         * @param {Object} options Hash of all records to be synchronized, broken down into create, update and destroy\r
         */\r
\r
        /**\r
         * @event metachange\r
         * Fires when this store's underlying reader (available via the proxy) provides new metadata.\r
         * Metadata usually consists of new field definitions, but can include any configuration data\r
         * required by an application, and can be processed as needed in the event handler.\r
         * This event is currently only fired for JsonReaders.\r
         * @param {Ext.data.Store} this\r
         * @param {Object} meta The JSON metadata\r
         * @since 1.1.0\r
         */\r
\r
\r
        /**\r
         * Temporary cache in which removed model instances are kept until successfully\r
         * synchronised with a Proxy, at which point this is cleared.\r
         *\r
         * This cache is maintained unless you set `trackRemoved` to `false`.\r
         *\r
         * @protected\r
         * @property {Ext.data.Model[]} removed\r
         */\r
        me.removed = [];\r
\r
        me.callParent(arguments);\r
\r
        if (me.getAsynchronousLoad() === false) {\r
            me.flushLoad();\r
        }\r
\r
        // <debug>\r
        if (!me.getModel() && me.useModelWarning !== false && me.getStoreId() !== 'ext-empty-store') {\r
            // There are a number of ways things could have gone wrong, try to give as much information as possible\r
            var logMsg = [\r
                Ext.getClassName(me) || 'Store',\r
                ' created with no model.'\r
            ];\r
\r
            if (typeof configModel === 'string') {\r
                logMsg.push(" The name '", configModel, "'", ' does not correspond to a valid model.');\r
            }\r
\r
            Ext.log.warn(logMsg.join(''));\r
        }\r
        // </debug>\r
    },\r
\r
    applyAsynchronousLoad: function(asynchronousLoad) {\r
    // Default in an asynchronousLoad setting.\r
    // It defaults to false if the proxy is synchronous, and true if the proxy is asynchronous.\r
        if (asynchronousLoad == null) {\r
            asynchronousLoad = !this.loadsSynchronously();\r
        }\r
        return asynchronousLoad;\r
    },\r
\r
    updateAutoLoad: function(autoLoad) {\r
        // Ensure the data collection is set up\r
        this.getData();\r
        if (autoLoad) {\r
            // Defer the load until idle, when the store (and probably the view) is fully constructed\r
            this.load(Ext.isObject(autoLoad) ? autoLoad : undefined);\r
        }\r
    },\r
\r
    /**\r
     * Returns the total number of {@link Ext.data.Model Model} instances that the {@link Ext.data.proxy.Proxy Proxy}\r
     * indicates exist. This will usually differ from {@link #getCount} when using paging - getCount returns the\r
     * number of records loaded into the Store at the moment, getTotalCount returns the number of records that\r
     * could be loaded into the Store if the Store contained all data\r
     * @return {Number} The total number of Model instances available via the Proxy. 0 returned if\r
     * no value has been set via the reader.\r
     */\r
    getTotalCount: function() {\r
        return this.totalCount || 0;\r
    },\r
\r
    applyFields: function(fields) {\r
        if (fields) {\r
            this.createImplicitModel(fields);\r
        }\r
    },\r
\r
    applyModel: function(model) {\r
        if (model) {\r
            model = Ext.data.schema.Schema.lookupEntity(model);\r
        }\r
        // If no model, ensure that the fields config is converted to a model.\r
        else {\r
            this.getFields();\r
            model = this.getModel() || this.createImplicitModel();\r
        }\r
        return model;\r
    },\r
\r
    applyProxy: function(proxy) {\r
        var model = this.getModel();\r
\r
        if (proxy !== null) {\r
            if (proxy) {\r
                if (proxy.isProxy) {\r
                    proxy.setModel(model);\r
                } else {\r
                    if (Ext.isString(proxy)) {\r
                        proxy = {\r
                            type: proxy,\r
                            model: model\r
                        };\r
                    } else if (!proxy.model) {\r
                        proxy = Ext.apply({\r
                            model: model\r
                        }, proxy);\r
                    }\r
\r
                    proxy = Ext.createByAlias('proxy.' + proxy.type, proxy);\r
                    proxy.autoCreated = true;\r
                }\r
            } else if (model) {\r
                proxy = model.getProxy();\r
            }\r
        \r
            if (!proxy) {\r
                proxy = Ext.createByAlias('proxy.memory');\r
                proxy.autoCreated = true;\r
            }\r
        }\r
\r
        return proxy;\r
    },\r
\r
    applyState: function (state) {\r
        var me = this;\r
\r
        me.callParent([state]);\r
\r
        // This is called during construction. Sorters and filters might have changed\r
        // which require a reload.\r
        // If autoLoad is true, it might have loaded synchronously from a memory proxy, so needs to reload.\r
        // If it is already loaded, we definitely need to reload to apply the state.\r
        if (me.getAutoLoad() || me.isLoaded()) {\r
            me.load();\r
        }\r
    },\r
\r
    updateProxy: function(proxy, oldProxy) {\r
        this.proxyListeners = Ext.destroy(this.proxyListeners);\r
    },\r
\r
    updateTrackRemoved: function (track) {\r
        this.cleanRemoved();\r
        this.removed = track ? [] : null;\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    onMetaChange: function(proxy, meta) {\r
        this.fireEvent('metachange', this, meta);\r
    },\r
\r
    //saves any phantom records\r
    create: function(data, options) {\r
        var me = this,\r
            Model = me.getModel(),\r
            instance = new Model(data),\r
            operation;\r
\r
        options = Ext.apply({}, options);\r
        if (!options.records) {\r
            options.records = [instance];\r
        }\r
        options.internalScope = me;\r
        options.internalCallback = me.onProxyWrite;\r
\r
        operation = me.createOperation('create', options);\r
        return operation.execute();\r
    },\r
\r
    read: function() {\r
        return this.load.apply(this, arguments);\r
    },\r
\r
    update: function(options) {\r
        var me = this,\r
            operation;\r
            \r
        options = Ext.apply({}, options);\r
        if (!options.records) {\r
            options.records = me.getUpdatedRecords();\r
        }\r
        options.internalScope = me;\r
        options.internalCallback = me.onProxyWrite;\r
\r
        operation = me.createOperation('update', options);\r
        return operation.execute();\r
    },\r
\r
    /**\r
     * @private\r
     * Callback for any write Operation over the Proxy. Updates the Store's MixedCollection to reflect\r
     * the updates provided by the Proxy\r
     */\r
    onProxyWrite: function(operation) {\r
        var me = this,\r
            success = operation.wasSuccessful(),\r
            records = operation.getRecords();\r
\r
        switch (operation.getAction()) {\r
            case 'create':\r
                me.onCreateRecords(records, operation, success);\r
                break;\r
            case 'update':\r
                me.onUpdateRecords(records, operation, success);\r
                break;\r
            case 'destroy':\r
                me.onDestroyRecords(records, operation, success);\r
                break;\r
        }\r
\r
        if (success) {\r
            me.fireEvent('write', me, operation);\r
            me.fireEvent('datachanged', me);\r
        }\r
    },\r
    \r
    // may be implemented by store subclasses\r
    onCreateRecords: Ext.emptyFn,\r
    \r
    // may be implemented by store subclasses\r
    onUpdateRecords: Ext.emptyFn,\r
    \r
    /**\r
     * Removes any records when a write is returned from the server.\r
     * @private\r
     * @param {Ext.data.Model[]} records The array of removed records\r
     * @param {Ext.data.operation.Operation} operation The operation that just completed\r
     * @param {Boolean} success True if the operation was successful\r
     */\r
    onDestroyRecords: function(records, operation, success) {\r
        if (success) {\r
            this.cleanRemoved();\r
        }\r
    },\r
\r
    // tells the attached proxy to destroy the given records\r
    // @since 3.4.0\r
    erase: function(options) {\r
        var me = this,\r
            operation;\r
\r
        options = Ext.apply({}, options);\r
        if (!options.records) {\r
            options.records = me.getRemovedRecords();\r
        }\r
        options.internalScope = me;\r
        options.internalCallback = me.onProxyWrite;\r
\r
        operation = me.createOperation('destroy', options);\r
        return operation.execute();\r
    },\r
\r
    /**\r
     * @private\r
     * Attached as the 'operationcomplete' event listener to a proxy's Batch object. By default just calls through\r
     * to onProxyWrite.\r
     */\r
    onBatchOperationComplete: function(batch, operation) {\r
        return this.onProxyWrite(operation);\r
    },\r
\r
    /**\r
     * @private\r
     * Attached as the 'complete' event listener to a proxy's Batch object. Iterates over the batch operations\r
     * and updates the Store's internal data MixedCollection.\r
     */\r
    onBatchComplete: function(batch, operation) {\r
        var me = this,\r
            operations = batch.operations,\r
            length = operations.length,\r
            i;\r
\r
        if (me.batchUpdateMode !== 'operation') {\r
            me.suspendEvents();\r
\r
            for (i = 0; i < length; i++) {\r
                me.onProxyWrite(operations[i]);\r
            }\r
\r
            me.resumeEvents();\r
        }\r
\r
        me.isSyncing = false;\r
        me.fireEvent('datachanged', me);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    onBatchException: function(batch, operation) {\r
        // //decide what to do... could continue with the next operation\r
        // batch.start();\r
        //\r
        // //or retry the last operation\r
        // batch.retry();\r
    },\r
\r
    /**\r
     * @private\r
     * Filter function for new records.\r
     */\r
    filterNew: function(item) {\r
        // only want phantom records that are valid\r
        return item.phantom === true && item.isValid();\r
    },\r
\r
    /**\r
     * Returns all `{@link Ext.data.Model#property-phantom phantom}` records in this store.\r
     * @return {Ext.data.Model[]} A possibly empty array of `phantom` records.\r
     */\r
    getNewRecords: function() {\r
        return [];\r
    },\r
\r
    /**\r
     * Returns all valid, non-phantom Model instances that have been updated in the Store but not yet synchronized with the Proxy.\r
     * @return {Ext.data.Model[]} The updated Model instances\r
     */\r
    getUpdatedRecords: function() {\r
        return [];\r
    },\r
\r
    /**\r
     * Gets all {@link Ext.data.Model records} added or updated since the last commit. Note that the order of records\r
     * returned is not deterministic and does not indicate the order in which records were modified. Note also that\r
     * removed records are not included (use {@link #getRemovedRecords} for that).\r
     * @return {Ext.data.Model[]} The added and updated Model instances\r
     */\r
    getModifiedRecords : function(){\r
        return [].concat(this.getNewRecords(), this.getUpdatedRecords());\r
    },\r
    \r
    /**\r
     * @private\r
     * Filter function for updated records.\r
     */\r
    filterUpdated: function(item) {\r
        // only want dirty records, not phantoms that are valid\r
        return item.dirty === true && item.phantom !== true && item.isValid();\r
    },\r
\r
    /**\r
     * Returns any records that have been removed from the store but not yet destroyed on the proxy.\r
     * @return {Ext.data.Model[]} The removed Model instances. Note that this is a *copy* of the store's\r
     * array, so may be mutated.\r
     */\r
    getRemovedRecords: function() {\r
        var removed = this.getRawRemovedRecords();\r
        // If trackRemoved: false, removed will be null\r
        return removed ? Ext.Array.clone(removed) : removed;\r
    },\r
\r
    /**\r
     * Synchronizes the store with its {@link #proxy}. This asks the proxy to batch together any new, updated\r
     * and deleted records in the store, updating the store's internal representation of the records\r
     * as each operation completes.\r
     * \r
     * @param {Object} [options] Object containing one or more properties supported by the sync method (these get \r
     * passed along to the underlying proxy's {@link Ext.data.Proxy#batch batch} method):\r
     * \r
     * @param {Ext.data.Batch/Object} [options.batch] A {@link Ext.data.Batch} object (or batch config to apply \r
     * to the created batch). If unspecified a default batch will be auto-created as needed.\r
     * \r
     * @param {Function} [options.callback] The function to be called upon completion of the sync.\r
     * The callback is called regardless of success or failure and is passed the following parameters:\r
     * @param {Ext.data.Batch} options.callback.batch The {@link Ext.data.Batch batch} that was processed,\r
     * containing all operations in their current state after processing\r
     * @param {Object} options.callback.options The options argument that was originally passed into sync\r
     * \r
     * @param {Function} [options.success] The function to be called upon successful completion of the sync. The \r
     * success function is called only if no exceptions were reported in any operations. If one or more exceptions\r
     * occurred then the failure function will be called instead. The success function is called \r
     * with the following parameters:\r
     * @param {Ext.data.Batch} options.success.batch The {@link Ext.data.Batch batch} that was processed,\r
     * containing all operations in their current state after processing\r
     * @param {Object} options.success.options The options argument that was originally passed into sync\r
     * \r
     * @param {Function} [options.failure] The function to be called upon unsuccessful completion of the sync. The \r
     * failure function is called when one or more operations returns an exception during processing (even if some\r
     * operations were also successful). In this case you can check the batch's {@link Ext.data.Batch#exceptions \r
     * exceptions} array to see exactly which operations had exceptions. The failure function is called with the \r
     * following parameters:\r
     * @param {Ext.data.Batch} options.failure.batch The {@link Ext.data.Batch} that was processed, containing all\r
     * operations in their current state after processing\r
     * @param {Object} options.failure.options The options argument that was originally passed into sync\r
     * \r
     * @param {Object} [options.params] Additional params to send during the sync Operation(s).\r
     *\r
     * @param {Object} [options.scope] The scope in which to execute any callbacks (i.e. the `this` object inside\r
     * the callback, success and/or failure functions). Defaults to the store's proxy.\r
     * \r
     * @return {Ext.data.Store} this\r
     */\r
    sync: function(options) {\r
        var me = this,\r
            operations = {},\r
            toCreate = me.getNewRecords(),\r
            toUpdate = me.getUpdatedRecords(),\r
            toDestroy = me.getRemovedRecords(),\r
            needsSync = false;\r
\r
        //<debug>\r
        if (me.isSyncing) {\r
            Ext.log.warn('Sync called while a sync operation is in progress. Consider configuring autoSync as false.');\r
        }\r
        //</debug>\r
\r
        me.needsSync = false;\r
\r
        if (toCreate.length > 0) {\r
            operations.create = toCreate;\r
            needsSync = true;\r
        }\r
\r
        if (toUpdate.length > 0) {\r
            operations.update = toUpdate;\r
            needsSync = true;\r
        }\r
\r
        if (toDestroy.length > 0) {\r
            operations.destroy = toDestroy;\r
            needsSync = true;\r
        }\r
\r
        if (needsSync && me.fireEvent('beforesync', operations) !== false) {\r
            me.isSyncing = true;\r
\r
            options = options || {};\r
\r
            me.proxy.batch(Ext.apply(options, {\r
                operations: operations,\r
                listeners: me.getBatchListeners()\r
            }));\r
        }\r
\r
        return me;\r
    },\r
    \r
    /**\r
     * @private\r
     * Returns an object which is passed in as the listeners argument to proxy.batch inside this.sync.\r
     * This is broken out into a separate function to allow for customisation of the listeners\r
     * @return {Object} The listeners object\r
     */\r
    getBatchListeners: function() {\r
        var me = this,\r
            listeners = {\r
                scope: me,\r
                exception: me.onBatchException,\r
                complete: me.onBatchComplete\r
            };\r
\r
        if (me.batchUpdateMode === 'operation') {\r
            listeners.operationcomplete = me.onBatchOperationComplete;\r
        }\r
\r
        return listeners;\r
    },\r
\r
    /**\r
     * Saves all pending changes via the configured {@link #proxy}. Use {@link #sync} instead.\r
     * @deprecated 4.0.0 Will be removed in the next major version\r
     */\r
    save: function() {\r
        return this.sync.apply(this, arguments);\r
    },\r
\r
    /**\r
     * Marks this store as needing a load. When the current executing event handler exits,\r
     * this store will send a request to load using its configured {@link #proxy}.\r
     *\r
     * Upon return of the data from whatever data source the proxy connected to, the retrieved\r
     * {@link Ext.data.Model records} will be loaded into this store, and the optional callback will be called.\r
     * Example usage:\r
     *\r
     *     store.load({\r
     *         scope: this,\r
     *         callback: function(records, operation, success) {\r
     *             // the {@link Ext.data.operation.Operation operation} object\r
     *             // contains all of the details of the load operation\r
     *             console.log(records);\r
     *         }\r
     *     });\r
     *\r
     * If the callback scope does not need to be set, a function can simply be passed:\r
     *\r
     *     store.load(function(records, operation, success) {\r
     *         console.log('loaded records');\r
     *     });\r
     *\r
     * @param {Object} [options] This is passed into the {@link Ext.data.operation.Operation Operation}\r
     * object that is created and then sent to the proxy's {@link Ext.data.proxy.Proxy#read} function.\r
     * In addition to the options listed below, this object may contain properties to configure the\r
     * {@link Ext.data.operation.Operation Operation}.\r
     * @param {Function} [options.callback] A function which is called when the response arrives.\r
     * @param {Ext.data.Model[]} options.callback.records Array of records.\r
     * @param {Ext.data.operation.Operation} options.callback.operation The Operation itself.\r
     * @param {Boolean} options.callback.success `true` when operation completed successfully.\r
     * @param {Boolean} [options.addRecords=false] Specify as `true` to *add* the incoming records rather than the\r
     * default which is to have the incoming records *replace* the existing stoire contents.\r
     * \r
     * @return {Ext.data.Store} this\r
     * @since 1.1.0\r
     */\r
    load: function(options) {\r
        var me = this;\r
\r
        // Legacy option. Specifying a function was allowed.\r
        if (typeof options === 'function') {\r
            options = {\r
                callback: options\r
            };\r
        } else {\r
            // We may mutate the options object in setLoadOptions.\r
            options = options ? Ext.Object.chain(options) : {};\r
        }\r
\r
        me.pendingLoadOptions = options;\r
\r
        // If we are configured to load asynchronously (the default for async proxies)\r
        // then schedule a flush, unless one is already scheduled.\r
        if (me.getAsynchronousLoad()) {\r
            if (!me.loadTimer) {\r
                me.loadTimer = Ext.asap(me.flushLoad, me);\r
            }\r
        }\r
        // If we are configured to load synchronously (the default for sync proxies)\r
        // then flush the load now.\r
        else {\r
            me.flushLoad();\r
        }\r
        return me;\r
    },\r
\r
    /**\r
     * Called when the event handler which called the {@link #method-load} method exits.\r
     */\r
    flushLoad: function() {\r
        var me = this,\r
            options = me.pendingLoadOptions,\r
            operation;\r
\r
        // If it gets called programatically before the timer fired, the listener will need cancelling.\r
        me.clearLoadTask();\r
        if (!options) {\r
            return;\r
        }\r
\r
        me.setLoadOptions(options);\r
\r
        if (me.getRemoteSort() && options.sorters) {\r
            me.fireEvent('beforesort', me, options.sorters);\r
        }\r
        \r
        operation = Ext.apply({\r
            internalScope: me,\r
            internalCallback: me.onProxyLoad,\r
            scope: me\r
        }, options);\r
        me.lastOptions = operation;\r
        \r
\r
        operation = me.createOperation('read', operation);\r
\r
        if (me.fireEvent('beforeload', me, operation) !== false) {\r
            me.onBeforeLoad(operation);\r
            me.loading = true;\r
            operation.execute();\r
        }\r
    },\r
\r
    /**\r
     * Reloads the store using the last options passed to the {@link #method-load} method. You can use the reload method to reload the\r
     * store using the parameters from the last load() call. For example:\r
     *\r
     *     store.load({\r
     *         params : {\r
     *             userid : 22216\r
     *         }\r
     *     });\r
     *\r
     *     //...\r
     *\r
     *     store.reload();\r
     *\r
     * The initial {@link #method-load} execution will pass the `userid` parameter in the request. The {@link #reload} execution\r
     * will also send the same `userid` parameter in its request as it will reuse the `params` object from the last {@link #method-load} call.\r
     *\r
     * You can override a param by passing in the config object with the `params` object:\r
     *\r
     *     store.load({\r
     *         params : {\r
     *             userid : 22216,\r
     *             foo    : 'bar'\r
     *         }\r
     *     });\r
     *\r
     *     //...\r
     *\r
     *     store.reload({\r
     *         params : {\r
     *             userid : 1234\r
     *         }\r
     *     });\r
     *\r
     * The initial {@link #method-load} execution sends the `userid` and `foo` parameters but in the {@link #reload} it only sends\r
     * the `userid` paramter because you are overriding the `params` config not just overriding the one param. To only change a single param\r
     * but keep other params, you will have to get the last params from the {@link #lastOptions} property:\r
     *\r
     *     var lastOptions = store.lastOptions,\r
     *         lastParams = Ext.clone(lastOptions.params); // make a copy of the last params so we don't affect future reload() calls\r
     *\r
     *     lastParams.userid = 1234;\r
     *\r
     *     store.reload({\r
     *         params : lastParams\r
     *     });\r
     *\r
     * This will now send the `userid` parameter as `1234` and the `foo` param as `'bar'`.\r
     *\r
     * @param {Object} [options] A config object which contains options which may override the options passed to the previous load call. See the\r
     * {@link #method-load} method for valid configs.\r
     */\r
    reload: function(options) {\r
        var o = Ext.apply({}, options, this.lastOptions);\r
        return this.load(o);\r
    },\r
\r
    onEndUpdate: function() {\r
        var me = this;\r
\r
        if (me.needsSync && me.autoSync && !me.autoSyncSuspended) {\r
            me.sync();\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     * A model instance should call this method on the Store it has been {@link Ext.data.Model#join joined} to..\r
     * @param {Ext.data.Model} record The model instance that was edited\r
     * @since 3.4.0\r
     */\r
    afterReject: function(record) {\r
        var me = this;\r
        // Must pass the 5th param (modifiedFieldNames) as null, otherwise the\r
        // event firing machinery appends the listeners "options" object to the arg list\r
        // which may get used as the modified fields array by a handler.\r
        // This array is used for selective grid cell updating by Grid View.\r
        // Null will be treated as though all cells need updating.\r
        if (me.contains(record)) {\r
            me.onUpdate(record, Ext.data.Model.REJECT, null);\r
            me.fireEvent('update', me, record, Ext.data.Model.REJECT, null);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     * A model instance should call this method on the Store it has been {@link Ext.data.Model#join joined} to.\r
     * @param {Ext.data.Model} record The model instance that was edited\r
     * @since 3.4.0\r
     */\r
    afterCommit: function(record, modifiedFieldNames) {\r
        var me = this;\r
        if (!modifiedFieldNames) {\r
            modifiedFieldNames = null;\r
        }\r
        if (me.contains(record)) {\r
            me.onUpdate(record, Ext.data.Model.COMMIT, modifiedFieldNames);\r
            me.fireEvent('update', me, record, Ext.data.Model.COMMIT, modifiedFieldNames);\r
        }\r
    },\r
    \r
    afterErase: function(record) {\r
        this.onErase(record);\r
    },\r
    \r
    onErase: Ext.emptyFn,\r
\r
    onUpdate: Ext.emptyFn,\r
\r
    /**\r
     * @private\r
     */\r
    onDestroy: function() {\r
        var me = this,\r
            proxy = me.getProxy();\r
\r
        me.clearLoadTask();\r
        me.getData().destroy();\r
        me.data = null;\r
        me.setProxy(null);\r
        \r
        if (proxy.autoCreated) {\r
            proxy.destroy();\r
        }\r
        \r
        me.setModel(null);\r
    },\r
\r
    \r
    /**\r
     * Returns true if the store has a pending load task.\r
     * @return {Boolean} `true` if the store has a pending load task.\r
     * @private\r
     */\r
    hasPendingLoad: function() {\r
        return !!this.pendingLoadOptions || this.isLoading();\r
    },\r
\r
    /**\r
     * Returns true if the Store is currently performing a load operation\r
     * @return {Boolean} `true` if the Store is currently loading\r
     */\r
    isLoading: function() {\r
        return !!this.loading;\r
    },\r
\r
    /**\r
     * Returns `true` if the Store has been loaded.\r
     * @return {Boolean} `true` if the Store has been loaded.\r
     */\r
    isLoaded: function() {\r
        return this.loadCount > 0;\r
    },\r
\r
    /**\r
     * Suspends automatically syncing the Store with its Proxy.  Only applicable if {@link #autoSync} is `true`\r
     */\r
    suspendAutoSync: function() {\r
        ++this.autoSyncSuspended;\r
    },\r
\r
    /**\r
     * Resumes automatically syncing the Store with its Proxy.  Only applicable if {@link #autoSync} is `true`\r
     * @param {Boolean} syncNow Pass `true` to synchronize now. Only synchronizes with the Proxy if the suspension\r
     * count has gone to zero (We are not under a higher level of suspension)\r
     * \r
     */\r
    resumeAutoSync: function(syncNow) {\r
        var me = this;\r
\r
        //<debug>\r
        if (!me.autoSyncSuspended) {\r
            Ext.log.warn('Mismatched call to resumeAutoSync - auto synchronization is currently not suspended.');\r
        }\r
        //</debug>\r
        if (me.autoSyncSuspended && ! --me.autoSyncSuspended) {\r
            if (syncNow) {\r
                me.sync();\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Removes all records from the store. This method does a "fast remove",\r
     * individual remove events are not called. The {@link #clear} event is\r
     * fired upon completion.\r
     * @method\r
     * @since 1.1.0\r
     */\r
    removeAll: Ext.emptyFn,\r
    // individual store subclasses should implement a "fast" remove\r
    // and fire a clear event afterwards\r
    \r
    // to be implemented by subclasses\r
    clearData: Ext.emptyFn,\r
\r
    privates: {\r
        /**\r
         * @private\r
         * Returns the array of records which have been removed since the last time this store was synced.\r
         *\r
         * This is used internally, when purging removed records after a successful sync.\r
         * This is overridden by TreeStore because TreeStore accumulates deleted records on removal\r
         * of child nodes from their parent, *not* on removal of records from its collection. The collection\r
         * has records added on expand, and removed on collapse.\r
         */\r
        getRawRemovedRecords: function() {\r
            return this.removed;\r
        },\r
\r
        onExtraParamsChanged: function() {\r
            \r
        },\r
\r
        clearLoadTask: function() {\r
            Ext.asapCancel(this.loadTimer);\r
            this.pendingLoadOptions = this.loadTimer = null;\r
        },\r
\r
        cleanRemoved: function() {\r
            // Must use class-specific getRawRemovedRecords.\r
            // Regular Stores add to the "removed" property on remove.\r
            // TreeStores are having records removed all the time; node collapse removes.\r
            // TreeStores add to the "removedNodes" property onNodeRemove\r
            var removed = this.getRawRemovedRecords(),\r
                len, i;\r
\r
            if (removed) {\r
                for (i = 0, len = removed.length; i < len; ++i) {\r
                    removed[i].unjoin(this);\r
                }\r
                removed.length = 0;\r
            }\r
        },\r
\r
        createOperation: function(type, options) {\r
            var me = this,\r
                proxy = me.getProxy(),\r
                listeners;\r
\r
            if (!me.proxyListeners) {\r
                listeners = {\r
                    scope: me,\r
                    destroyable: true,\r
                    beginprocessresponse: me.beginUpdate,\r
                    endprocessresponse: me.endUpdate\r
                };\r
\r
                if (!me.disableMetaChangeEvent) {\r
                    listeners.metachange = me.onMetaChange;\r
                }\r
                me.proxyListeners = proxy.on(listeners);\r
            }\r
            return proxy.createOperation(type, options);\r
        },\r
\r
        createImplicitModel: function(fields) {\r
            var me = this,\r
                modelCfg = {\r
                    extend: me.implicitModel,\r
                    statics: {\r
                        defaultProxy: 'memory'\r
                    }\r
                },\r
                proxy, model;\r
\r
            if (fields) {\r
                modelCfg.fields = fields;\r
            }\r
            model = Ext.define(null, modelCfg);\r
\r
            me.setModel(model);\r
\r
            proxy = me.getProxy();\r
            if (proxy) {\r
                model.setProxy(proxy);\r
            } else {\r
                me.setProxy(model.getProxy());\r
            }\r
        },\r
\r
        loadsSynchronously: function() {\r
            return this.getProxy().isSynchronous;\r
        },\r
\r
        onBeforeLoad: Ext.privateFn,\r
\r
        removeFromRemoved: function(record) {\r
            // Must use class-specific getRawRemovedRecords.\r
            // Regular Stores add to the "removed" property on remove.\r
            // TreeStores are having records removed all the time; node collapse removes.\r
            // TreeStores add to the "removedNodes" property onNodeRemove\r
            var removed = this.getRawRemovedRecords();\r
            if (removed) {\r
                Ext.Array.remove(removed, record);\r
                record.unjoin(this);\r
            }\r
        },\r
\r
        setLoadOptions: function(options) {\r
            var me = this,\r
                filters, sorters;\r
\r
            if (me.getRemoteFilter()) {\r
                filters = me.getFilters(false);\r
                if (filters && filters.getCount()) {\r
                    options.filters = filters.getRange();\r
                }\r
            }\r
\r
            if (me.getRemoteSort()) {\r
                sorters = me.getSorters(false);\r
                if (sorters && sorters.getCount()) {\r
                    options.sorters = sorters.getRange();\r
                }\r
            }\r
        }\r
    }\r
\r
});\r