1 /*

     2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.

     3 Code licensed under the BSD License:

     4 http://developer.yahoo.net/yui/license.txt

     5 version: 3.0.0

     6 build: 1549

     7 */

     8 YUI.add('cache', function(Y) {

     9 

    10 /**

    11  * The Cache utility provides a common configurable interface for components to

    12  * cache and retrieve data from a local JavaScript struct.

    13  *

    14  * @module cache

    15  */

    16 var LANG = Y.Lang,

    17 

    18 /**

    19  * Base class for the YUI Cache utility.

    20  * @class Cache

    21  * @extends Plugin.Base

    22  * @constructor

    23  */    

    24 Cache = function() {

    25     Cache.superclass.constructor.apply(this, arguments);

    26 };

    27     

    28     /////////////////////////////////////////////////////////////////////////////

    29     //

    30     // Cache static properties

    31     //

    32     /////////////////////////////////////////////////////////////////////////////

    33 Y.mix(Cache, {

    34     /**

    35      * The namespace for the plugin. This will be the property on the host which

    36      * references the plugin instance.

    37      *

    38      * @property NS

    39      * @type String

    40      * @static

    41      * @final

    42      * @value "cache"

    43      */

    44     NS: "cache",

    45 

    46     

    47     /**

    48      * Class name.

    49      *

    50      * @property NAME

    51      * @type String

    52      * @static     

    53      * @final

    54      * @value "cache"

    55      */

    56     NAME: "cache",

    57 

    58 

    59     ATTRS: {

    60         /////////////////////////////////////////////////////////////////////////////

    61         //

    62         // Cache Attributes

    63         //

    64         /////////////////////////////////////////////////////////////////////////////

    65         

    66         /**

    67         * @attribute max

    68         * @description Maximum number of entries the Cache can hold.

    69         * Set to 0 to turn off caching.

    70         * @type Number

    71         * @default 0

    72         */

    73         max: {

    74             value: 0,

    75             validator: function(value) {

    76                 return (LANG.isNumber(value));

    77             },

    78             setter: function(value) {

    79                 // If the cache is full, make room by removing stalest element (index=0)

    80                 var entries = this._entries;

    81                 if(value > 0) {

    82                     if(entries) {

    83                         while(entries.length > value) {

    84                             entries.shift();

    85                         }

    86                     }

    87                 }

    88                 else {

    89                     this._entries = [];

    90                 }

    91                 return value;

    92             }

    93         },

    94         

    95         /**

    96         * @attribute size

    97         * @description Number of entries currently cached.

    98         * @type Number

    99         */

   100         size: {

   101             readOnly: true,

   102             getter: function() {

   103                 return this._entries.length;

   104             }

   105         },

   106 

   107         /**

   108         * @attribute uniqueKeys

   109         * @description Validate uniqueness of stored keys. Default is false and

   110         * is more performant.

   111         * @type Number

   112         */

   113         uniqueKeys: {

   114             value: false,

   115             validator: function(value) {

   116                 return (LANG.isBoolean(value));

   117             }

   118         },

   119 

   120         /**

   121          * @attribute entries

   122          * @description Cached entries.

   123          * @type Array

   124          */

   125         entries: {

   126             readOnly: true,

   127             getter: function() {

   128                 return this._entries;

   129             }

   130         }

   131     }

   132 });

   133     

   134 Y.extend(Cache, Y.Plugin.Base, {

   135     /////////////////////////////////////////////////////////////////////////////

   136     //

   137     // Cache private properties

   138     //

   139     /////////////////////////////////////////////////////////////////////////////

   140     

   141     /**

   142      * Array of request/response objects indexed chronologically.

   143      *

   144      * @property _entries

   145      * @type Object[]

   146      * @private

   147      */

   148     _entries: null,

   149 

   150     /////////////////////////////////////////////////////////////////////////////

   151     //

   152     // Cache private methods

   153     //

   154     /////////////////////////////////////////////////////////////////////////////

   155 

   156     /**

   157     * @method initializer

   158     * @description Internal init() handler.

   159     * @param config {Object} Config object.

   160     * @private        

   161     */

   162     initializer: function(config) {

   163 

   164         /**

   165         * @event add

   166         * @description Fired when an entry is added.

   167         * @param e {Event.Facade} Event Facade with the following properties:

   168          * <dl>

   169          * <dt>entry (Object)</dt> <dd>The cached entry.</dd>

   170          * </dl>

   171         * @preventable _defAddFn

   172         */

   173         this.publish("add", {defaultFn: this._defAddFn});

   174 

   175         /**

   176         * @event flush

   177         * @description Fired when the cache is flushed.

   178         * @param e {Event.Facade} Event Facade object.

   179         * @preventable _defFlushFn

   180         */

   181         this.publish("flush", {defaultFn: this._defFlushFn});

   182 

   183         /**

   184         * @event request

   185         * @description Fired when an entry is requested from the cache.

   186         * @param e {Event.Facade} Event Facade with the following properties:

   187         * <dl>

   188         * <dt>request (Object)</dt> <dd>The request object.</dd>

   189         * </dl>

   190         */

   191 

   192         /**

   193         * @event retrieve

   194         * @description Fired when an entry is retrieved from the cache.

   195         * @param e {Event.Facade} Event Facade with the following properties:

   196         * <dl>

   197         * <dt>entry (Object)</dt> <dd>The retrieved entry.</dd>

   198         * </dl>

   199         */

   200 

   201         // Initialize internal values

   202         this._entries = [];

   203         Y.log("Cache initialized", "info", "cache");

   204     },

   205 

   206     /**

   207     * @method destructor

   208     * @description Internal destroy() handler.

   209     * @private        

   210     */

   211     destructor: function() {

   212         this._entries = null;

   213         Y.log("Cache destroyed", "info", "cache");

   214     },

   215 

   216     /////////////////////////////////////////////////////////////////////////////

   217     //

   218     // Cache protected methods

   219     //

   220     /////////////////////////////////////////////////////////////////////////////

   221 

   222     /**

   223      * Adds entry to cache.

   224      *

   225      * @method _defAddFn

   226      * @param e {Event.Facade} Event Facade with the following properties:

   227      * <dl>

   228      * <dt>entry (Object)</dt> <dd>The cached entry.</dd>

   229      * </dl>

   230      * @protected

   231      */

   232     _defAddFn: function(e) {

   233         var entries = this._entries,

   234             max = this.get("max"),

   235             entry = e.entry;

   236 

   237         if(this.get("uniqueKeys") && (this.retrieve(e.entry.request))) {

   238             entries.shift();

   239         }

   240 

   241             

   242         // If the cache at or over capacity, make room by removing stalest element (index=0)

   243         while(entries.length>=max) {

   244             entries.shift();

   245         }

   246     

   247         // Add entry to cache in the newest position, at the end of the array

   248         entries[entries.length] = entry;

   249         Y.log("Cached entry: " + Y.dump(entry), "info", "cache");

   250     },

   251 

   252     /**

   253      * Flushes cache.

   254      *

   255      * @method _defFlushFn

   256      * @param e {Event.Facade} Event Facade object.

   257      * @protected     

   258      */

   259     _defFlushFn: function(e) {

   260         this._entries = [];

   261         Y.log("Cache flushed", "info", "cache");

   262     },

   263 

   264     /**

   265      * Default overridable method compares current request with given cache entry.

   266      * Returns true if current request matches the cached request, otherwise

   267      * false. Implementers should override this method to customize the

   268      * cache-matching algorithm.

   269      *

   270      * @method _isMatch

   271      * @param request {Object} Request object.

   272      * @param entry {Object} Cached entry.

   273      * @return {Boolean} True if current request matches given cached request, false otherwise.

   274      * @protected

   275      */

   276     _isMatch: function(request, entry) {

   277         return (request === entry.request);

   278     },

   279 

   280     /////////////////////////////////////////////////////////////////////////////

   281     //

   282     // Cache public methods

   283     //

   284     /////////////////////////////////////////////////////////////////////////////

   285 

   286     /**

   287      * Adds a new entry to the cache of the format

   288      * {request:request, response:response, payload:payload}.

   289      * If cache is full, evicts the stalest entry before adding the new one.

   290      *

   291      * @method add

   292      * @param request {Object} Request value.

   293      * @param response {Object} Response value.

   294      * @param payload {Object} (optional) Arbitrary data payload.

   295      */

   296     add: function(request, response, payload) {

   297         if(this.get("entries") && (this.get("max")>0) &&

   298                 (LANG.isValue(request) || LANG.isNull(request) || LANG.isUndefined(request))) {

   299             this.fire("add", {entry: {request:request, response:response, payload:payload}});

   300         }

   301         else {

   302             Y.log("Could not add " + Y.dump(response) + " to cache for " + Y.dump(request), "info", "cache");

   303         }

   304     },

   305 

   306     /**

   307      * Flushes cache.

   308      *

   309      * @method flush

   310      */

   311     flush: function() {

   312         this.fire("flush");

   313     },

   314 

   315     /**

   316      * Retrieves cached entry for given request, if available, and refreshes

   317      * entry in the cache. Returns null if there is no cache match.

   318      *

   319      * @method retrieve

   320      * @param request {Object} Request object.

   321      * @return {Object} Cached entry object with the properties request, response, and payload, or null.

   322      */

   323     retrieve: function(request) {

   324         // If cache is enabled...

   325         var entries = this._entries,     

   326             length = entries.length,

   327             entry = null,

   328             i = length-1;

   329             

   330         if((this.get("max") > 0) && (length > 0)) {

   331             this.fire("request", {request: request});

   332     

   333             // Loop through each cached entry starting from the newest

   334             for(; i >= 0; i--) {

   335                 entry = entries[i];

   336     

   337                 // Execute matching function

   338                 if(this._isMatch(request, entry)) {

   339                     this.fire("retrieve", {entry: entry});

   340                     

   341                     // Refresh the position of the cache hit

   342                     if(i < length-1) {

   343                         // Remove element from its original location

   344                         entries.splice(i,1);

   345                         // Add as newest

   346                         entries[entries.length] = entry;

   347                         Y.log("Refreshed cache entry: " + Y.dump(entry) + 

   348                                 " for request: " +  Y.dump(request), "info", "cache");

   349                     } 

   350                     

   351                     Y.log("Retrieved cached response: " + Y.dump(entry) +

   352                             " for request: " + Y.dump(request), "info", "cache");

   353                     return entry;

   354                 }

   355             }

   356         }

   357         return null;

   358     }

   359 });

   360     

   361 Y.Cache = Cache;

   362     

   363 

   364 

   365 

   366 }, '3.0.0' ,{requires:['plugin']});