288 lines
11 KiB
JavaScript
288 lines
11 KiB
JavaScript
define("dojo/store/api/Store", ["../../_base/declare"], function(declare){
|
|
|
|
// module:
|
|
// dojo/api/Store
|
|
|
|
var Store = declare(null, {
|
|
// summary:
|
|
// This is an abstract API that data provider implementations conform to.
|
|
// This file defines methods signatures and intentionally leaves all the
|
|
// methods unimplemented. For more information on the ,
|
|
// please visit: http://dojotoolkit.org/reference-guide/dojo/store.html
|
|
// Every method and property is optional, and is only needed if the functionality
|
|
// it provides is required.
|
|
// Every method may return a promise for the specified return value if the
|
|
// execution of the operation is asynchronous (except
|
|
// for query() which already defines an async return value).
|
|
|
|
// idProperty: String
|
|
// If the store has a single primary key, this indicates the property to use as the
|
|
// identity property. The values of this property should be unique.
|
|
idProperty: "id",
|
|
|
|
// queryEngine: Function
|
|
// If the store can be queried locally (on the client side in JS), this defines
|
|
// the query engine to use for querying the data store.
|
|
// This takes a query and query options and returns a function that can execute
|
|
// the provided query on a JavaScript array. The queryEngine may be replace to
|
|
// provide more sophisticated querying capabilities. For example:
|
|
// | var query = store.queryEngine({foo:"bar"}, {count:10});
|
|
// | query(someArray) -> filtered array
|
|
// The returned query function may have a "matches" property that can be
|
|
// used to determine if an object matches the query. For example:
|
|
// | query.matches({id:"some-object", foo:"bar"}) -> true
|
|
// | query.matches({id:"some-object", foo:"something else"}) -> false
|
|
queryEngine: null,
|
|
|
|
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.
|
|
},
|
|
getIdentity: function(object){
|
|
// summary:
|
|
// Returns an object's identity
|
|
// object: Object
|
|
// The object to get the identity from
|
|
// returns: String|Number
|
|
},
|
|
put: function(object, directives){
|
|
// summary:
|
|
// Stores an object
|
|
// object: Object
|
|
// The object to store.
|
|
// directives: dojo/store/api/Store.PutDirectives?
|
|
// Additional directives for storing objects.
|
|
// returns: Number|String
|
|
},
|
|
add: function(object, directives){
|
|
// summary:
|
|
// Creates an object, throws an error if the object already exists
|
|
// object: Object
|
|
// The object to store.
|
|
// directives: dojo/store/api/Store.PutDirectives?
|
|
// Additional directives for creating objects.
|
|
// returns: Number|String
|
|
},
|
|
remove: function(id){
|
|
// summary:
|
|
// Deletes an object by its identity
|
|
// id: Number
|
|
// The identity to use to delete the object
|
|
delete this.index[id];
|
|
var data = this.data,
|
|
idProperty = this.idProperty;
|
|
for(var i = 0, l = data.length; i < l; i++){
|
|
if(data[i][idProperty] == id){
|
|
data.splice(i, 1);
|
|
return;
|
|
}
|
|
}
|
|
},
|
|
query: function(query, options){
|
|
// summary:
|
|
// Queries the store for objects. This does not alter the store, but returns a
|
|
// set of data from the store.
|
|
// query: String|Object|Function
|
|
// 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:
|
|
//
|
|
// ...find all items where "prime" is true:
|
|
//
|
|
// | store.query({ prime: true }).forEach(function(object){
|
|
// | // handle each object
|
|
// | });
|
|
},
|
|
transaction: function(){
|
|
// summary:
|
|
// Starts a new transaction.
|
|
// Note that a store user might not call transaction() prior to using put,
|
|
// delete, etc. in which case these operations effectively could be thought of
|
|
// as "auto-commit" style actions.
|
|
// returns: dojo/store/api/Store.Transaction
|
|
// This represents the new current transaction.
|
|
},
|
|
getChildren: function(parent, options){
|
|
// summary:
|
|
// Retrieves the children of an object.
|
|
// parent: Object
|
|
// The object to find the children of.
|
|
// options: dojo/store/api/Store.QueryOptions?
|
|
// Additional options to apply to the retrieval of the children.
|
|
// returns: dojo/store/api/Store.QueryResults
|
|
// A result set of the children of the parent object.
|
|
},
|
|
getMetadata: function(object){
|
|
// summary:
|
|
// Returns any metadata about the object. This may include attribution,
|
|
// cache directives, history, or version information.
|
|
// object: Object
|
|
// The object to return metadata for.
|
|
// returns: Object
|
|
// An object containing metadata.
|
|
}
|
|
});
|
|
|
|
Store.PutDirectives = declare(null, {
|
|
// summary:
|
|
// Directives passed to put() and add() handlers for guiding the update and
|
|
// creation of stored objects.
|
|
// id: String|Number?
|
|
// Indicates the identity of the object if a new object is created
|
|
// before: Object?
|
|
// If the collection of objects in the store has a natural ordering,
|
|
// this indicates that the created or updated object should be placed before the
|
|
// object specified by the value of this property. A value of null indicates that the
|
|
// object should be last.
|
|
// parent: Object?,
|
|
// If the store is hierarchical (with single parenting) this property indicates the
|
|
// new parent of the created or updated object.
|
|
// overwrite: Boolean?
|
|
// If this is provided as a boolean it indicates that the object should or should not
|
|
// overwrite an existing object. A value of true indicates that a new object
|
|
// should not be created, the operation should update an existing object. A
|
|
// value of false indicates that an existing object should not be updated, a new
|
|
// object should be created (which is the same as an add() operation). When
|
|
// this property is not provided, either an update or creation is acceptable.
|
|
});
|
|
|
|
Store.SortInformation = declare(null, {
|
|
// summary:
|
|
// An object describing what attribute to sort on, and the direction of the sort.
|
|
// attribute: String
|
|
// The name of the attribute to sort on.
|
|
// descending: Boolean
|
|
// The direction of the sort. Default is false.
|
|
});
|
|
|
|
Store.QueryOptions = declare(null, {
|
|
// summary:
|
|
// Optional object with additional parameters for query results.
|
|
// sort: dojo/store/api/Store.SortInformation[]?
|
|
// A list of attributes to sort on, as well as direction
|
|
// For example:
|
|
// | [{attribute:"price, descending: true}].
|
|
// If the sort parameter is omitted, then the natural order of the store may be
|
|
// applied if there is a natural order.
|
|
// start: Number?
|
|
// The first result to begin iteration on
|
|
// count: Number?
|
|
// The number of how many results should be returned.
|
|
});
|
|
|
|
Store.QueryResults = declare(null, {
|
|
// summary:
|
|
// This is an object returned from query() calls that provides access to the results
|
|
// of a query. Queries may be executed asynchronously.
|
|
|
|
forEach: function(callback, thisObject){
|
|
// summary:
|
|
// Iterates over the query results, based on
|
|
// https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach.
|
|
// Note that this may executed asynchronously. The callback may be called
|
|
// after this function returns.
|
|
// callback:
|
|
// Function that is called for each object in the query results
|
|
// thisObject:
|
|
// The object to use as |this| in the callback.
|
|
|
|
},
|
|
filter: function(callback, thisObject){
|
|
// summary:
|
|
// Filters the query results, based on
|
|
// https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter.
|
|
// Note that this may executed asynchronously. The callback may be called
|
|
// after this function returns.
|
|
// callback:
|
|
// Function that is called for each object in the query results
|
|
// thisObject:
|
|
// The object to use as |this| in the callback.
|
|
// returns: dojo/store/api/Store.QueryResults
|
|
},
|
|
map: function(callback, thisObject){
|
|
// summary:
|
|
// Maps the query results, based on
|
|
// https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map.
|
|
// Note that this may executed asynchronously. The callback may be called
|
|
// after this function returns.
|
|
// callback:
|
|
// Function that is called for each object in the query results
|
|
// thisObject:
|
|
// The object to use as |this| in the callback.
|
|
// returns: dojo/store/api/Store.QueryResults
|
|
},
|
|
then: function(callback, errorHandler){
|
|
// summary:
|
|
// This registers a callback for when the query is complete, if the query is asynchronous.
|
|
// This is an optional method, and may not be present for synchronous queries.
|
|
// callback:
|
|
// This is called when the query is completed successfully, and is passed a single argument
|
|
// that is an array representing the query results.
|
|
// errorHandler:
|
|
// This is called if the query failed, and is passed a single argument that is the error
|
|
// for the failure.
|
|
},
|
|
observe: function(listener, includeAllUpdates){
|
|
// summary:
|
|
// This registers a callback for notification of when data is modified in the query results.
|
|
// This is an optional method, and is usually provided by dojo/store/Observable.
|
|
// listener: Function
|
|
// The listener function is called when objects in the query results are modified
|
|
// to affect the query result. The listener function is called with the following arguments:
|
|
// | listener(object, removedFrom, insertedInto);
|
|
//
|
|
// - The object parameter indicates the object that was create, modified, or deleted.
|
|
// - The removedFrom parameter indicates the index in the result array where
|
|
// the object used to be. If the value is -1, then the object is an addition to
|
|
// this result set (due to a new object being created, or changed such that it
|
|
// is a part of the result set).
|
|
// - The insertedInto parameter indicates the index in the result array where
|
|
// the object should be now. If the value is -1, then the object is a removal
|
|
// from this result set (due to an object being deleted, or changed such that it
|
|
// is not a part of the result set).
|
|
// includeAllUpdates:
|
|
// This indicates whether or not to include object updates that do not affect
|
|
// the inclusion or order of the object in the query results. By default this is false,
|
|
// which means that if any object is updated in such a way that it remains
|
|
// in the result set and it's position in result sets is not affected, then the listener
|
|
// will not be fired.
|
|
|
|
},
|
|
// total: Number|Promise?
|
|
// This property should be included in if the query options included the "count"
|
|
// property limiting the result set. This property indicates the total number of objects
|
|
// matching the query (as if "start" and "count" weren't present). This may be
|
|
// a promise if the query is asynchronous.
|
|
total: 0
|
|
});
|
|
|
|
Store.Transaction = declare(null, {
|
|
// summary:
|
|
// This is an object returned from transaction() calls that represents the current
|
|
// transaction.
|
|
|
|
commit: function(){
|
|
// summary:
|
|
// Commits the transaction. This may throw an error if it fails. Of if the operation
|
|
// is asynchronous, it may return a promise that represents the eventual success
|
|
// or failure of the commit.
|
|
},
|
|
abort: function(callback, thisObject){
|
|
// summary:
|
|
// Aborts the transaction. This may throw an error if it fails. Of if the operation
|
|
// is asynchronous, it may return a promise that represents the eventual success
|
|
// or failure of the abort.
|
|
}
|
|
});
|
|
return Store;
|
|
});
|