source: Dev/branches/rest-dojo-ui/client/dojo/data/api/Notification.js @ 256

define(["../..", "./Read"], function(dojo) {
        // module:
        //              dojo/data/api/Notification
        // summary:
        //              TODOC


dojo.declare("dojo.data.api.Notification", dojo.data.api.Read, {
        //      summary:
        //              This is an abstract API that data provider implementations conform to.
        //              This file defines functions signatures and intentionally leaves all the
        //              functions unimplemented.
        //
        //      description:
        //              This API defines a set of APIs that all datastores that conform to the
        //              Notifications API must implement.  In general, most stores will implement
        //              these APIs as no-op functions for users who wish to monitor them to be able
        //              to connect to then via dojo.connect().  For non-users of dojo.connect,
        //              they should be able to just replace the function on the store to obtain
        //               notifications.  Both read-only and read-write stores may implement
        //              this feature.  In the case of a read-only store, this feature makes sense if
        //              the store itself does internal polling to a back-end server and periodically updates
        //              its cache of items (deletes, adds, and updates).
        //
        //      example:
        //
        //      |       function onSet(item, attribute, oldValue, newValue) {
        //      |               //Do something with the information...
        //      |       };
        //      |       var store = new some.newStore();
        //      |       dojo.connect(store, "onSet", onSet);

        getFeatures: function(){
                //      summary:
                //              See dojo.data.api.Read.getFeatures()
                return {
                        'dojo.data.api.Read': true,
                        'dojo.data.api.Notification': true
                };
        },

        onSet: function(/* item */ item,
                                        /* attribute-name-string */ attribute,
                                        /* object|array */ oldValue,
                                        /* object|array */ newValue){
                //      summary:
                //              This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc.
                //      description:
                //              This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc.
                //              Its purpose is to provide a hook point for those who wish to monitor actions on items in the store
                //              in a simple manner.  The general expected usage is to dojo.connect() to the store's
                //              implementation and be called after the store function is called.
                //
                //      item:
                //              The item being modified.
                //      attribute:
                //              The attribute being changed represented as a string name.
                //      oldValue:
                //              The old value of the attribute.  In the case of single value calls, such as setValue, unsetAttribute, etc,
                //              this value will be generally be an atomic value of some sort (string, int, etc, object).  In the case of
                //              multi-valued attributes, it will be an array.
                //      newValue:
                //              The new value of the attribute.  In the case of single value calls, such as setValue, this value will be
                //              generally be an atomic value of some sort (string, int, etc, object).  In the case of multi-valued attributes,
                //              it will be an array.  In the case of unsetAttribute, the new value will be 'undefined'.
                //
                //      returns:
                //              Nothing.
                throw new Error('Unimplemented API: dojo.data.api.Notification.onSet');
        },

        onNew: function(/* item */ newItem, /*object?*/ parentInfo){
                //      summary:
                //              This function is called any time a new item is created in the store.
                //              It is called immediately after the store newItem processing has completed.
                //      description:
                //              This function is called any time a new item is created in the store.
                //              It is called immediately after the store newItem processing has completed.
                //
                //      newItem:
                //              The item created.
                //      parentInfo:
                //              An optional javascript object that is passed when the item created was placed in the store
                //              hierarchy as a value f another item's attribute, instead of a root level item.  Note that if this
                //              function is invoked with a value for parentInfo, then onSet is not invoked stating the attribute of
                //              the parent item was modified.  This is to avoid getting two notification  events occurring when a new item
                //              with a parent is created.  The structure passed in is as follows:
                //              {
                //                      item: someItem,                                                 //The parent item
                //                      attribute:      "attribute-name-string",        //The attribute the new item was assigned to.
                //                      oldValue: something     //Whatever was the previous value for the attribute.
                //                                              //If it is a single-value attribute only, then this value will be a single value.
                //                                              //If it was a multi-valued attribute, then this will be an array of all the values minues the new one.
                //                      newValue: something     //The new value of the attribute.  In the case of single value calls, such as setValue, this value will be
                //                                              //generally be an atomic value of some sort (string, int, etc, object).  In the case of multi-valued attributes,
                //                                              //it will be an array.
                //              }
                //
                //      returns:
                //              Nothing.
                throw new Error('Unimplemented API: dojo.data.api.Notification.onNew');
        },

        onDelete: function(/* item */ deletedItem){
                //      summary:
                //              This function is called any time an item is deleted from the store.
                //              It is called immediately after the store deleteItem processing has completed.
                //      description:
                //              This function is called any time an item is deleted from the store.
                //              It is called immediately after the store deleteItem processing has completed.
                //
                //      deletedItem:
                //              The item deleted.
                //
                //      returns:
                //              Nothing.
                throw new Error('Unimplemented API: dojo.data.api.Notification.onDelete');
        }
});

return dojo.data.api.Notification;
});