]>
Commit | Line | Data |
---|---|---|
1 | define("dojo/data/api/Identity", ["../../_base/declare", "./Read"], function(declare, Read){ | |
2 | ||
3 | // module: | |
4 | // dojo/data/api/Identity | |
5 | ||
6 | return declare("dojo.data.api.Identity", 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(/* dojo/data/api/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 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 | }, | |
36 | ||
37 | getIdentityAttributes: function(/* dojo/data/api/Item */ item){ | |
38 | // summary: | |
39 | // Returns an array of attribute names that are used to generate the identity. | |
40 | // For most stores, this is a single attribute, but for some complex stores | |
41 | // such as RDB backed stores that use compound (multi-attribute) identifiers | |
42 | // it can be more than one. If the identity is not composed of attributes | |
43 | // on the item, it will return null. This function is intended to identify | |
44 | // the attributes that comprise the identity so that so that during a render | |
45 | // of all attributes, the UI can hide the the identity information if it | |
46 | // chooses. | |
47 | // item: | |
48 | // The item from the store from which to obtain the array of public attributes that | |
49 | // compose the identifier, if any. | |
50 | // example: | |
51 | // | var itemId = store.getIdentity(kermit); | |
52 | // | var identifiers = store.getIdentityAttributes(itemId); | |
53 | // | assert(typeof identifiers === "array" || identifiers === null); | |
54 | throw new Error('Unimplemented API: dojo.data.api.Identity.getIdentityAttributes'); | |
55 | }, | |
56 | ||
57 | ||
58 | fetchItemByIdentity: function(/* object */ keywordArgs){ | |
59 | // summary: | |
60 | // Given the identity of an item, this method returns the item that has | |
61 | // that identity through the onItem callback. Conforming implementations | |
62 | // should return null if there is no item with the given identity. | |
63 | // Implementations of fetchItemByIdentity() may sometimes return an item | |
64 | // from a local cache and may sometimes fetch an item from a remote server, | |
65 | // keywordArgs: | |
66 | // An anonymous object that defines the item to locate and callbacks to invoke when the | |
67 | // item has been located and load has completed. The format of the object is as follows: | |
68 | // | { | |
69 | // | identity: string|object, | |
70 | // | onItem: Function, | |
71 | // | onError: Function, | |
72 | // | scope: object | |
73 | // | } | |
74 | // | |
75 | // ####The *identity* parameter | |
76 | // | |
77 | // The identity parameter is the identity of the item you wish to locate and load | |
78 | // This attribute is required. It should be a string or an object that toString() | |
79 | // can be called on. | |
80 | // | |
81 | // ####The *onItem* parameter | |
82 | // | |
83 | // Function(item) | |
84 | // The onItem parameter is the callback to invoke when the item has been loaded. It takes only one | |
85 | // parameter, the item located, or null if none found. | |
86 | // | |
87 | // ####The *onError* parameter | |
88 | // | |
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 | // | |
95 | // If a scope object is provided, all of the callback functions (onItem, | |
96 | // onError, etc) will be invoked in the context of the scope object. | |
97 | // In the body of the callback function, the value of the "this" | |
98 | // keyword will be the scope object. If no scope object is provided, | |
99 | // the callback functions will be called in the context of dojo.global. | |
100 | // For example, onItem.call(scope, item, request) vs. | |
101 | // onItem.call(dojo.global, item, request) | |
102 | ||
103 | if(!this.isItemLoaded(keywordArgs.item)){ | |
104 | throw new Error('Unimplemented API: dojo.data.api.Identity.fetchItemByIdentity'); | |
105 | } | |
106 | } | |
107 | }); | |
108 | ||
109 | }); |