git.pond.sub.org Git - eow/blob - static/dojo-release-1.1.1/dojo/data/api/Identity.js

   1 if(!dojo._hasResource["dojo.data.api.Identity"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
   2 dojo._hasResource["dojo.data.api.Identity"] = true;
   3 dojo.provide("dojo.data.api.Identity");
   4 dojo.require("dojo.data.api.Read");
   5
   6 dojo.declare("dojo.data.api.Identity", dojo.data.api.Read, {
   7         //      summary:
   8         //              This is an abstract API that data provider implementations conform to.
   9         //              This file defines methods signatures and intentionally leaves all the
  10         //              methods unimplemented.
  11
  12         getFeatures: function(){
  13                 //      summary:
  14                 //              See dojo.data.api.Read.getFeatures()
  15                 return {
  16                          'dojo.data.api.Read': true,
  17                          'dojo.data.api.Identity': true
  18                 };
  19         },
  20
  21         getIdentity: function(/* item */ item){
  22                 //      summary:
  23                 //              Returns a unique identifier for an item.  The return value will be
  24                 //              either a string or something that has a toString() method (such as,
  25                 //              for example, a dojox.uuid.Uuid object).
  26                 //      item:
  27                 //              The item from the store from which to obtain its identifier.
  28                 //      exceptions:
  29                 //              Conforming implementations may throw an exception or return null if
  30                 //              item is not an item.
  31                 //      example:
  32                 //      |       var itemId = store.getIdentity(kermit);
  33                 //      |       assert(kermit === store.findByIdentity(store.getIdentity(kermit)));
  34                 throw new Error('Unimplemented API: dojo.data.api.Identity.getIdentity');
  35                 var itemIdentityString = null;
  36                 return itemIdentityString; // string
  37         },
  38
  39         getIdentityAttributes: function(/* item */ item){
  40                 //      summary:
  41                 //              Returns an array of attribute names that are used to generate the identity.
  42                 //              For most stores, this is a single attribute, but for some complex stores
  43                 //              such as RDB backed stores that use compound (multi-attribute) identifiers
  44                 //              it can be more than one.  If the identity is not composed of attributes
  45                 //              on the item, it will return null.  This function is intended to identify
  46                 //              the attributes that comprise the identity so that so that during a render
  47                 //              of all attributes, the UI can hide the the identity information if it
  48                 //              chooses.
  49                 //      item:
  50                 //              The item from the store from which to obtain the array of public attributes that
  51                 //              compose the identifier, if any.
  52                 //      example:
  53                 //      |       var itemId = store.getIdentity(kermit);
  54                 //      |       var identifiers = store.getIdentityAttributes(itemId);
  55                 //      |       assert(typeof identifiers === "array" || identifiers === null);
  56                 throw new Error('Unimplemented API: dojo.data.api.Identity.getIdentityAttributes');
  57                 return null; // string
  58         },
  59
  60
  61         fetchItemByIdentity: function(/* object */ keywordArgs){
  62                 //      summary:
  63                 //              Given the identity of an item, this method returns the item that has
  64                 //              that identity through the onItem callback.  Conforming implementations
  65                 //              should return null if there is no item with the given identity.
  66                 //              Implementations of fetchItemByIdentity() may sometimes return an item
  67                 //              from a local cache and may sometimes fetch an item from a remote server,
  68                 //
  69                 //      keywordArgs:
  70                 //              An anonymous object that defines the item to locate and callbacks to invoke when the
  71                 //              item has been located and load has completed.  The format of the object is as follows:
  72                 //              {
  73                 //                      identity: string|object,
  74                 //                      onItem: Function,
  75                 //                      onError: Function,
  76                 //                      scope: object
  77                 //              }
  78                 //      The *identity* parameter.
  79                 //              The identity parameter is the identity of the item you wish to locate and load
  80                 //              This attribute is required.  It should be a string or an object that toString()
  81                 //              can be called on.
  82                 //
  83                 //      The *onItem* parameter.
  84                 //              Function(item)
  85                 //              The onItem parameter is the callback to invoke when the item has been loaded.  It takes only one
  86                 //              parameter, the item located, or null if none found.
  87                 //
  88                 //      The *onError* parameter.
  89                 //              Function(error)
  90                 //              The onError parameter is the callback to invoke when the item load encountered an error.  It takes only one
  91                 //              parameter, the error object
  92                 //
  93                 //      The *scope* parameter.
  94                 //              If a scope object is provided, all of the callback functions (onItem,
  95                 //              onError, etc) will be invoked in the context of the scope object.
  96                 //              In the body of the callback function, the value of the "this"
  97                 //              keyword will be the scope object.   If no scope object is provided,
  98                 //              the callback functions will be called in the context of dojo.global.
  99                 //              For example, onItem.call(scope, item, request) vs.
 100                 //              onItem.call(dojo.global, item, request)
 101                 if (!this.isItemLoaded(keywordArgs.item)) {
 102                         throw new Error('Unimplemented API: dojo.data.api.Identity.fetchItemByIdentity');
 103                 }
 104         }
 105 });
 106
 107 }