read.js

对java中如何使用Ajax技术

/*
	Copyright (c) 2004-2006, The Dojo Foundation
	All Rights Reserved.

	Licensed under the Academic Free License version 2.1 or above OR the
	modified BSD license. For more information on Dojo licensing, see:

		http://dojotoolkit.org/community/licensing.shtml
*/

dojo.provide("dojo.data.core.Read");
dojo.require("dojo.data.core.Result");
dojo.require("dojo.lang.declare");
dojo.require("dojo.experimental");

/* summary:
 *   This is an abstract API that data provider implementations conform to.  
 *   This file defines methods signatures and intentionally leaves all the
 *   methods unimplemented.
 */
dojo.experimental("dojo.data.core.Read");
 
dojo.declare("dojo.data.core.Read", null, {
	get: function(/* item */ item, /* attribute || attribute-name-string */ attribute, /* value? */ defaultValue) {
		/* summary:
		 *   Returns a single attribute value.
		 *   Returns defaultValue if *item* does not have a value for *attribute*.
		 *   Returns null if null was explicitly set as the attribute value.
		 *   Returns undefined if the item does not have a value for the given 
		 *   attribute, or if 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" 
		 *   or "the item has that attribute but does not have any attribute values".
		 *   If store.hasAttribute(item, attribute) returns false, then
		 *   store.get(item, attribute) will return undefined.
		 */
		 
		/* exceptions:
		 *   Conforming implementations should throw an exception if *item* is not
		 *   an item, or *attribute* is neither an attribute object or a string.
		 * examples:
		 *   var darthVader = store.get(lukeSkywalker, "father");
		 */
		dojo.unimplemented('dojo.data.core.Read.get');
		var attributeValue = null;
		return attributeValue; // a literal, an item, null, or undefined (never an array)
	},
	
	getValues: function(/* item */ item, /* attribute || attribute-name-string */ attribute) {
		/* summary:
		 *   This getValues() method works just like the get() method, but getValues()
		 *   always returns an array rather than a single attribute value.  The array
		 *   may be empty, may contain a single attribute value, or may contain many
		 *   attribute values.
		 *   If the item does not have a value for the given attribute, then getValues()
		 *   will return an empty array: [].  (So, if store.hasAttribute(item, attribute)
		 *   returns false, then store.getValues(item, attribute) will return [].)
		 */
		 
		/* exceptions:
		 *   Throws an exception if *item* is not an item, or *attribute* is neither an 
		 *   attribute object or a string.
		 * examples:
		 *   var friendsOfLuke = store.get(lukeSkywalker, "friends");
		 */
		dojo.unimplemented('dojo.data.core.Read.getValues');
		var array = null;
		return array; // an array that may contain literals and items
	},
	
	getAttributes: function(/* item */ item) {
		/* summary:
		 *   Returns an array with all the attributes that this item has.  This
		 *   method will always return an array; if the item has no attributes
		 *   at all, getAttributes() will return an empty array: [].
		 */
		 
		/* exceptions:
		 *   Throws an exception if *item* is not an item. 
		 * examples:
		 *   var array = store.getAttributes(kermit);
		 */
		dojo.unimplemented('dojo.data.core.Read.getAttributes');
		var array = null;
		return array; // array
	},
	
	hasAttribute: function(/* item */ item, /* attribute || attribute-name-string */ attribute) {
		/* summary:
		 *   Returns true if the given *item* has a value for the given *attribute*.
		 */
		 
		/* exceptions:
		 *   Throws an exception if *item* is not an item, or *attribute* is neither an 
		 *   attribute object or a string.
		 * examples:
		 *   var trueOrFalse = store.hasAttribute(kermit, "color");
		 */
		dojo.unimplemented('dojo.data.core.Read.hasAttribute');
		return false; // boolean
	},
	
	containsValue: function(/* item */ item, /* attribute || attribute-name-string */ attribute, /* anything */ value) {
		/* summary:
		 *   Returns true if the given *value* is one of the values that getValue()
		 *   would return.
		 */
		 
		/* exceptions:
		 *   Throws an exception if *item* is not an item, or *attribute* is neither an 
		 *   attribute object or a string.
		 * examples:
		 *   var trueOrFalse = store.containsValue(kermit, "color", "green");
		 */
		dojo.unimplemented('dojo.data.core.Read.containsValue');
		return false; // boolean
	},
	
	isItem: function(/* anything */ something) {
		/* summary:
		 *   Returns true if *something* is an item.  Returns false if *something*
		 *   is a literal or is any object other than an item.
		 */
		 
		/* examples:
		 *   var yes = store.isItem(store.newItem());
		 *   var no  = store.isItem("green");
		 */
		dojo.unimplemented('dojo.data.core.Read.isItem');
		return false; // boolean
	},
	
	isItemAvailable: function(/* anything */ something) {
		/* summary:
		 *   Returns false if isItem(something) is false.  Returns false if
		 *   if isItem(something) is true but the the item is not yet available
		 *   in local memory (for example, if the item has not yet been fully
		 *   loaded from the server).
		 */
		 
		/* examples:
		 *   var yes = store.isItemAvailable(store.newItem());
		 *   var no  = store.isItemAvailable("green");
		 */
		dojo.unimplemented('dojo.data.core.Read.isItemAvailable');
		return false; // boolean
	},
	
	find: function(/* object? || dojo.data.core.Result */ keywordArgs) {
		/* summary:
		 *   Given a query, this method executes the query and makes the
		 *   results available as data items.
		 * description:
		 *   A Result object will always be returned, even if the result set
		 *   is empty.  A Result object will always be returned immediately.
		 *   By default the Result object will be fully populated with result
		 *   items as soon as it is created (synchronously).  The caller may 
		 *   request that the find() operation be executed asynchronously, in
		 *   which case the Result object will be returned immediately but 
		 *   will not yet be populated with result items.  
		 *   For more info about the Result API, see dojo.data.core.Result
		 * keywordArgs:
		 *   The keywordArgs parameter may either be an instance of 
		 *   dojo.data.core.Result or may be a simple anonymous object
		 *   that may contain any of the following:
		 *   { query: query-string or query-object,
		 *     sync: Boolean,
		 *     saveResult: Boolean,
		 *     onbegin: Function,
		 *     onnext: Function,
		 *     oncompleted: Function,
		 *     onerror: Function,
		 *     scope: object
		 *     }
		 *   All implementations should accept keywordArgs objects with any of
		 *   the 7 standard properties: query, sync, saveResult, onnext, oncompleted, 
		 *   onerror, and scope.  Some implementations may accept additional 
		 *   properties in the keywordArgs object as valid parameters, such as 
		 *   {maxResults:100} or {includeOutliers:true}.		 
		 * The *query* parameter.
		 *   The query may be optional in some data store implementations.
		 *   The dojo.data.core.Read API does not specify the syntax or semantics
		 *   of the query itself -- each different data store implementation
		 *   may have its own notion of what a query should look like.
		 *   In most implementations the query will probably be a string, but
		 *   in some implementations the query might be a Date, or a number,
		 *   or some complex keyword parameter object.  The dojo.data.core.Read
		 *   API is completely agnostic about what the query actually is.
		 * The *sync* parameter.
		 *   The sync parameter specifies whether the find operation is asynchronous 
		 *   or not, with {sync:false} for asynchronous finds operations and 
		 *   {sync:true} for synchronous find operations.  If no sync parameter
		 *   is specified, the default is {sync:true}.
		 * The *saveResult* parameter.
		 *   If saveResult is true, then the find call will return a Result
		 *   object that includes a property called *items*, and *items* will
		 *   contain an array of the items found by the query.  If no saveResult
		 *   parameter is specified and no onnext Function is set, the default 
		 *   saveResult value will be {saveResult:true}.  If no saveResult
		 *   parameter is specified but an onnext Function is set, the default 
		 *   saveResult value will be {saveResult:false}.  
		 * The *onbegin* parameter.
		 *   If an onbegin callback function is provided, the callback function
		 *   will be called just once, before the first onnext callback is called.
		 *   The onbegin callback function will be passed a single argument:
		 *   the Result object.  The onbegin callback will be called even if 
		 *   query returns zero items.
		 * The *onnext* parameter.
		 *   If an onnext callback function is provided, the callback function
		 *   will be called as each item in the result is received. The callback 
		 *   function will be passed two arguments: the item itself, and the
		 *   Result object.
		 * The *oncompleted* parameter.
		 *   If an oncompleted callback function is provided, the callback function
		 *   will be called just once, after the last onnext callback is called.
		 *   The oncompleted callback function will be passed a single argument:
		 *   the Result object.  The oncompleted callback will be called even if 
		 *   query returns zero items.
		 * The *onerror* parameter.
		 *   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..
		 *   The onerror callback function will be passed two arguments:
		 *   an Error object and the Result object.
		 * The *scope* parameter.
		 *   If a scope object is provided, all of the callback function (onnext, 
		 *   oncompleted, onerror) 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 dj_global.  
		 *   For example, onnext.call(scope, item, result) vs. 
		 *   onnext.call(dj_global, item, result)
		 * returns:
		 *   The find() method will return an instance of dojo.data.core.Result
		 *   (or an object that extends dojo.data.core.Result or conforms to the
		 *   dojo.data.core.Result API).  If the find() method was passed an
		 *   instance of dojo.data.core.Result as an argument, the same instance
		 *   will be returned.  If the find() method was passed a simple 
		 *   keywordArgs object, like {sync:true}, then the properties in the
		 *   keywordArgs object will be copied into the Result object that 
		 *   find() returns.  The Result object will also have additional 
		 *   properties when it is returned.  The result.store property will 
		 *   have a pointer to the datastore object that find() is a method of.
		 *   The result.length will be -1 if the find() operation has not 
		 *   finished or if there was an error; if the find() operation
		 *   finishes successfully, result.length will be the number of items
		 *   that were found.  If the saveResult property was set to true, or
		 *   if no onnext callback was set, the result.item property will 
		 *   contain an array of data items.  The result.resultMetadata property 
		 *   will contain an additional metaData that was returned by the query
		 *   along with the data items.  For example, if the query returned a
		 *   list of 500 houses for sales, the resultMetadata property might
		 *   contain the average asking price of the houses, or info about 
		 *   how long the query took to execute.
		 */
		
		/* exceptions:
		 *   Throws an exception if the query is not valid, or if the query
		 *   is required but was not supplied.
		 * examples:
		 *   var result = store.find({query:"all books"});
		 *   var result = store.find();
		 *   var result = store.find({query:"foo/bar", sync:true});
		 *   var result = store.find({query:"foo/bar", sync:false, onnext:callback});
		 *   var result = store.find({query:{author:"King"}, maxResults:100});
		 */
		dojo.unimplemented('dojo.data.core.Read.find');
		var result = null; // new dojo.data.core.Result().
		return result; // a dojo.data.core.Result object
	},
	
	getIdentity: function(/* item */ item) {
		/* summary:
		 *   Returns a unique identifer for an item.  The return value will be
		 *   either a string or something that has a toString() method (such as,
		 *   for example, a dojo.uuid.Uuid object).
		 * description:
		 * ISSUE - 
		 *   Should we move this method out of dojo.data.core.Read, and put it somewhere
		 *   else, like maybe dojo.data.core.Identity?
		 */
		 
		/* exceptions:
		 *   Conforming implementations may throw an exception or return null if
		 *   item is not an item.
		 * examples:
		 *   var itemId = store.getIdentity(kermit);
		 *   assert(kermit === store.findByIdentity(store.getIdentity(kermit)));
		 */
		dojo.unimplemented('dojo.data.core.Read.getIdentity');
		var itemIdentifyString = null;
		return itemIdentifyString; // string
	},
	
	findByIdentity: function(/* string */ identity) {
		/* summary:
		 *   Given the identity of an item, this method returns the item that has 
		 *   that identity.  Conforming implementations should return null if there 
		 *   is no item with the given identity.  Implementations of findByIdentity() 
		 *   may sometimes return an item from a local cache and may sometimes 
		 *   fetch an item from a remote server, in which case the call to 
		 *   findByIdentity() will block until the findByIdentity() implementation 
		 *   has the item to return.
		 * description:
		 * FIXME - 
		 *   In our meeting on 2006-10-03 we resolved to move the findByIdentity()
		 *   method out of the Read.js API and into the Identity.js API, as soon
		 *   as we have an Identity.js API.
		 */
		 
		/* examples:
		 *   var alaska = store.getByIdentity("AK");
		 *   assert("AK" == store.getIdentity(store.getByIdentity("AK")));
		 */
		dojo.unimplemented('dojo.data.core.Read.getByIdentity');
		var item = null;
		return item; // item
	}
});