add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / data / proxy / WebStorage.js

/**\r
 * WebStorageProxy is simply a superclass for the {@link Ext.data.proxy.LocalStorage LocalStorage} and {@link\r
 * Ext.data.proxy.SessionStorage SessionStorage} proxies. It uses the new HTML5 key/value client-side storage objects to\r
 * save {@link Ext.data.Model model instances} for offline use.\r
 * @private\r
 */\r
Ext.define('Ext.data.proxy.WebStorage', {\r
    extend: 'Ext.data.proxy.Client',\r
    alternateClassName: 'Ext.data.WebStorageProxy',\r
    requires: [\r
        'Ext.data.identifier.Sequential'\r
    ],\r
\r
    config: {\r
        /**\r
        * @cfg {String} id\r
        * The unique ID used as the key in which all record data are stored in the local storage object.\r
        */\r
        id: undefined\r
    },\r
\r
    /**\r
     * @cfg {Object} reader\r
     * Not used by web storage proxy.\r
     * @hide\r
     */\r
\r
    /**\r
     * @cfg {Object} writer\r
     * Not used by web storage proxy.\r
     * @hide\r
     */\r
\r
    /**\r
     * Creates the proxy, throws an error if local storage is not supported in the current browser.\r
     * @param {Object} config (optional) Config object.\r
     */\r
    constructor: function(config) {\r
        this.callParent(arguments);\r
\r
        /**\r
         * @property {Object} cache\r
         * Cached map of records already retrieved by this Proxy. Ensures that the same instance is always retrieved.\r
         */\r
        this.cache = {};\r
\r
        //<debug>\r
        if (this.getStorageObject() === undefined) {\r
            Ext.raise("Local Storage is not supported in this browser, please use another type of data proxy");\r
        }\r
        //</debug>\r
\r
        //<debug>\r
        if (this.getId() === undefined) {\r
            Ext.raise("No unique id was provided to the local storage proxy. See Ext.data.proxy.LocalStorage documentation for details");\r
        }\r
        //</debug>\r
\r
        this.initialize();\r
    },\r
\r
    /**\r
     * @inheritdoc\r
     */\r
    create: function(operation) {\r
        var me = this,\r
            records = operation.getRecords(),\r
            length = records.length,\r
            ids = me.getIds(),\r
            id, record, i, identifier;\r
\r
        if (me.isHierarchical === undefined) {\r
            // if the storage object does not yet contain any data, this is the first point at which we can determine whether or not this proxy deals with hierarchical data.\r
            // it cannot be determined during initialization because the Model is not decorated with NodeInterface until it is used in a TreeStore\r
            me.isHierarchical = !!records[0].isNode;\r
            if(me.isHierarchical) {\r
                me.getStorageObject().setItem(me.getTreeKey(), true);\r
            }\r
        }\r
\r
        for (i = 0; i < length; i++) {\r
            record = records[i];\r
\r
            if (record.phantom) {\r
                record.phantom = false;\r
                identifier = record.identifier;\r
                if (identifier && identifier.isUnique) {\r
                    id = record.getId();\r
                } else {\r
                    id = me.getNextId();\r
                }\r
            } else {\r
                id = record.getId();\r
            }\r
\r
            me.setRecord(record, id);\r
            record.commit();\r
            ids.push(id);\r
        }\r
\r
        me.setIds(ids);\r
\r
        operation.setSuccessful(true);\r
    },\r
\r
    /**\r
     * @inheritdoc\r
     */\r
    read: function(operation) {\r
        var me = this,\r
            allRecords,\r
            records = [],\r
            success = true,\r
            Model = me.getModel(),\r
            validCount = 0,\r
            recordCreator = operation.getRecordCreator(),\r
            filters, sorters, limit, filterLen, valid, record, ids, length, data, id, i, j;\r
\r
        if (me.isHierarchical) {\r
            records = me.getTreeData();\r
        } else {\r
            ids = me.getIds();\r
            length = ids.length;\r
            id = operation.getId();\r
            //read a single record\r
            if (id) {\r
                data = me.getRecord(id);\r
                if (data !== null) {\r
                    record = recordCreator ? recordCreator(data, Model) : new Model(data);\r
                }\r
\r
                if (record) {\r
                    records.push(record);\r
                } else {\r
                    success = false;\r
                }\r
            } else {\r
                sorters = operation.getSorters();\r
                filters = operation.getFilters();\r
                limit = operation.getLimit();\r
                allRecords = [];\r
\r
                // build an array of all records first first so we can sort them before\r
                // applying filters or limit.  These are Model instances instead of raw\r
                // data objects so that the sorter and filter Fn can use the Model API\r
                for (i = 0; i < length; i++) {\r
                    data = me.getRecord(ids[i]);\r
                    record = recordCreator ? recordCreator(data, Model) : new Model(data);\r
                    allRecords.push(record);\r
                }\r
\r
                if (sorters) {\r
                    Ext.Array.sort(allRecords, Ext.util.Sorter.createComparator(sorters));\r
                }\r
\r
                for (i = operation.getStart() || 0; i < length; i++) {\r
                    record = allRecords[i];\r
                    valid = true;\r
\r
                    if (filters) {\r
                        for (j = 0, filterLen = filters.length; j < filterLen; j++) {\r
                            valid = filters[j].filter(record);\r
                        }\r
                    }\r
\r
                    if (valid) {\r
                        records.push(record);\r
                        validCount++;\r
                    }\r
\r
                    if (limit && validCount === limit) {\r
                        break;\r
                    }\r
                }\r
            }\r
\r
        }\r
\r
        if (success) {\r
            operation.setResultSet(new Ext.data.ResultSet({\r
                records: records,\r
                total  : records.length,\r
                loaded : true\r
            }));\r
            operation.setSuccessful(true);\r
        } else {\r
            operation.setException('Unable to load records');\r
        }\r
    },\r
\r
    /**\r
     * @inheritdoc\r
     */\r
    update: function(operation) {\r
        var records = operation.getRecords(),\r
            length  = records.length,\r
            ids     = this.getIds(),\r
            record, id, i;\r
\r
        for (i = 0; i < length; i++) {\r
            record = records[i];\r
            this.setRecord(record);\r
            record.commit();\r
\r
            //we need to update the set of ids here because it's possible that a non-phantom record was added\r
            //to this proxy - in which case the record's id would never have been added via the normal 'create' call\r
            id = record.getId();\r
            if (id !== undefined && Ext.Array.indexOf(ids, id) === -1) {\r
                ids.push(id);\r
            }\r
        }\r
        this.setIds(ids);\r
        operation.setSuccessful(true);\r
    },\r
\r
    /**\r
     * @inheritdoc\r
     */\r
    erase: function(operation) {\r
        var me = this,\r
            records = operation.getRecords(),\r
            ids = me.getIds(),\r
            idLength = ids.length,\r
            newIds = [],\r
            removedHash = {},\r
            i = records.length,\r
            id;\r
\r
        for (; i--;) {\r
            Ext.apply(removedHash, me.removeRecord(records[i]));\r
        }\r
\r
        for(i = 0; i < idLength; i++) {\r
            id = ids[i];\r
            if(!removedHash[id]) {\r
                newIds.push(id);\r
            }\r
        }\r
\r
        me.setIds(newIds);\r
        operation.setSuccessful(true);\r
    },\r
\r
    /**\r
     * @private\r
     * Fetches record data from the Proxy by ID.\r
     * @param {String} id The record's unique ID\r
     * @return {Object} The record data\r
     */\r
    getRecord: function(id) {\r
        var me = this,\r
            cache = me.cache,\r
            data = !cache[id] ? Ext.decode(me.getStorageObject().getItem(me.getRecordKey(id))) : cache[id];\r
\r
        if(!data) {\r
            return null;\r
        }\r
\r
        cache[id] = data;\r
        data[me.getModel().prototype.idProperty] = id;\r
\r
        // In order to preserve the cache, we MUST copy it here because\r
        // Models use the incoming raw data as their data object and convert/default values into that object\r
        return Ext.merge({}, data);\r
    },\r
\r
    /**\r
     * Saves the given record in the Proxy.\r
     * @param {Ext.data.Model} record The model instance\r
     * @param {String} [id] The id to save the record under (defaults to the value of the record's getId() function)\r
     */\r
    setRecord: function(record, id) {\r
        if (id) {\r
            record.set('id', id, {\r
                commit: true\r
            });\r
        } else {\r
            id = record.getId();\r
        }\r
\r
        var me = this,\r
            rawData = record.getData(),\r
            data    = {},\r
            model   = me.getModel(),\r
            fields  = model.getFields(),\r
            length  = fields.length,\r
            i = 0,\r
            field, name, obj, key;\r
\r
        for (; i < length; i++) {\r
            field = fields[i];\r
            name  = field.name;\r
\r
            if(field.persist) {\r
                data[name] = rawData[name];\r
            }\r
        }\r
\r
        // no need to store the id in the data, since it is already stored in the record key\r
        delete data[model.prototype.idProperty];\r
\r
        // if the record is a tree node and it's a direct child of the root node, do not store the parentId\r
        if(record.isNode && record.get('depth') === 1) {\r
            delete data.parentId;\r
        }\r
\r
        obj = me.getStorageObject();\r
        key = me.getRecordKey(id);\r
\r
        //keep the cache up to date\r
        me.cache[id] = data;\r
\r
        //iPad bug requires that we remove the item before setting it\r
        obj.removeItem(key);\r
        obj.setItem(key, Ext.encode(data));\r
    },\r
\r
    /**\r
     * @private\r
     * Physically removes a given record from the local storage and recursively removes children if the record is a tree node. Used internally by {@link #destroy}.\r
     * @param {Ext.data.Model} record The record to remove\r
     * @return {Object} a hash with the ids of the records that were removed as keys and the records that were removed as values\r
     */\r
    removeRecord: function(record) {\r
        var me = this,\r
            id = record.getId(),\r
            records = {},\r
            i, childNodes;\r
\r
        records[id] = record;\r
        me.getStorageObject().removeItem(me.getRecordKey(id));\r
        delete me.cache[id];\r
\r
        if(record.childNodes) {\r
            childNodes = record.childNodes;\r
            for(i = childNodes.length; i--;) {\r
                Ext.apply(records, me.removeRecord(childNodes[i]));\r
            }\r
        }\r
\r
        return records;\r
    },\r
\r
    /**\r
     * @private\r
     * Given the id of a record, returns a unique string based on that id and the id of this proxy. This is used when\r
     * storing data in the local storage object and should prevent naming collisions.\r
     * @param {String/Number/Ext.data.Model} id The record id, or a Model instance\r
     * @return {String} The unique key for this record\r
     */\r
    getRecordKey: function(id) {\r
        if (id.isModel) {\r
            id = id.getId();\r
        }\r
\r
        return Ext.String.format("{0}-{1}", this.getId(), id);\r
    },\r
\r
    /**\r
     * @private\r
     * Returns the unique key used to store the current record counter for this proxy. This is used internally when\r
     * realizing models (creating them when they used to be phantoms), in order to give each model instance a unique id.\r
     * @return {String} The counter key\r
     */\r
    getRecordCounterKey: function() {\r
        return Ext.String.format("{0}-counter", this.getId());\r
    },\r
\r
    /**\r
     * @private\r
     * Returns the unique key used to store the tree indicator. This is used internally to determine if the stored data is hierarchical\r
     * @return {String} The counter key\r
     */\r
    getTreeKey: function() {\r
        return Ext.String.format("{0}-tree", this.getId());\r
    },\r
\r
    /**\r
     * @private\r
     * Returns the array of record IDs stored in this Proxy\r
     * @return {Number[]} The record IDs. Each is cast as a Number\r
     */\r
    getIds: function() {\r
        var me = this,\r
            ids = (me.getStorageObject().getItem(me.getId()) || "").split(","),\r
            length = ids.length,\r
            isString = this.getIdField().isStringField,\r
            i;\r
\r
        if (length === 1 && ids[0] === "") {\r
            ids = [];\r
        } else {\r
            for (i = 0; i < length; i++) {\r
                ids[i] = isString ? ids[i] : +ids[i];\r
            }\r
        }\r
\r
        return ids;\r
    },\r
    \r
    getIdField: function() {\r
        return this.getModel().prototype.idField;\r
    },\r
\r
    /**\r
     * @private\r
     * Saves the array of ids representing the set of all records in the Proxy\r
     * @param {Number[]} ids The ids to set\r
     */\r
    setIds: function(ids) {\r
        var obj = this.getStorageObject(),\r
            str = ids.join(","),\r
            id = this.getId();\r
\r
        obj.removeItem(id);\r
\r
        if (!Ext.isEmpty(str)) {\r
            obj.setItem(id, str);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     * Returns the next numerical ID that can be used when realizing a model instance (see getRecordCounterKey).\r
     * Increments the counter.\r
     * @return {Number} The id\r
     */\r
    getNextId: function() {\r
        var me = this,\r
            obj = me.getStorageObject(),\r
            key = me.getRecordCounterKey(),\r
            isString = me.getIdField().isStringField,\r
            id;\r
\r
        id = me.idGenerator.generate();\r
\r
        obj.setItem(key, id);\r
\r
        if(isString) {\r
            id = id + '';\r
        }\r
\r
        return id;\r
    },\r
\r
    /**\r
     * Gets tree data and transforms it from key value pairs into a hierarchical structure.\r
     * @private\r
     * @return {Ext.data.NodeInterface[]}\r
     */\r
    getTreeData: function() {\r
        var me = this,\r
            ids = me.getIds(),\r
            length = ids.length,\r
            records = [],\r
            recordHash = {},\r
            root = [],\r
            i = 0,\r
            Model = me.getModel(),\r
            idProperty = Model.prototype.idProperty,\r
            rootLength, record, parent, parentId, children, id;\r
\r
        for(; i < length; i++) {\r
            id = ids[i];\r
            // get the record for each id\r
            record = me.getRecord(id);\r
            // push the record into the records array\r
            records.push(record);\r
            // add the record to the record hash so it can be easily retrieved by id later\r
            recordHash[id] = record;\r
            if(!record.parentId) {\r
                // push records that are at the root level (those with no parent id) into the "root" array\r
                root.push(record);\r
            }\r
        }\r
\r
        rootLength = root.length;\r
\r
        // sort the records by parent id for greater efficiency, so that each parent record only has to be found once for all of its children\r
        Ext.Array.sort(records, me.sortByParentId);\r
\r
        // append each record to its parent, starting after the root node(s), since root nodes do not need to be attached to a parent\r
        for(i = rootLength; i < length; i++) {\r
            record = records[i];\r
            parentId = record.parentId;\r
            if(!parent || parent[idProperty] !== parentId) {\r
                // if this record has a different parent id from the previous record, we need to look up the parent by id.\r
                parent = recordHash[parentId];\r
                parent.children = children = [];\r
            }\r
\r
            // push the record onto its parent's children array\r
            children.push(record);\r
        }\r
\r
        for(i = length; i--;) {\r
            record = records[i];\r
            if (!record.children && !record.leaf) {\r
                // set non-leaf nodes with no children to loaded so the proxy won't try to dynamically load their contents when they are expanded\r
                record.loaded = true;\r
            }\r
        }\r
\r
        // Create model instances out of all the "root-level" nodes.\r
        for(i = rootLength; i--;) {\r
            record = root[i];\r
            root[i] = new Model(record);\r
        }\r
\r
        return root;\r
    },\r
\r
    /**\r
     * Sorter function for sorting records by parentId\r
     * @private\r
     * @param {Object} node1\r
     * @param {Object} node2\r
     * @return {Number}\r
     */\r
    sortByParentId: function(node1, node2) {\r
        return (node1.parentId || 0) - (node2.parentId || 0);\r
    },\r
\r
    /**\r
     * @private\r
     * Sets up the Proxy by claiming the key in the storage object that corresponds to the unique id of this Proxy. Called\r
     * automatically by the constructor, this should not need to be called again unless {@link #clear} has been called.\r
     */\r
    initialize: function() {\r
        var me = this,\r
            storageObject = me.getStorageObject(),\r
            lastId = +storageObject.getItem(me.getRecordCounterKey()),\r
            id = me.getId();\r
\r
        storageObject.setItem(id, storageObject.getItem(id) || "");\r
        if(storageObject.getItem(me.getTreeKey())) {\r
            me.isHierarchical = true;\r
        }\r
\r
        me.idGenerator = new Ext.data.identifier.Sequential({\r
            seed: lastId ? lastId + 1 : 1\r
        });\r
    },\r
\r
    /**\r
     * Destroys all records stored in the proxy and removes all keys and values used to support the proxy from the\r
     * storage object.\r
     */\r
    clear: function() {\r
        var me = this,\r
            obj = me.getStorageObject(),\r
            ids = me.getIds(),\r
            len = ids.length,\r
            i;\r
\r
        //remove all the records\r
        for (i = 0; i < len; i++) {\r
            obj.removeItem(me.getRecordKey(ids[i]));\r
        }\r
\r
        //remove the supporting objects\r
        obj.removeItem(me.getRecordCounterKey());\r
        obj.removeItem(me.getTreeKey());\r
        obj.removeItem(me.getId());\r
\r
        // clear the cache\r
        me.cache = {};\r
    },\r
\r
    /**\r
     * @private\r
     * Abstract function which should return the storage object that data will be saved to. This must be implemented\r
     * in each subclass.\r
     * @return {Object} The storage object\r
     */\r
    getStorageObject: function() {\r
        //<debug>\r
        Ext.raise("The getStorageObject function has not been defined in your Ext.data.proxy.WebStorage subclass");\r
        //</debug>\r
    }\r
});