source: Dev/trunk/src/client/dojox/data/FileStore.js @ 532

define(["dojo/_base/declare", "dojo/_base/lang", "dojo/_base/kernel", "dojo/_base/json", "dojo/_base/xhr"],
  function(declare, lang, kernel, jsonUtil, xhr) {

return declare("dojox.data.FileStore", null, {
        constructor: function(/*Object*/args){
                // summary:
                //              A simple store that provides a datastore interface to a filesystem.
                // description:
                //              A simple store that provides a datastore interface to a filesystem.  It takes a few parameters
                //              for initialization:
                //
                //              - url:  The URL of the service which provides the file store serverside implementation.
                //              - label:        The attribute of the file to use as the human-readable text.  Default is 'name'.
                //
                //              The purpose of this store is to represent a file as a datastore item.  The
                //              datastore item by default has the following attributes that can be examined on it.
                //
                //              - directory:    Boolean indicating if the file item represents a directory.
                //              - name: The filename with no path informatiom.
                //              - path: The file complete file path including name, relative to the location the
                //                      file service scans from
                //              - size: The size of the file, in bytes.
                //              - parentDir:    The parent directory path.
                //              - children:     Any child files contained by a directory file item.
                //
                //              Note that the store's server call pattern is RESTlike.
                //
                //              The store also supports the passing of configurable options to the back end service, such as
                //              expanding all child files (no lazy load), displaying hidden files, displaying only directories, and so on.
                //              These are defined through a comma-separated list in declarative, or through setting the options array in programmatic.
                //              example:        options="expand,dirsOnly,showHiddenFiles"
                if(args && args.label){
                        this.label = args.label;
                }
                if(args && args.url){
                        this.url = args.url;
                }
                if(args && args.options){
                        if(lang.isArray(args.options)){
                                this.options = args.options;
                        }else{
                                if(lang.isString(args.options)){
                                        this.options = args.options.split(",");
                                }
                        }
                }
                if(args && args.pathAsQueryParam){
                        this.pathAsQueryParam = true;
                }
                if(args && "urlPreventCache" in args){
                        this.urlPreventCache = args.urlPreventCache?true:false;
                }
        },

        // url: [public] string
        //              The URL to the file path service.
        url: "",
        
        // _storeRef: [private] string
        //              Internal variable used to denote an item came from this store instance.
        _storeRef: "_S",

        // label: [public] string
        //              Default attribute to use to represent the item as a user-readable
        //              string.  Public, so users can change it.
        label: "name",

        // _identifier: [private] string
        //              Default attribute to use to represent the item's identifier.
        //              Path should always be unique in the store instance.
        _identifier: "path",

        // _attributes: [private] string
        //              Internal variable of attributes all file items should have.
        _attributes: ["children", "directory", "name", "path", "modified", "size", "parentDir"],
        
        // pathSeparator: [public] string
        //              The path separator to use when chaining requests for children
        //              Can be overriden by the server on initial load
        pathSeparator: "/",

        // options: [public] array
        //              Array of options to always send when doing requests.
        //              Back end service controls this, like 'dirsOnly', 'showHiddenFiles', 'expandChildren', etc.
        options: [],

        // failOk: [public] boolean
        //              Flag to pass on to xhr functions to check if we are OK to fail the call silently
        failOk: false,

        // urlPreventCache: [public] string
        //              Flag to dennote if preventCache should be passed to xhrGet.
        urlPreventCache: true,

        _assertIsItem: function(/* item */ item){
                // summary:
                //              This function tests whether the item passed in is indeed an item in the store.
                // item:
                //              The item to test for being contained by the store.
                if(!this.isItem(item)){
                        throw new Error("dojox.data.FileStore: a function was passed an item argument that was not an item");
                }
        },

        _assertIsAttribute: function(/* attribute-name-string */ attribute){
                // summary:
                //              This function tests whether the item passed in is indeed a valid 'attribute' like type for the store.
                // attribute:
                //              The attribute to test for being contained by the store.
                if(typeof attribute !== "string"){
                        throw new Error("dojox.data.FileStore: a function was passed an attribute argument that was not an attribute name string");
                }
        },

        pathAsQueryParam: false, //Function to switch between REST style URL lookups and passing the path to specific items as a query param: 'path'.

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

        getValue: function(item, attribute, defaultValue){
                // summary:
                //              See dojo/data/api/Read.getValue()
                var values = this.getValues(item, attribute);
                if(values && values.length > 0){
                        return values[0];
                }
                return defaultValue;
        },

        getAttributes: function(item){
                // summary:
                //              See dojo/data/api/Read.getAttributes()
                return this._attributes;
        },

        hasAttribute: function(item, attribute){
                // summary:
                //              See dojo/data/api/Read.hasAttribute()
                this._assertIsItem(item);
                this._assertIsAttribute(attribute);
                return (attribute in item);
        },
        
        getIdentity: function(/* item */ item){
                // summary:
                //              See dojo/data/api/Identity.getIdentity()
                return this.getValue(item, this._identifier);
        },
        
        getIdentityAttributes: function(item){
                // summary:
                //              See dojo/data/api/Read.getLabelAttributes()
                return [this._identifier];
        },


        isItemLoaded: function(item){
                // summary:
                //              See dojo/data/api/Read.isItemLoaded()
                var loaded = this.isItem(item);
                if(loaded && typeof item._loaded == "boolean" && !item._loaded){
                        loaded = false;
                }
                return loaded;
        },

        loadItem: function(keywordArgs){
                // summary:
                //              See dojo/data/api/Read.loadItem()
                var item = keywordArgs.item;
                var self = this;
                var scope = keywordArgs.scope || kernel.global;

                var content = {};

                if(this.options.length > 0){
                        content.options = jsonUtil.toJson(this.options);
                }

                if(this.pathAsQueryParam){
                        content.path = item.parentPath + this.pathSeparator + item.name;
                }
                var xhrData = {
                        url: this.pathAsQueryParam? this.url : this.url + "/" + item.parentPath + "/" + item.name,
                        handleAs: "json-comment-optional",
                        content: content,
                        preventCache: this.urlPreventCache,
                        failOk: this.failOk
                };

                var deferred = xhr.get(xhrData);
                deferred.addErrback(function(error){
                                if(keywordArgs.onError){
                                        keywordArgs.onError.call(scope, error);
                                }
                });
                
                deferred.addCallback(function(data){
                        delete item.parentPath;
                        delete item._loaded;
                        lang.mixin(item, data);
                        self._processItem(item);
                        if(keywordArgs.onItem){
                                keywordArgs.onItem.call(scope, item);
                        }
                });
        },

        getLabel: function(item){
                // summary:
                //              See dojo/data/api/Read.getLabel()
                return this.getValue(item,this.label);
        },
        
        getLabelAttributes: function(item){
                // summary:
                //              See dojo/data/api/Read.getLabelAttributes()
                return [this.label];
        },
        
        containsValue: function(item, attribute, value){
                // summary:
                //              See dojo/data/api/Read.containsValue()
                var values = this.getValues(item,attribute);
                for(var i = 0; i < values.length; i++){
                        if(values[i] == value){
                                return true;
                        }
                }
                return false;
        },

        getValues: function(item, attribute){
                // summary:
                //              See dojo/data/api/Read.getValue()
                this._assertIsItem(item);
                this._assertIsAttribute(attribute);
                
                var value = item[attribute];
                if(typeof value !== "undefined" && !lang.isArray(value)){
                        value = [value];
                }else if(typeof value === "undefined"){
                        value = [];
                }
                return value;
        },

        isItem: function(item){
                // summary:
                //              See dojo/data/api/Read.isItem()
                if(item && item[this._storeRef] === this){
                        return true;
                }
                return false;
        },
        
        close: function(request){
                // summary:
                //              See dojo/data/api/Read.close()
        },

        fetch: function(request){
                // summary:
                //              Fetch  items that match to a query
                // request:
                //              A request object

                request = request || {};
                if(!request.store){
                        request.store = this;
                }
                var self = this;
                var scope = request.scope || kernel.global;

                //Generate what will be sent over.
                var reqParams = {};
                if(request.query){
                        reqParams.query = jsonUtil.toJson(request.query);
                }

                if(request.sort){
                        reqParams.sort = jsonUtil.toJson(request.sort);
                }

                if(request.queryOptions){
                        reqParams.queryOptions = jsonUtil.toJson(request.queryOptions);
                }

                if(typeof request.start == "number"){
                        reqParams.start = "" + request.start;
                }
                if(typeof request.count == "number"){
                        reqParams.count = "" + request.count;
                }

                if(this.options.length > 0){
                        reqParams.options = jsonUtil.toJson(this.options);
                }

                var getArgs = {
                        url: this.url,
                        preventCache: this.urlPreventCache,
                        failOk: this.failOk,
                        handleAs: "json-comment-optional",
                        content: reqParams
                };


                var deferred = xhr.get(getArgs);

                deferred.addCallback(function(data){self._processResult(data, request);});
                deferred.addErrback(function(error){
                        if(request.onError){
                                request.onError.call(scope, error, request);
                        }
                });
        },

        fetchItemByIdentity: function(keywordArgs){
                // summary:
                //              See dojo/data/api/Read.loadItem()
                var path = keywordArgs.identity;
                var self = this;
                var scope = keywordArgs.scope || kernel.global;

                var content = {};

                if(this.options.length > 0){
                        content.options = jsonUtil.toJson(this.options);
                }

                if(this.pathAsQueryParam){
                        content.path = path;
                }
                var xhrData = {
                        url: this.pathAsQueryParam? this.url : this.url + "/" + path,
                        handleAs: "json-comment-optional",
                        content: content,
                        preventCache: this.urlPreventCache,
                        failOk: this.failOk
                };

                var deferred = xhr.get(xhrData);
                deferred.addErrback(function(error){
                                if(keywordArgs.onError){
                                        keywordArgs.onError.call(scope, error);
                                }
                });
                
                deferred.addCallback(function(data){
                        var item = self._processItem(data);
                        if(keywordArgs.onItem){
                                keywordArgs.onItem.call(scope, item);
                        }
                });
        },

        _processResult: function(data, request){
                var scope = request.scope || kernel.global;
                try{
                        //If the data contains a path separator, set ours
                        if(data.pathSeparator){
                                this.pathSeparator = data.pathSeparator;
                        }
                        //Invoke the onBegin handler, if any, to return the
                        //size of the dataset as indicated by the service.
                        if(request.onBegin){
                                request.onBegin.call(scope, data.total, request);
                        }
                        //Now process all the returned items thro
                        var items = this._processItemArray(data.items);
                        if(request.onItem){
                                var i;
                                for(i = 0; i < items.length; i++){
                                        request.onItem.call(scope, items[i], request);
                                }
                                items = null;
                        }
                        if(request.onComplete){
                                request.onComplete.call(scope, items, request);
                        }
                }catch (e){
                        if(request.onError){
                                request.onError.call(scope, e, request);
                        }else{
                                console.log(e);
                        }
                }
        },
        
        _processItemArray: function(itemArray){
                // summary:
                //              Internal function for processing an array of items for return.
                var i;
                for(i = 0; i < itemArray.length; i++){
                        this._processItem(itemArray[i]);
                }
                return itemArray;
        },
        
        _processItem: function(item){
                // summary:
                //              Internal function for processing an item returned from the store.
                //              It sets up the store ref as well as sets up the attributes necessary
                //              to invoke a lazy load on a child, if there are any.
                if(!item){return null;}
                item[this._storeRef] = this;
                if(item.children && item.directory){
                        if(lang.isArray(item.children)){
                                var children = item.children;
                                var i;
                                for(i = 0; i < children.length; i++ ){
                                        var name = children[i];
                                        if(lang.isObject(name)){
                                                children[i] = this._processItem(name);
                                        }else{
                                                children[i] = {name: name, _loaded: false, parentPath: item.path};
                                                children[i][this._storeRef] = this;
                                        }
                                }
                        }else{
                                delete item.children;
                        }
                }
                return item;
        }
});
});