source: Dev/branches/rest-dojo-ui/client/dojo/data/util/simpleFetch.js @ 256

define(["dojo/_base/lang", "dojo/_base/window", "./sorter"], 
  function(lang, winUtil, sorter) {
        // module:
        //              dojo/data/util/simpleFetch
        // summary:
        //              TODOC

var simpleFetch = lang.getObject("dojo.data.util.simpleFetch", true);

simpleFetch.fetch = function(/* Object? */ request){
        //      summary:
        //              The simpleFetch mixin is designed to serve as a set of function(s) that can
        //              be mixed into other datastore implementations to accelerate their development.
        //              The simpleFetch mixin should work well for any datastore that can respond to a _fetchItems()
        //              call by returning an array of all the found items that matched the query.  The simpleFetch mixin
        //              is not designed to work for datastores that respond to a fetch() call by incrementally
        //              loading items, or sequentially loading partial batches of the result
        //              set.  For datastores that mixin simpleFetch, simpleFetch
        //              implements a fetch method that automatically handles eight of the fetch()
        //              arguments -- onBegin, onItem, onComplete, onError, start, count, sort and scope
        //              The class mixing in simpleFetch should not implement fetch(),
        //              but should instead implement a _fetchItems() method.  The _fetchItems()
        //              method takes three arguments, the keywordArgs object that was passed
        //              to fetch(), a callback function to be called when the result array is
        //              available, and an error callback to be called if something goes wrong.
        //              The _fetchItems() method should ignore any keywordArgs parameters for
        //              start, count, onBegin, onItem, onComplete, onError, sort, and scope.
        //              The _fetchItems() method needs to correctly handle any other keywordArgs
        //              parameters, including the query parameter and any optional parameters
        //              (such as includeChildren).  The _fetchItems() method should create an array of
        //              result items and pass it to the fetchHandler along with the original request object
        //              -- or, the _fetchItems() method may, if it wants to, create an new request object
        //              with other specifics about the request that are specific to the datastore and pass
        //              that as the request object to the handler.
        //
        //              For more information on this specific function, see dojo.data.api.Read.fetch()
        request = request || {};
        if(!request.store){
                request.store = this;
        }
        var self = this;

        var _errorHandler = function(errorData, requestObject){
                if(requestObject.onError){
                        var scope = requestObject.scope || winUtil.global;
                        requestObject.onError.call(scope, errorData, requestObject);
                }
        };

        var _fetchHandler = function(items, requestObject){
                var oldAbortFunction = requestObject.abort || null;
                var aborted = false;

                var startIndex = requestObject.start?requestObject.start:0;
                var endIndex = (requestObject.count && (requestObject.count !== Infinity))?(startIndex + requestObject.count):items.length;

                requestObject.abort = function(){
                        aborted = true;
                        if(oldAbortFunction){
                                oldAbortFunction.call(requestObject);
                        }
                };

                var scope = requestObject.scope || winUtil.global;
                if(!requestObject.store){
                        requestObject.store = self;
                }
                if(requestObject.onBegin){
                        requestObject.onBegin.call(scope, items.length, requestObject);
                }
                if(requestObject.sort){
                        items.sort(sorter.createSortFunction(requestObject.sort, self));
                }
                if(requestObject.onItem){
                        for(var i = startIndex; (i < items.length) && (i < endIndex); ++i){
                                var item = items[i];
                                if(!aborted){
                                        requestObject.onItem.call(scope, item, requestObject);
                                }
                        }
                }
                if(requestObject.onComplete && !aborted){
                        var subset = null;
                        if(!requestObject.onItem){
                                subset = items.slice(startIndex, endIndex);
                        }
                        requestObject.onComplete.call(scope, subset, requestObject);
                }
        };
        this._fetchItems(request, _fetchHandler, _errorHandler);
        return request; // Object
};

return simpleFetch;
});