source: Dev/trunk/src/client/dojo/store/Memory.js

define(["../_base/declare", "./util/QueryResults", "./util/SimpleQueryEngine" /*=====, "./api/Store" =====*/],
function(declare, QueryResults, SimpleQueryEngine /*=====, Store =====*/){

// module:
//              dojo/store/Memory

// No base class, but for purposes of documentation, the base class is dojo/store/api/Store
var base = null;
/*===== base = Store; =====*/

return declare("dojo.store.Memory", base, {
        // summary:
        //              This is a basic in-memory object store. It implements dojo/store/api/Store.
        constructor: function(options){
                // summary:
                //              Creates a memory object store.
                // options: dojo/store/Memory
                //              This provides any configuration information that will be mixed into the store.
                //              This should generally include the data property to provide the starting set of data.
                for(var i in options){
                        this[i] = options[i];
                }
                this.setData(this.data || []);
        },
        // data: Array
        //              The array of all the objects in the memory store
        data:null,

        // idProperty: String
        //              Indicates the property to use as the identity property. The values of this
        //              property should be unique.
        idProperty: "id",

        // index: Object
        //              An index of data indices into the data array by id
        index:null,

        // queryEngine: Function
        //              Defines the query engine to use for querying the data store
        queryEngine: SimpleQueryEngine,
        get: function(id){
                // summary:
                //              Retrieves an object by its identity
                // id: Number
                //              The identity to use to lookup the object
                // returns: Object
                //              The object in the store that matches the given id.
                return this.data[this.index[id]];
        },
        getIdentity: function(object){
                // summary:
                //              Returns an object's identity
                // object: Object
                //              The object to get the identity from
                // returns: Number
                return object[this.idProperty];
        },
        put: function(object, options){
                // summary:
                //              Stores an object
                // object: Object
                //              The object to store.
                // options: dojo/store/api/Store.PutDirectives?
                //              Additional metadata for storing the data.  Includes an "id"
                //              property if a specific id is to be used.
                // returns: Number
                var data = this.data,
                        index = this.index,
                        idProperty = this.idProperty;
                var id = object[idProperty] = (options && "id" in options) ? options.id : idProperty in object ? object[idProperty] : Math.random();
                if(id in index){
                        // object exists
                        if(options && options.overwrite === false){
                                throw new Error("Object already exists");
                        }
                        // replace the entry in data
                        data[index[id]] = object;
                }else{
                        // add the new object
                        index[id] = data.push(object) - 1;
                }
                return id;
        },
        add: function(object, options){
                // summary:
                //              Creates an object, throws an error if the object already exists
                // object: Object
                //              The object to store.
                // options: dojo/store/api/Store.PutDirectives?
                //              Additional metadata for storing the data.  Includes an "id"
                //              property if a specific id is to be used.
                // returns: Number
                (options = options || {}).overwrite = false;
                // call put with overwrite being false
                return this.put(object, options);
        },
        remove: function(id){
                // summary:
                //              Deletes an object by its identity
                // id: Number
                //              The identity to use to delete the object
                // returns: Boolean
                //              Returns true if an object was removed, falsy (undefined) if no object matched the id
                var index = this.index;
                var data = this.data;
                if(id in index){
                        data.splice(index[id], 1);
                        // now we have to reindex
                        this.setData(data);
                        return true;
                }
        },
        query: function(query, options){
                // summary:
                //              Queries the store for objects.
                // query: Object
                //              The query to use for retrieving objects from the store.
                // options: dojo/store/api/Store.QueryOptions?
                //              The optional arguments to apply to the resultset.
                // returns: dojo/store/api/Store.QueryResults
                //              The results of the query, extended with iterative methods.
                //
                // example:
                //              Given the following store:
                //
                //      |       var store = new Memory({
                //      |               data: [
                //      |                       {id: 1, name: "one", prime: false },
                //      |                       {id: 2, name: "two", even: true, prime: true},
                //      |                       {id: 3, name: "three", prime: true},
                //      |                       {id: 4, name: "four", even: true, prime: false},
                //      |                       {id: 5, name: "five", prime: true}
                //      |               ]
                //      |       });
                //
                //      ...find all items where "prime" is true:
                //
                //      |       var results = store.query({ prime: true });
                //
                //      ...or find all items where "even" is true:
                //
                //      |       var results = store.query({ even: true });
                return QueryResults(this.queryEngine(query, options)(this.data));
        },
        setData: function(data){
                // summary:
                //              Sets the given data as the source for this store, and indexes it
                // data: Object[]
                //              An array of objects to use as the source of data.
                if(data.items){
                        // just for convenience with the data format IFRS expects
                        this.idProperty = data.identifier;
                        data = this.data = data.items;
                }else{
                        this.data = data;
                }
                this.index = {};
                for(var i = 0, l = data.length; i < l; i++){
                        this.index[data[i][this.idProperty]] = i;
                }
        }
});

});