lib/dojo/data/api/Identity.js

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