lib/dojo/data/api/Identity.js

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