/*
- Copyright (c) 2004-2010, The Dojo Foundation All Rights Reserved.
+ Copyright (c) 2004-2011, The Dojo Foundation All Rights Reserved.
Available via Academic Free License >= 2.1 OR the modified BSD license.
see: http://dojotoolkit.org/license for details
*/
dojo.provide("dojo.data.api.Read");
dojo.require("dojo.data.api.Request");
+
dojo.declare("dojo.data.api.Read", null, {
// summary:
- // This is an abstract API that data provider implementations conform to.
+ // 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 dojo.data APIs,
+ // methods unimplemented. For more information on the dojo.data APIs,
// please visit: http://www.dojotoolkit.org/node/98
- getValue: function( /* item */ item,
- /* attribute-name-string */ attribute,
+ getValue: function( /* item */ item,
+ /* attribute-name-string */ attribute,
/* value? */ defaultValue){
// summary:
// Returns a single attribute value.
// Returns defaultValue if and only if *item* does not have a value for *attribute*.
// Returns null if and only if null was explicitly set as the attribute value.
// Returns undefined if and only if the item does not have a value for the
- // given attribute (which is the same as saying the item does not have the attribute).
+ // given attribute (which is the same as saying the item does not have the attribute).
// description:
// Saying that an "item x does not have a value for an attribute y"
- // is identical to saying that an "item x does not have attribute y".
- // It is an oxymoron to say "that attribute is present but has no values"
+ // is identical to saying that an "item x does not have attribute y".
+ // It is an oxymoron to say "that attribute is present but has no values"
// or "the item has that attribute but does not have any attribute values".
// If store.hasAttribute(item, attribute) returns false, then
// store.getValue(item, attribute) will return undefined.
},
containsValue: function(/* item */ item,
- /* attribute-name-string */ attribute,
+ /* attribute-name-string */ attribute,
/* anything */ value){
// summary:
// Returns true if the given *value* is one of the values that getValues()
isItem: function(/* anything */ something){
// summary:
- // Returns true if *something* is an item and came from the store instance.
- // Returns false if *something* is a literal, an item from another store instance,
+ // Returns true if *something* is an item and came from the store instance.
+ // Returns false if *something* is a literal, an item from another store instance,
// or is any object other than an item.
//
// something:
// isItemLoaded() returns true before loadItem() is even called,
// then loadItem() need not do any work at all and will not even invoke
// the callback handlers. So, before invoking this method, check that
- // the item has not already been loaded.
+ // the item has not already been loaded.
// keywordArgs:
- // An anonymous object that defines the item to load and callbacks to invoke when the
+ // An anonymous object that defines the item to load and callbacks to invoke when the
// load has completed. The format of the object is as follows:
// {
// item: object,
// parameter, the error object
//
// The *scope* parameter.
- // If a scope object is provided, all of the callback functions (onItem,
+ // If a scope object is provided, all of the callback functions (onItem,
// onError, etc) will be invoked in the context of the scope object.
// In the body of the callback function, the value of the "this"
// keyword will be the scope object. If no scope object is provided,
// the callback functions will be called in the context of dojo.global().
- // For example, onItem.call(scope, item, request) vs.
+ // For example, onItem.call(scope, item, request) vs.
// onItem.call(dojo.global(), item, request)
if(!this.isItemLoaded(keywordArgs.item)){
throw new Error('Unimplemented API: dojo.data.api.Read.loadItem');
// summary:
// Given a query and set of defined options, such as a start and count of items to return,
// this method executes the query and makes the results available as data items.
- // The format and expectations of stores is that they operate in a generally asynchronous
+ // The format and expectations of stores is that they operate in a generally asynchronous
// manner, therefore callbacks are always used to return items located by the fetch parameters.
//
// description:
// A Request object will always be returned and is returned immediately.
- // The basic request is nothing more than the keyword args passed to fetch and
- // an additional function attached, abort(). The returned request object may then be used
- // to cancel a fetch. All data items returns are passed through the callbacks defined in the
+ // The basic request is nothing more than the keyword args passed to fetch and
+ // an additional function attached, abort(). The returned request object may then be used
+ // to cancel a fetch. All data items returns are passed through the callbacks defined in the
// fetch parameters and are not present on the 'request' object.
//
// This does not mean that custom stores can not add methods and properties to the request object
- // returned, only that the API does not require it. For more info about the Request API,
+ // returned, only that the API does not require it. For more info about the Request API,
// see dojo.data.api.Request
//
// keywordArgs:
- // The keywordArgs parameter may either be an instance of
+ // The keywordArgs parameter may either be an instance of
// conforming to dojo.data.api.Request or may be a simple anonymous object
// that may contain any of the following:
- // {
+ // {
// query: query-object or query-string,
// queryOptions: object,
// onBegin: Function,
// sort: array
// }
// All implementations should accept keywordArgs objects with any of
- // the 9 standard properties: query, onBegin, onItem, onComplete, onError
- // scope, sort, start, and count. Some implementations may accept additional
- // properties in the keywordArgs object as valid parameters, such as
- // {includeOutliers:true}.
+ // the 9 standard properties: query, onBegin, onItem, onComplete, onError
+ // scope, sort, start, and count. Some implementations may accept additional
+ // properties in the keywordArgs object as valid parameters, such as
+ // {includeOutliers:true}.
//
// The *query* parameter.
// The query may be optional in some data store implementations.
// of the query itself -- each different data store implementation
// may have its own notion of what a query should look like.
// However, as of dojo 0.9, 1.0, and 1.1, all the provided datastores in dojo.data
- // and dojox.data support an object structure query, where the object is a set of
+ // and dojox.data support an object structure query, where the object is a set of
// name/value parameters such as { attrFoo: valueBar, attrFoo1: valueBar1}. Most of the
- // dijit widgets, such as ComboBox assume this to be the case when working with a datastore
- // when they dynamically update the query. Therefore, for maximum compatibility with dijit
+ // dijit widgets, such as ComboBox assume this to be the case when working with a datastore
+ // when they dynamically update the query. Therefore, for maximum compatibility with dijit
// widgets the recommended query parameter is a key/value object. That does not mean that the
- // the datastore may not take alternative query forms, such as a simple string, a Date, a number,
- // or a mix of such. Ultimately, The dojo.data.api.Read API is agnostic about what the query
- // format.
- // Further note: In general for query objects that accept strings as attribute
- // value matches, the store should also support basic filtering capability, such as *
+ // the datastore may not take alternative query forms, such as a simple string, a Date, a number,
+ // or a mix of such. Ultimately, The dojo.data.api.Read API is agnostic about what the query
+ // format.
+ // Further note: In general for query objects that accept strings as attribute
+ // value matches, the store should also support basic filtering capability, such as *
// (match any character) and ? (match single character). An example query that is a query object
- // would be like: { attrFoo: "value*"}. Which generally means match all items where they have
+ // would be like: { attrFoo: "value*"}. Which generally means match all items where they have
// an attribute named attrFoo, with a value that starts with 'value'.
//
// The *queryOptions* parameter
// The queryOptions parameter is an optional parameter used to specify optiosn that may modify
// the query in some fashion, such as doing a case insensitive search, or doing a deep search
- // where all items in a hierarchical representation of data are scanned instead of just the root
+ // where all items in a hierarchical representation of data are scanned instead of just the root
// items. It currently defines two options that all datastores should attempt to honor if possible:
// {
// ignoreCase: boolean, //Whether or not the query should match case sensitively or not. Default behaviour is false.
- // deep: boolean //Whether or not a fetch should do a deep search of items and all child
+ // deep: boolean //Whether or not a fetch should do a deep search of items and all child
// //items instead of just root-level items in a datastore. Default is false.
// }
//
// will be called just once, before the first onItem callback is called.
// The onBegin callback function will be passed two arguments, the
// the total number of items identified and the Request object. If the total number is
- // unknown, then size will be -1. Note that size is not necessarily the size of the
- // collection of items returned from the query, as the request may have specified to return only a
+ // unknown, then size will be -1. Note that size is not necessarily the size of the
+ // collection of items returned from the query, as the request may have specified to return only a
// subset of the total set of items through the use of the start and count parameters.
//
// The *onItem* parameter.
// function(item, request);
// If an onItem callback function is provided, the callback function
- // will be called as each item in the result is received. The callback
+ // will be called as each item in the result is received. The callback
// function will be passed two arguments: the item itself, and the
// Request object.
//
// If an onComplete callback function is provided, the callback function
// will be called just once, after the last onItem callback is called.
// Note that if the onItem callback is not present, then onComplete will be passed
- // an array containing all items which matched the query and the request object.
- // If the onItem callback is present, then onComplete is called as:
+ // an array containing all items which matched the query and the request object.
+ // If the onItem callback is present, then onComplete is called as:
// onComplete(null, request).
//
// The *onError* parameter.
- // function(errorData, request);
+ // function(errorData, request);
// If an onError callback function is provided, the callback function
// will be called if there is any sort of error while attempting to
// execute the query.
// an Error object and the Request object.
//
// The *scope* parameter.
- // If a scope object is provided, all of the callback functions (onItem,
+ // If a scope object is provided, all of the callback functions (onItem,
// onComplete, onError, etc) will be invoked in the context of the scope
// object. In the body of the callback function, the value of the "this"
// keyword will be the scope object. If no scope object is provided,
- // the callback functions will be called in the context of dojo.global().
- // For example, onItem.call(scope, item, request) vs.
+ // the callback functions will be called in the context of dojo.global().
+ // For example, onItem.call(scope, item, request) vs.
// onItem.call(dojo.global(), item, request)
//
// The *start* parameter.
- // If a start parameter is specified, this is a indication to the datastore to
+ // If a start parameter is specified, this is a indication to the datastore to
// only start returning items once the start number of items have been located and
// skipped. When this parameter is paired withh 'count', the store should be able
- // to page across queries with millions of hits by only returning subsets of the
+ // to page across queries with millions of hits by only returning subsets of the
// hits for each query
//
// The *count* parameter.
- // If a count parameter is specified, this is a indication to the datastore to
- // only return up to that many items. This allows a fetch call that may have
- // millions of item matches to be paired down to something reasonable.
+ // If a count parameter is specified, this is a indication to the datastore to
+ // only return up to that many items. This allows a fetch call that may have
+ // millions of item matches to be paired down to something reasonable.
//
// The *sort* parameter.
- // If a sort parameter is specified, this is a indication to the datastore to
- // sort the items in some manner before returning the items. The array is an array of
+ // If a sort parameter is specified, this is a indication to the datastore to
+ // sort the items in some manner before returning the items. The array is an array of
// javascript objects that must conform to the following format to be applied to the
// fetching of items:
// {
// descending: true|false; // Optional. Default is false.
// }
// Note that when comparing attributes, if an item contains no value for the attribute
- // (undefined), then it the default ascending sort logic should push it to the bottom
+ // (undefined), then it the default ascending sort logic should push it to the bottom
// of the list. In the descending order case, it such items should appear at the top of the list.
- //
+ //
// returns:
// The fetch() method will return a javascript object conforming to the API
// defined in dojo.data.api.Request. In general, it will be the keywordArgs
// object returned with the required functions in Request.js attached.
// Its general purpose is to provide a convenient way for a caller to abort an
- // ongoing fetch.
- //
+ // ongoing fetch.
+ //
// The Request object may also have additional properties when it is returned
- // such as request.store property, which is a pointer to the datastore object that
+ // such as request.store property, which is a pointer to the datastore object that
// fetch() is a method of.
//
// exceptions:
// | var request = store.fetch(onComplete: showEverything);
// example:
// Fetch only 10 books that match the query 'all books', starting at the fifth book found during the search.
- // This demonstrates how paging can be done for specific queries.
+ // This demonstrates how paging can be done for specific queries.
// | var request = store.fetch({query:"all books", start: 4, count: 10, onComplete: showBooks});
// example:
// Fetch all items that match the query, calling 'callback' each time an item is located.
// and then when the user presses the "Next Page" button...
// | fetchArgs.start += 20;
// | store.fetch(fetchArgs); // get the next 20 items
- var request = null;
+ var request = null;
throw new Error('Unimplemented API: dojo.data.api.Read.fetch');
return request; // an object conforming to the dojo.data.api.Request API
},
getFeatures: function(){
// summary:
- // The getFeatures() method returns an simple keyword values object
- // that specifies what interface features the datastore implements.
- // A simple CsvStore may be read-only, and the only feature it
+ // The getFeatures() method returns an simple keyword values object
+ // that specifies what interface features the datastore implements.
+ // A simple CsvStore may be read-only, and the only feature it
// implements will be the 'dojo.data.api.Read' interface, so the
// getFeatures() method will return an object like this one:
// {'dojo.data.api.Read': true}.
// A more sophisticated datastore might implement a variety of
- // interface features, like 'dojo.data.api.Read', 'dojo.data.api.Write',
+ // interface features, like 'dojo.data.api.Read', 'dojo.data.api.Write',
// 'dojo.data.api.Identity', and 'dojo.data.api.Attribution'.
return {
'dojo.data.api.Read': true
close: function(/*dojo.data.api.Request || keywordArgs || null */ request){
// summary:
- // The close() method is intended for instructing the store to 'close' out
+ // The close() method is intended for instructing the store to 'close' out
// any information associated with a particular request.
//
// description:
- // The close() method is intended for instructing the store to 'close' out
+ // The close() method is intended for instructing the store to 'close' out
// any information associated with a particular request. In general, this API
- // expects to recieve as a parameter a request object returned from a fetch.
- // It will then close out anything associated with that request, such as
+ // expects to recieve as a parameter a request object returned from a fetch.
+ // It will then close out anything associated with that request, such as
// clearing any internal datastore caches and closing any 'open' connections.
// For some store implementations, this call may be a no-op.
//
// An instance of a request for the store to use to identify what to close out.
// If no request is passed, then the store should clear all internal caches (if any)
// and close out all 'open' connections. It does not render the store unusable from
- // there on, it merely cleans out any current data and resets the store to initial
+ // there on, it merely cleans out any current data and resets the store to initial
// state.
//
// example:
getLabel: function(/* item */ item){
// summary:
// Method to inspect the item and return a user-readable 'label' for the item
- // that provides a general/adequate description of what the item is.
+ // that provides a general/adequate description of what the item is.
//
// description:
// Method to inspect the item and return a user-readable 'label' for the item
// most labels will be a specific attribute value or collection of the attribute
// values that combine to label the item in some manner. For example for an item
// that represents a person it may return the label as: "firstname lastlame" where
- // the firstname and lastname are attributes on the item. If the store is unable
+ // the firstname and lastname are attributes on the item. If the store is unable
// to determine an adequate human readable label, it should return undefined. Users that wish
- // to customize how a store instance labels items should replace the getLabel() function on
- // their instance of the store, or extend the store and replace the function in
+ // to customize how a store instance labels items should replace the getLabel() function on
+ // their instance of the store, or extend the store and replace the function in
// the extension class.
//
// item:
// The item to return the label for.
//
- // returns:
- // A user-readable string representing the item or undefined if no user-readable label can
+ // returns:
+ // A user-readable string representing the item or undefined if no user-readable label can
// be generated.
throw new Error('Unimplemented API: dojo.data.api.Read.getLabel');
return undefined;
getLabelAttributes: function(/* item */ item){
// summary:
- // Method to inspect the item and return an array of what attributes of the item were used
+ // Method to inspect the item and return an array of what attributes of the item were used
// to generate its label, if any.
//
// description:
- // Method to inspect the item and return an array of what attributes of the item were used
+ // Method to inspect the item and return an array of what attributes of the item were used
// to generate its label, if any. This function is to assist UI developers in knowing what
// attributes can be ignored out of the attributes an item has when displaying it, in cases
- // where the UI is using the label as an overall identifer should they wish to hide
+ // where the UI is using the label as an overall identifer should they wish to hide
// redundant information.
//
// item:
// The item to return the list of label attributes for.
//
- // returns:
- // An array of attribute names that were used to generate the label, or null if public attributes
+ // returns:
+ // An array of attribute names that were used to generate the label, or null if public attributes
// were not used to generate the label.
throw new Error('Unimplemented API: dojo.data.api.Read.getLabelAttributes');
return null;
git.wh0rd.org / tt-rss.git / blobdiff