docs/source/IdGenerator.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-data-IdGenerator'>/**
  19 </span> * @author Don Griffin
  20  *
  21  * This class is a base for all id generators. It also provides lookup of id generators by
  22  * their id.
  23  *
  24  * Generally, id generators are used to generate a primary key for new model instances. There
  25  * are different approaches to solving this problem, so this mechanism has both simple use
  26  * cases and is open to custom implementations. A {@link Ext.data.Model} requests id generation
  27  * using the {@link Ext.data.Model#idgen} property.
  28  *
  29  * # Identity, Type and Shared IdGenerators
  30  *
  31  * It is often desirable to share IdGenerators to ensure uniqueness or common configuration.
  32  * This is done by giving IdGenerator instances an id property by which they can be looked
  33  * up using the {@link #get} method. To configure two {@link Ext.data.Model Model} classes
  34  * to share one {@link Ext.data.SequentialIdGenerator sequential} id generator, you simply
  35  * assign them the same id:
  36  *
  37  *     Ext.define('MyApp.data.MyModelA', {
  38  *         extend: 'Ext.data.Model',
  39  *         idgen: {
  40  *             type: 'sequential',
  41  *             id: 'foo'
  42  *         }
  43  *     });
  44  *
  45  *     Ext.define('MyApp.data.MyModelB', {
  46  *         extend: 'Ext.data.Model',
  47  *         idgen: {
  48  *             type: 'sequential',
  49  *             id: 'foo'
  50  *         }
  51  *     });
  52  *
  53  * To make this as simple as possible for generator types that are shared by many (or all)
  54  * Models, the IdGenerator types (such as 'sequential' or 'uuid') are also reserved as
  55  * generator id's. This is used by the {@link Ext.data.UuidGenerator} which has an id equal
  56  * to its type ('uuid'). In other words, the following Models share the same generator:
  57  *
  58  *     Ext.define('MyApp.data.MyModelX', {
  59  *         extend: 'Ext.data.Model',
  60  *         idgen: 'uuid'
  61  *     });
  62  *
  63  *     Ext.define('MyApp.data.MyModelY', {
  64  *         extend: 'Ext.data.Model',
  65  *         idgen: 'uuid'
  66  *     });
  67  *
  68  * This can be overridden (by specifying the id explicitly), but there is no particularly
  69  * good reason to do so for this generator type.
  70  *
  71  * # Creating Custom Generators
  72  *
  73  * An id generator should derive from this class and implement the {@link #generate} method.
  74  * The constructor will apply config properties on new instances, so a constructor is often
  75  * not necessary.
  76  *
  77  * To register an id generator type, a derived class should provide an `alias` like so:
  78  *
  79  *     Ext.define('MyApp.data.CustomIdGenerator', {
  80  *         extend: 'Ext.data.IdGenerator',
  81  *         alias: 'idgen.custom',
  82  *
  83  *         configProp: 42, // some config property w/default value
  84  *
  85  *         generate: function () {
  86  *             return ... // a new id
  87  *         }
  88  *     });
  89  *
  90  * Using the custom id generator is then straightforward:
  91  *
  92  *     Ext.define('MyApp.data.MyModel', {
  93  *         extend: 'Ext.data.Model',
  94  *         idgen: 'custom'
  95  *     });
  96  *     // or...
  97  *
  98  *     Ext.define('MyApp.data.MyModel', {
  99  *         extend: 'Ext.data.Model',
 100  *         idgen: {
 101  *             type: 'custom',
 102  *             configProp: value
 103  *         }
 104  *     });
 105  *
 106  * It is not recommended to mix shared generators with generator configuration. This leads
 107  * to unpredictable results unless all configurations match (which is also redundant). In
 108  * such cases, a custom generator with a default id is the best approach.
 109  *
 110  *     Ext.define('MyApp.data.CustomIdGenerator', {
 111  *         extend: 'Ext.data.SequentialIdGenerator',
 112  *         alias: 'idgen.custom',
 113  *
 114  *         id: 'custom', // shared by default
 115  *
 116  *         prefix: 'ID_',
 117  *         seed: 1000
 118  *     });
 119  *
 120  *     Ext.define('MyApp.data.MyModelX', {
 121  *         extend: 'Ext.data.Model',
 122  *         idgen: 'custom'
 123  *     });
 124  *
 125  *     Ext.define('MyApp.data.MyModelY', {
 126  *         extend: 'Ext.data.Model',
 127  *         idgen: 'custom'
 128  *     });
 129  *
 130  *     // the above models share a generator that produces ID_1000, ID_1001, etc..
 131  *
 132  */
 133 Ext.define('Ext.data.IdGenerator', {
 134
 135     isGenerator: true,
 136
 137 <span id='Ext-data-IdGenerator-method-constructor'>    /**
 138 </span>     * Initializes a new instance.
 139      * @param {Object} config (optional) Configuration object to be applied to the new instance.
 140      */
 141     constructor: function(config) {
 142         var me = this;
 143
 144         Ext.apply(me, config);
 145
 146         if (me.id) {
 147             Ext.data.IdGenerator.all[me.id] = me;
 148         }
 149     },
 150
 151 <span id='Ext-data-IdGenerator-cfg-id'>    /**
 152 </span>     * @cfg {String} id
 153      * The id by which to register a new instance. This instance can be found using the
 154      * {@link Ext.data.IdGenerator#get} static method.
 155      */
 156
 157     getRecId: function (rec) {
 158         return rec.modelName + '-' + rec.internalId;
 159     },
 160
 161 <span id='Ext-data-IdGenerator-method-generate'>    /**
 162 </span>     * Generates and returns the next id. This method must be implemented by the derived
 163      * class.
 164      *
 165      * @return {String} The next id.
 166      * @method generate
 167      * @abstract
 168      */
 169
 170     statics: {
 171 <span id='Ext-data-IdGenerator-static-property-all'>        /**
 172 </span>         * @property {Object} all
 173          * This object is keyed by id to lookup instances.
 174          * @private
 175          * @static
 176          */
 177         all: {},
 178
 179 <span id='Ext-data-IdGenerator-static-method-get'>        /**
 180 </span>         * Returns the IdGenerator given its config description.
 181          * @param {String/Object} config If this parameter is an IdGenerator instance, it is
 182          * simply returned. If this is a string, it is first used as an id for lookup and
 183          * then, if there is no match, as a type to create a new instance. This parameter
 184          * can also be a config object that contains a `type` property (among others) that
 185          * are used to create and configure the instance.
 186          * @static
 187          */
 188         get: function (config) {
 189             var generator,
 190                 id,
 191                 type;
 192
 193             if (typeof config == 'string') {
 194                 id = type = config;
 195                 config = null;
 196             } else if (config.isGenerator) {
 197                 return config;
 198             } else {
 199                 id = config.id || config.type;
 200                 type = config.type;
 201             }
 202
 203             generator = this.all[id];
 204             if (!generator) {
 205                 generator = Ext.create('idgen.' + type, config);
 206             }
 207
 208             return generator;
 209         }
 210     }
 211 });
 212 </pre>
 213 </body>
 214 </html>