Upgrade to ExtJS 4.0.7 - Released 10/19/2011

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

diff --git a/src/data/proxy/WebStorage.js b/src/data/proxy/WebStorage.js
index 8ebe385..491293f 100644 (file)
--- a/src/data/proxy/WebStorage.js
+++ b/src/data/proxy/WebStorage.js
@@ -1,35 +1,45 @@
+/*
+
+This file is part of Ext JS 4
+
+Copyright (c) 2011 Sencha Inc
+
+Contact:  http://www.sencha.com/contact
+
+GNU General Public License Usage
+This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
+
+If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
+
+*/

 /**
  * @author Ed Spencer
 /**
  * @author Ed Spencer

- * @class Ext.data.proxy.WebStorage
- * @extends Ext.data.proxy.Client
- * 
- * <p>WebStorageProxy is simply a superclass for the {@link Ext.data.proxy.LocalStorage localStorage} and 
- * {@link Ext.data.proxy.SessionStorage sessionStorage} proxies. It uses the new HTML5 key/value client-side storage 
- * objects to save {@link Ext.data.Model model instances} for offline use.</p>
- * 
- * @constructor
- * Creates the proxy, throws an error if local storage is not supported in the current browser
- * @param {Object} config Optional config object
+ *
+ * WebStorageProxy is simply a superclass for the {@link Ext.data.proxy.LocalStorage LocalStorage} and {@link
+ * Ext.data.proxy.SessionStorage SessionStorage} proxies. It uses the new HTML5 key/value client-side storage objects to
+ * save {@link Ext.data.Model model instances} for offline use.
+ * @private

  */
 Ext.define('Ext.data.proxy.WebStorage', {
     extend: 'Ext.data.proxy.Client',
     alternateClassName: 'Ext.data.WebStorageProxy',
  */
 Ext.define('Ext.data.proxy.WebStorage', {
     extend: 'Ext.data.proxy.Client',
     alternateClassName: 'Ext.data.WebStorageProxy',

-    
+

     /**
     /**

-     * @cfg {String} id The unique ID used as the key in which all record data are stored in the local storage object
+     * @cfg {String} id
+     * The unique ID used as the key in which all record data are stored in the local storage object.

      */
     id: undefined,
 
     /**
      */
     id: undefined,
 
     /**

-     * @ignore
+     * Creates the proxy, throws an error if local storage is not supported in the current browser.
+     * @param {Object} config (optional) Config object.

      */
     constructor: function(config) {
         this.callParent(arguments);
      */
     constructor: function(config) {
         this.callParent(arguments);

-        
+

         /**
         /**

-         * Cached map of records already retrieved by this Proxy - ensures that the same instance is always retrieved
-         * @property cache
-         * @type Object
+         * @property {Object} cache
+         * Cached map of records already retrieved by this Proxy. Ensures that the same instance is always retrieved.

          */
         this.cache = {};
 
          */
         this.cache = {};
 


@@ -57,7 +67,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
             length  = records.length,
             ids     = this.getIds(),
             id, record, i;
             length  = records.length,
             ids     = this.getIds(),
             id, record, i;

-        
+

         operation.setStarted();
 
         for (i = 0; i < length; i++) {
         operation.setStarted();
 
         for (i = 0; i < length; i++) {


@@ -92,11 +102,11 @@ Ext.define('Ext.data.proxy.WebStorage', {
             ids     = this.getIds(),
             length  = ids.length,
             i, recordData, record;
             ids     = this.getIds(),
             length  = ids.length,
             i, recordData, record;

-        
+

         //read a single record
         if (operation.id) {
             record = this.getRecord(operation.id);
         //read a single record
         if (operation.id) {
             record = this.getRecord(operation.id);

-            
+

             if (record) {
                 records.push(record);
                 operation.setSuccessful();
             if (record) {
                 records.push(record);
                 operation.setSuccessful();


@@ -107,7 +117,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
             }
             operation.setSuccessful();
         }
             }
             operation.setSuccessful();
         }

-        
+

         operation.setCompleted();
 
         operation.resultSet = Ext.create('Ext.data.ResultSet', {
         operation.setCompleted();
 
         operation.resultSet = Ext.create('Ext.data.ResultSet', {


@@ -133,7 +143,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
         for (i = 0; i < length; i++) {
             record = records[i];
             this.setRecord(record);
         for (i = 0; i < length; i++) {
             record = records[i];
             this.setRecord(record);

-            
+

             //we need to update the set of ids here because it's possible that a non-phantom record was added
             //to this proxy - in which case the record's id would never have been added via the normal 'create' call
             id = record.getId();
             //we need to update the set of ids here because it's possible that a non-phantom record was added
             //to this proxy - in which case the record's id would never have been added via the normal 'create' call
             id = record.getId();


@@ -167,7 +177,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
         }
 
         this.setIds(newIds);
         }
 
         this.setIds(newIds);

-        
+

         operation.setCompleted();
         operation.setSuccessful();
 
         operation.setCompleted();
         operation.setSuccessful();
 


@@ -178,7 +188,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
 
     /**
      * @private
 
     /**
      * @private

-     * Fetches a model instance from the Proxy by ID. Runs each field's decode function (if present) to decode the data
+     * Fetches a model instance from the Proxy by ID. Runs each field's decode function (if present) to decode the data.

      * @param {String} id The record's unique ID
      * @return {Ext.data.Model} The model instance
      */
      * @param {String} id The record's unique ID
      * @return {Ext.data.Model} The model instance
      */


@@ -207,14 +217,14 @@ Ext.define('Ext.data.proxy.WebStorage', {
 
             this.cache[id] = record;
         }
 
             this.cache[id] = record;
         }

-        
+

         return this.cache[id];
     },
 
     /**
         return this.cache[id];
     },
 
     /**

-     * Saves the given record in the Proxy. Runs each field's encode function (if present) to encode the data
+     * Saves the given record in the Proxy. Runs each field's encode function (if present) to encode the data.

      * @param {Ext.data.Model} record The model instance
      * @param {Ext.data.Model} record The model instance

-     * @param {String} id The id to save the record under (defaults to the value of the record's getId() function)
+     * @param {String} [id] The id to save the record under (defaults to the value of the record's getId() function)

      */
     setRecord: function(record, id) {
         if (id) {
      */
     setRecord: function(record, id) {
         if (id) {


@@ -245,10 +255,10 @@ Ext.define('Ext.data.proxy.WebStorage', {
 
         obj = me.getStorageObject();
         key = me.getRecordKey(id);
 
         obj = me.getStorageObject();
         key = me.getRecordKey(id);

-        
+

         //keep the cache up to date
         me.cache[id] = record;
         //keep the cache up to date
         me.cache[id] = record;

-        
+

         //iPad bug requires that we remove the item before setting it
         obj.removeItem(key);
         obj.setItem(key, Ext.encode(data));
         //iPad bug requires that we remove the item before setting it
         obj.removeItem(key);
         obj.setItem(key, Ext.encode(data));


@@ -258,12 +268,12 @@ Ext.define('Ext.data.proxy.WebStorage', {
      * @private
      * Physically removes a given record from the local storage. Used internally by {@link #destroy}, which you should
      * use instead because it updates the list of currently-stored record ids
      * @private
      * Physically removes a given record from the local storage. Used internally by {@link #destroy}, which you should
      * use instead because it updates the list of currently-stored record ids

-     * @param {String|Number|Ext.data.Model} id The id of the record to remove, or an Ext.data.Model instance
+     * @param {String/Number/Ext.data.Model} id The id of the record to remove, or an Ext.data.Model instance

      */
     removeRecord: function(id, updateIds) {
         var me = this,
             ids;
      */
     removeRecord: function(id, updateIds) {
         var me = this,
             ids;

-            
+

         if (id.isModel) {
             id = id.getId();
         }
         if (id.isModel) {
             id = id.getId();
         }


@@ -281,7 +291,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
      * @private
      * Given the id of a record, returns a unique string based on that id and the id of this proxy. This is used when
      * storing data in the local storage object and should prevent naming collisions.
      * @private
      * Given the id of a record, returns a unique string based on that id and the id of this proxy. This is used when
      * storing data in the local storage object and should prevent naming collisions.

-     * @param {String|Number|Ext.data.Model} id The record id, or a Model instance
+     * @param {String/Number/Ext.data.Model} id The record id, or a Model instance

      * @return {String} The unique key for this record
      */
     getRecordKey: function(id) {
      * @return {String} The unique key for this record
      */
     getRecordKey: function(id) {


@@ -305,7 +315,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
     /**
      * @private
      * Returns the array of record IDs stored in this Proxy
     /**
      * @private
      * Returns the array of record IDs stored in this Proxy

-     * @return {Array} The record IDs. Each is cast as a Number
+     * @return {Number[]} The record IDs. Each is cast as a Number

      */
     getIds: function() {
         var ids    = (this.getStorageObject().getItem(this.id) || "").split(","),
      */
     getIds: function() {
         var ids    = (this.getStorageObject().getItem(this.id) || "").split(","),


@@ -326,14 +336,14 @@ Ext.define('Ext.data.proxy.WebStorage', {
     /**
      * @private
      * Saves the array of ids representing the set of all records in the Proxy
     /**
      * @private
      * Saves the array of ids representing the set of all records in the Proxy

-     * @param {Array} ids The ids to set
+     * @param {Number[]} ids The ids to set

      */
     setIds: function(ids) {
         var obj = this.getStorageObject(),
             str = ids.join(",");
      */
     setIds: function(ids) {
         var obj = this.getStorageObject(),
             str = ids.join(",");

-        
+

         obj.removeItem(this.id);
         obj.removeItem(this.id);

-        
+

         if (!Ext.isEmpty(str)) {
             obj.setItem(this.id, str);
         }
         if (!Ext.isEmpty(str)) {
             obj.setItem(this.id, str);
         }


@@ -341,8 +351,8 @@ Ext.define('Ext.data.proxy.WebStorage', {
 
     /**
      * @private
 
     /**
      * @private

-     * Returns the next numerical ID that can be used when realizing a model instance (see getRecordCounterKey). Increments
-     * the counter.
+     * Returns the next numerical ID that can be used when realizing a model instance (see getRecordCounterKey).
+     * Increments the counter.

      * @return {Number} The id
      */
     getNextId: function() {
      * @return {Number} The id
      */
     getNextId: function() {


@@ -350,15 +360,15 @@ Ext.define('Ext.data.proxy.WebStorage', {
             key  = this.getRecordCounterKey(),
             last = obj.getItem(key),
             ids, id;
             key  = this.getRecordCounterKey(),
             last = obj.getItem(key),
             ids, id;

-        
+

         if (last === null) {
             ids = this.getIds();
             last = ids[ids.length - 1] || 0;
         }
         if (last === null) {
             ids = this.getIds();
             last = ids[ids.length - 1] || 0;
         }

-        
+

         id = parseInt(last, 10) + 1;
         obj.setItem(key, id);
         id = parseInt(last, 10) + 1;
         obj.setItem(key, id);

-        
+

         return id;
     },
 
         return id;
     },
 


@@ -373,7 +383,8 @@ Ext.define('Ext.data.proxy.WebStorage', {
     },
 
     /**
     },
 
     /**

-     * Destroys all records stored in the proxy and removes all keys and values used to support the proxy from the storage object
+     * Destroys all records stored in the proxy and removes all keys and values used to support the proxy from the
+     * storage object.

      */
     clear: function() {
         var obj = this.getStorageObject(),
      */
     clear: function() {
         var obj = this.getStorageObject(),


@@ -402,4 +413,4 @@ Ext.define('Ext.data.proxy.WebStorage', {
         Ext.Error.raise("The getStorageObject function has not been defined in your Ext.data.proxy.WebStorage subclass");
         //</debug>
     }
         Ext.Error.raise("The getStorageObject function has not been defined in your Ext.data.proxy.WebStorage subclass");
         //</debug>
     }

-});
\ No newline at end of file
+});