add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / data / identifier / Generator.js

/**\r
 * This class is a base for all id generators. It also provides lookup of id generators by\r
 * their id.\r
 * \r
 * Generally, id generators are used to generate a primary key for new model instances. There\r
 * are different approaches to solving this problem, so this mechanism has both simple use\r
 * cases and is open to custom implementations. A {@link Ext.data.Model} requests id generation\r
 * using the {@link Ext.data.Model#identifier} property.\r
 *\r
 * The following types of `identifiers` are provided:\r
 *\r
 *   * `{@link Ext.data.identifier.Sequential sequential}`\r
 *   * `{@link Ext.data.identifier.Negative negative}`\r
 *   * `{@link Ext.data.identifier.Uuid uuid}`\r
 *\r
 * In most cases (other than `uuid`), the server is the only party that can generate\r
 * authoritative id values. This means that any id generated by an `identifier` should be\r
 * consider "provisional" and must eventually be reconciled with the server. This makes a\r
 * `uuid` very attractive as an `identifier` because they are designed to be generated in\r
 * a distributed manner and therefore never require reconciliation.\r
 *\r
 * It is common for id values to be generated as increasing integer values (1, 2, etc.) by\r
 * the server when records are inserted. A `{@link Ext.data.identifier.Negative negative}`\r
 * `identifier` may be useful as it generates client-side values of -1, -2, etc.. These\r
 * values are of the same data type (integer) and so can typically be read by servers\r
 * using typed languages (such as Java or C#) and easily recognized as provisional.\r
 *\r
 * In the end, the choice of `identifier` strategy requires agreement between client and\r
 * server.\r
 *\r
 * # Identity, Type and Shared Generators\r
 *\r
 * It is often desirable to share Generators to ensure uniqueness or common configuration.\r
 * This is done by giving Generator instances an id property by which they can be looked\r
 * up using the {@link Ext.Factory#dataIdentifier dataIdentifier} method. To configure two {@link Ext.data.Model Model} classes\r
 * to share one {@link Ext.data.identifier.Sequential sequential} id generator, you simply\r
 * assign them the same id:\r
 *\r
 *     Ext.define('MyApp.data.MyModelA', {\r
 *         extend: 'Ext.data.Model',\r
 *         identifier: {\r
 *             type: 'sequential',\r
 *             id: 'foo'\r
 *         }\r
 *     });\r
 *\r
 *     Ext.define('MyApp.data.MyModelB', {\r
 *         extend: 'Ext.data.Model',\r
 *         identifier: {\r
 *             type: 'sequential',\r
 *             id: 'foo'\r
 *         }\r
 *     });\r
 *\r
 * To make this as simple as possible for generator types that are shared by many (or all)\r
 * Models, the Generator types (such as 'sequential' or 'uuid') are also reserved as\r
 * generator ids. This is used by the {@link Ext.data.identifier.Uuid} which has an id equal\r
 * to its type ('uuid'). In other words, the following Models share the same generator:\r
 *\r
 *     Ext.define('MyApp.data.MyModelX', {\r
 *         extend: 'Ext.data.Model',\r
 *         identifier: 'uuid'\r
 *     });\r
 *\r
 *     Ext.define('MyApp.data.MyModelY', {\r
 *         extend: 'Ext.data.Model',\r
 *         identifier: 'uuid'\r
 *     });\r
 *\r
 * This can be overridden (by specifying the id explicitly), but there is no particularly\r
 * good reason to do so for this generator type.\r
 *\r
 * # Creating Custom Generators\r
 * \r
 * An id generator should derive from this class and implement the {@link #generate} method.\r
 *\r
 * To register an id generator type, a derived class should provide an `alias` like so:\r
 *\r
 *     Ext.define('MyApp.data.identifier.Custom', {\r
 *         extend: 'Ext.data.identifier.Generator',\r
 *         alias: 'data.identifier.custom',\r
 *         config: {\r
 *             configProp: 42 // some config property w/default value\r
 *         }\r
 *\r
 *         generate: function () {\r
 *             return ... // a new id\r
 *         }\r
 *     });\r
 *\r
 * Using the custom id generator is then straightforward:\r
 *\r
 *     Ext.define('MyApp.data.MyModel', {\r
 *         extend: 'Ext.data.Model',\r
 *         identifier: 'custom'\r
 *     });\r
 *     // or...\r
 *\r
 *     Ext.define('MyApp.data.MyModel', {\r
 *         extend: 'Ext.data.Model',\r
 *         identifier: {\r
 *             type: 'custom',\r
 *             configProp: value\r
 *         }\r
 *     });\r
 *\r
 * It is not recommended to mix shared generators with generator configuration. This leads\r
 * to unpredictable results unless all configurations match (which is also redundant). In\r
 * such cases, a custom generator with a default id is the best approach.\r
 *\r
 *     Ext.define('MyApp.data.identifier.Custom', {\r
 *         extend: 'Ext.data.identifier.Sequential',\r
 *         alias: 'data.identifier.custom',\r
 *         \r
 *         config: {\r
 *             id: 'custom',\r
 *             prefix: 'ID_',\r
 *             seed: 1000\r
 *         }\r
 *     });\r
 *\r
 *     Ext.define('MyApp.data.MyModelX', {\r
 *         extend: 'Ext.data.Model',\r
 *         identifier: 'custom'\r
 *     });\r
 *\r
 *     Ext.define('MyApp.data.MyModelY', {\r
 *         extend: 'Ext.data.Model',\r
 *         identifier: 'custom'\r
 *     });\r
 *\r
 *     // the above models share a generator that produces ID_1000, ID_1001, etc..\r
 *\r
 */\r
Ext.define('Ext.data.identifier.Generator', {\r
    'abstract': true,\r
\r
    mixins: [\r
        'Ext.mixin.Factoryable'\r
    ],\r
\r
    alias: 'data.identifier.default',  // this is used by Factoryable\r
\r
    factoryConfig: {\r
        defaultType: 'sequential'  // this is not a suitable type to create\r
    },\r
\r
    /**\r
     * @property {Boolean} isGenerator\r
     * `true` in this class to identify an object as an instantiated IdGenerator, or subclass thereof.\r
     */\r
    isGenerator: true,\r
\r
    config: {\r
        /**\r
         * @cfg {String} id\r
         * The id for this generator.\r
         */\r
        id: null\r
    },\r
\r
    /**\r
     * Initializes a new instance.\r
     * @param {Object} config (optional) Configuration object to be applied to the new instance.\r
     */\r
    constructor: function (config) {\r
        var me = this,\r
            cache, id;\r
\r
        me.initConfig(config);\r
\r
        id = me.getId();\r
        if (id) {\r
            cache = (config && config.cache) || Ext.data.identifier.Generator.all;\r
            cache[id] = me;\r
        }\r
    },\r
\r
    /**\r
     * Generates and returns the next id. This method must be implemented by the derived\r
     * class.\r
     *\r
     * @return {Number/String} The next id.\r
     * @method generate\r
     * @abstract\r
     */\r
\r
    privates: {\r
        /**\r
         * Create a copy of this identifier.\r
         * @private\r
         * @return {Ext.data.identifier.Generator} The clone\r
         */\r
        clone: function (config) {\r
            var cfg = this.getInitialConfig();\r
            cfg = config ? Ext.apply({}, config, cfg) : cfg;\r
            return new this.self(cfg);\r
        },\r
\r
        statics: {\r
            /**\r
             * @property {Object} all\r
             * This object is keyed by id to lookup instances.\r
             * @private\r
             * @static\r
             */\r
            all: {}\r
        }\r
    }\r
},\r
function () {\r
    var Generator = this,\r
        Factory = Ext.Factory,\r
        factory = Factory.dataIdentifier;\r
\r
    // If there is an id property passed we need to lookup that id in the cache. If that\r
    // produces a cache miss, call the normal factory.\r
    /**\r
     * @member Ext.Factory\r
     * @method dataIdentifier\r
     * Returns an instance of an ID generator based on the ID you pass in.\r
     * @param {string} id\r
     * @return {Object} Ext.data.identifier.* The data identifier\r
     */\r
    Factory.dataIdentifier = function (config) {\r
        var id = Ext.isString(config) ? config : (config && config.id),\r
            existing = id && ((config && config.cache) || Generator.all)[id];\r
\r
        return existing || factory(config);\r
    };\r
});\r