add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / data / proxy / Server.js

/**\r
 * ServerProxy is a superclass of {@link Ext.data.proxy.JsonP JsonPProxy} and {@link Ext.data.proxy.Ajax AjaxProxy}, and\r
 * would not usually be used directly.\r
 * @protected\r
 */\r
Ext.define('Ext.data.proxy.Server', {\r
    extend: 'Ext.data.proxy.Proxy',\r
    alias : 'proxy.server',\r
    alternateClassName: 'Ext.data.ServerProxy',\r
    uses  : ['Ext.data.Request'],\r
    \r
    isRemote: true,\r
\r
    config: {\r
        /**\r
         * @cfg {String} url\r
         * The URL from which to request the data object.\r
         */\r
        url: '',\r
    \r
        /**\r
         * @cfg {String} [pageParam="page"]\r
         * The name of the 'page' parameter to send in a request. Defaults to 'page'. Set this to `''` if you don't\r
         * want to send a page parameter.\r
         */\r
        pageParam: 'page',\r
    \r
        /**\r
         * @cfg {String} [startParam="start"]\r
         * The name of the 'start' parameter to send in a request. Defaults to 'start'. Set this to `''` if you don't\r
         * want to send a start parameter.\r
         */\r
        startParam: 'start',\r
    \r
        /**\r
         * @cfg {String} [limitParam="limit"]\r
         * The name of the 'limit' parameter to send in a request. Defaults to 'limit'. Set this to `''` if you don't\r
         * want to send a limit parameter.\r
         */\r
        limitParam: 'limit',\r
    \r
        /**\r
         * @cfg {String} [groupParam="group"]\r
         * The name of the 'group' parameter to send in a request. Defaults to 'group'. Set this to `''` if you don't\r
         * want to send a group parameter.\r
         */\r
        groupParam: 'group',\r
    \r
        /**\r
         * @cfg {String} [groupDirectionParam="groupDir"]\r
         * The name of the direction parameter to send in a request. **This is only used when simpleGroupMode is set to\r
         * true.**\r
         */\r
        groupDirectionParam: 'groupDir',\r
    \r
        /**\r
         * @cfg {String} [sortParam="sort"]\r
         * The name of the 'sort' parameter to send in a request. Defaults to 'sort'. Set this to `''` if you don't\r
         * want to send a sort parameter.\r
         */\r
        sortParam: 'sort',\r
    \r
        /**\r
         * @cfg {String} [filterParam="filter"]\r
         * The name of the 'filter' parameter to send in a request. Defaults to 'filter'. Set this to `''` if you don't\r
         * want to send a filter parameter.\r
         */\r
        filterParam: 'filter',\r
    \r
        /**\r
         * @cfg {String} [directionParam="dir"]\r
         * The name of the direction parameter to send in a request. **This is only used when simpleSortMode is set to\r
         * true.**\r
         */\r
        directionParam: 'dir',\r
    \r
        /**\r
         * @cfg {String} [idParam="id"]\r
         * The name of the parameter which carries the id of the entity being operated upon.\r
         */\r
        idParam: 'id',\r
    \r
        /**\r
         * @cfg {Boolean} [simpleSortMode=false]\r
         * Enabling simpleSortMode in conjunction with remoteSort will only send one sort property and a direction when a\r
         * remote sort is requested. The {@link #directionParam} and {@link #sortParam} will be sent with the property name\r
         * and either 'ASC' or 'DESC'.\r
         */\r
        simpleSortMode: false,\r
    \r
        /**\r
         * @cfg {Boolean} [simpleGroupMode=false]\r
         * Enabling simpleGroupMode in conjunction with remoteGroup will only send one group property and a direction when a\r
         * remote group is requested. The {@link #groupDirectionParam} and {@link #groupParam} will be sent with the property name and either 'ASC'\r
         * or 'DESC'.\r
         */\r
        simpleGroupMode: false,\r
    \r
        /**\r
         * @cfg {Boolean} [noCache=true]\r
         * Disable caching by adding a unique parameter name to the request. Set to false to allow caching. Defaults to true.\r
         */\r
        noCache : true,\r
    \r
        /**\r
         * @cfg {String} [cacheString="_dc"]\r
         * The name of the cache param added to the url when using noCache. Defaults to "_dc".\r
         */\r
        cacheString: "_dc",\r
    \r
        /**\r
         * @cfg {Number} timeout\r
         * The number of milliseconds to wait for a response. Defaults to 30000 milliseconds (30 seconds).\r
         */\r
        timeout : 30000,\r
    \r
        /**\r
         * @cfg {Object} api\r
         * Specific urls to call on CRUD action methods "create", "read", "update" and "destroy". Defaults to:\r
         *\r
         *     api: {\r
         *         create  : undefined,\r
         *         read    : undefined,\r
         *         update  : undefined,\r
         *         destroy : undefined\r
         *     }\r
         *\r
         * The url is built based upon the action being executed [create|read|update|destroy] using the commensurate\r
         * {@link #api} property, or if undefined default to the configured\r
         * {@link Ext.data.Store}.{@link Ext.data.proxy.Server#url url}.\r
         *\r
         * For example:\r
         *\r
         *     api: {\r
         *         create  : '/controller/new',\r
         *         read    : '/controller/load',\r
         *         update  : '/controller/update',\r
         *         destroy : '/controller/destroy_action'\r
         *     }\r
         *\r
         * If the specific URL for a given CRUD action is undefined, the CRUD action request will be directed to the\r
         * configured {@link Ext.data.proxy.Server#url url}.\r
         */\r
        api: {\r
            create  : undefined,\r
            read    : undefined,\r
            update  : undefined,\r
            destroy : undefined\r
        },\r
\r
        /**\r
         * @cfg {Object} extraParams\r
         * Extra parameters that will be included on every request. Individual requests with params of the same name\r
         * will override these params when they are in conflict.\r
         */\r
        extraParams: {}\r
    },\r
\r
    /**\r
     * @event exception\r
     * Fires when the server returns an exception. This event may also be listened\r
     * to in the event that a request has timed out or has been aborted.\r
     * @param {Ext.data.proxy.Proxy} this\r
     * @param {Ext.data.Request} request The request that was sent\r
     * @param {Ext.data.operation.Operation} operation The operation that triggered the request\r
     */\r
\r
    //in a ServerProxy all four CRUD operations are executed in the same manner, so we delegate to doRequest in each case\r
    create: function() {\r
        return this.doRequest.apply(this, arguments);\r
    },\r
\r
    read: function() {\r
        return this.doRequest.apply(this, arguments);\r
    },\r
\r
    update: function() {\r
        return this.doRequest.apply(this, arguments);\r
    },\r
\r
    erase: function() {\r
        return this.doRequest.apply(this, arguments);\r
    },\r
\r
    /**\r
     * Sets a value in the underlying {@link #extraParams}.\r
     * @param {String} name The key for the new value\r
     * @param {Object} value The value\r
     */\r
    setExtraParam: function(name, value) {\r
        var extraParams = this.getExtraParams();\r
        extraParams[name] = value;\r
        this.fireEvent('extraparamschanged', extraParams);\r
    },\r
\r
    updateExtraParams: function(newExtraParams, oldExtraParams) {\r
        this.fireEvent('extraparamschanged', newExtraParams);\r
    },\r
\r
    /**\r
     * Creates an {@link Ext.data.Request Request} object from {@link Ext.data.operation.Operation Operation}.\r
     *\r
     * This gets called from doRequest methods in subclasses of Server proxy.\r
     * \r
     * @param {Ext.data.operation.Operation} operation The operation to execute\r
     * @return {Ext.data.Request} The request object\r
     */\r
    buildRequest: function(operation) {\r
        var me = this,\r
            initialParams = Ext.apply({}, operation.getParams()),\r
            // Clone params right now so that they can be mutated at any point further down the call stack\r
            params = Ext.applyIf(initialParams, me.getExtraParams() || {}),\r
            request,\r
            operationId,\r
            idParam;\r
\r
        //copy any sorters, filters etc into the params so they can be sent over the wire\r
        Ext.applyIf(params, me.getParams(operation));\r
\r
        // Set up the entity id parameter according to the configured name.\r
        // This defaults to "id". But TreeStore has a "nodeParam" configuration which\r
        // specifies the id parameter name of the node being loaded.\r
        operationId = operation.getId();\r
        idParam = me.getIdParam();\r
        if (operationId !== undefined && params[idParam] === undefined) {\r
            params[idParam] = operationId;\r
        }\r
\r
        request = new Ext.data.Request({\r
            params   : params,\r
            action   : operation.getAction(),\r
            records  : operation.getRecords(),\r
            url      : operation.getUrl(),\r
            operation: operation,\r
\r
            // this is needed by JsonSimlet in order to properly construct responses for\r
            // requests from this proxy\r
            proxy: me\r
        });\r
\r
        request.setUrl(me.buildUrl(request));\r
\r
        /*\r
         * Save the request on the Operation. Operations don't usually care about Request and Response data, but in the\r
         * ServerProxy and any of its subclasses we add both request and response as they may be useful for further processing\r
         */\r
        operation.setRequest(request);\r
\r
        return request;\r
    },\r
\r
    /**\r
     * Processes response, which may involve updating or committing records, each of which\r
     * will inform the owning stores and their interested views. Finally, we may perform\r
     * an additional layout if the data shape has changed. \r
     *\r
     * @protected\r
     */\r
    processResponse: function(success, operation, request, response) {\r
        var me = this,\r
            exception, reader, resultSet;\r
\r
        // Processing a response may involve updating or committing many records\r
        // each of which will inform the owning stores, which will ultimately\r
        // inform interested views which will most likely have to do a layout\r
        // assuming that the data shape has changed.\r
        // Bracketing the processing with this event gives owning stores the ability\r
        // to fire their own beginupdate/endupdate events which can be used by interested\r
        // views to suspend layouts.\r
        me.fireEvent('beginprocessresponse', me, response, operation);\r
\r
        if (success === true) {\r
            reader = me.getReader();\r
\r
            if (response.status === 204) {\r
                resultSet = reader.getNullResultSet();\r
            } else {\r
                resultSet = reader.read(me.extractResponseData(response), {\r
                    // If we're doing an update, we want to construct the models ourselves.\r
                    recordCreator: operation.getRecordCreator()\r
                });\r
            }\r
\r
            operation.process(resultSet, request, response);\r
            exception = !operation.wasSuccessful();\r
        } else {\r
            me.setException(operation, response);\r
            exception = true;\r
        }\r
        \r
        if (exception) {\r
            me.fireEvent('exception', me, response, operation);\r
        }\r
\r
        me.afterRequest(request, success);\r
\r
        // Tell owning store processing has finished.\r
        // It will fire its endupdate event which will cause interested views to \r
        // resume layouts.\r
        me.fireEvent('endprocessresponse', me, response, operation);\r
    },\r
    \r
    /**\r
     * Sets up an exception on the operation\r
     * @private\r
     * @param {Ext.data.operation.Operation} operation The operation\r
     * @param {Object} response The response\r
     */\r
    setException: function(operation, response) {\r
        operation.setException({\r
            status: response.status,\r
            statusText: response.statusText,\r
            response: response\r
        });\r
    },\r
\r
    /**\r
     * @method\r
     * Template method to allow subclasses to specify how to get the response for the reader.\r
     * @template\r
     * @private\r
     * @param {Object} response The server response\r
     * @return {Object} The response data to be used by the reader\r
     */\r
    extractResponseData: Ext.identityFn,\r
\r
    /**\r
     * Encode any values being sent to the server. Can be overridden in subclasses.\r
     * @protected\r
     * @param {Array} value An array of sorters/filters.\r
     * @return {Object} The encoded value\r
     */\r
    applyEncoding: function(value) {\r
        return Ext.encode(value);\r
    },\r
\r
    /**\r
     * Encodes the array of {@link Ext.util.Sorter} objects into a string to be sent in the request url. By default,\r
     * this simply JSON-encodes the sorter data\r
     * @param {Ext.util.Sorter[]} sorters The array of {@link Ext.util.Sorter Sorter} objects\r
     * @param {Boolean} [preventArray=false] Prevents the items from being output as an array.\r
     * @return {String} The encoded sorters\r
     */\r
    encodeSorters: function(sorters, preventArray) {\r
        var out = [],\r
            length = sorters.length, \r
            i;\r
        \r
        for (i = 0; i < length; i++) {\r
            out[i] = sorters[i].serialize();\r
        }\r
\r
        return this.applyEncoding(preventArray ? out[0] : out);\r
    },\r
\r
    /**\r
     * Encodes the array of {@link Ext.util.Filter} objects into a string to be sent in the request url. By default,\r
     * this simply JSON-encodes the filter data\r
     * @param {Ext.util.Filter[]} filters The array of {@link Ext.util.Filter Filter} objects\r
     * @return {String} The encoded filters\r
     */\r
    encodeFilters: function(filters) {\r
        var out = [],\r
            length = filters.length,\r
            i, op;\r
\r
        for (i = 0; i < length; i++) {\r
            out[i] = filters[i].serialize();\r
        }\r
\r
        return this.applyEncoding(out);\r
    },\r
\r
    /**\r
     * @private\r
     * Copy any sorters, filters etc into the params so they can be sent over the wire\r
     */\r
    getParams: function(operation) {\r
        if (!operation.isReadOperation) {\r
            return {};\r
        }\r
\r
        var me = this,\r
            params = {},\r
            grouper = operation.getGrouper(),\r
            sorters = operation.getSorters(),\r
            filters = operation.getFilters(),\r
            page = operation.getPage(),\r
            start = operation.getStart(),\r
            limit = operation.getLimit(),\r
            simpleSortMode = me.getSimpleSortMode(),\r
            simpleGroupMode = me.getSimpleGroupMode(),\r
            pageParam = me.getPageParam(),\r
            startParam = me.getStartParam(),\r
            limitParam = me.getLimitParam(),\r
            groupParam = me.getGroupParam(),\r
            groupDirectionParam = me.getGroupDirectionParam(),\r
            sortParam = me.getSortParam(),\r
            filterParam = me.getFilterParam(),\r
            directionParam = me.getDirectionParam(),\r
            hasGroups, index;\r
\r
        if (pageParam && page) {\r
            params[pageParam] = page;\r
        }\r
\r
        if (startParam && (start || start === 0)) {\r
            params[startParam] = start;\r
        }\r
\r
        if (limitParam && limit) {\r
            params[limitParam] = limit;\r
        }\r
\r
        hasGroups = groupParam && grouper;\r
        if (hasGroups) {\r
            // Grouper is a subclass of sorter, so we can just use the sorter method\r
            if (simpleGroupMode) {\r
                params[groupParam] = grouper.getProperty();\r
                params[groupDirectionParam] = grouper.getDirection();\r
            } else {\r
                params[groupParam] = me.encodeSorters([grouper], true);\r
            }\r
        }\r
\r
        if (sortParam && sorters && sorters.length > 0) {\r
            if (simpleSortMode) {\r
                index = 0;\r
                // Group will be included in sorters, so grab the next one\r
                if (sorters.length > 1 && hasGroups) {\r
                    index = 1;\r
                }\r
                params[sortParam] = sorters[index].getProperty();\r
                params[directionParam] = sorters[index].getDirection();\r
            } else {\r
                params[sortParam] = me.encodeSorters(sorters);\r
            }\r
\r
        }\r
\r
        if (filterParam && filters && filters.length > 0) {\r
            params[filterParam] = me.encodeFilters(filters);\r
        }\r
\r
        return params;\r
    },\r
\r
    /**\r
     * Generates a url based on a given Ext.data.Request object. By default, ServerProxy's buildUrl will add the\r
     * cache-buster param to the end of the url. Subclasses may need to perform additional modifications to the url.\r
     * @param {Ext.data.Request} request The request object\r
     * @return {String} The url\r
     */\r
    buildUrl: function(request) {\r
        var me = this,\r
            url = me.getUrl(request);\r
\r
        //<debug>\r
        if (!url) {\r
            Ext.raise("You are using a ServerProxy but have not supplied it with a url.");\r
        }\r
        //</debug>\r
\r
        if (me.getNoCache()) {\r
            url = Ext.urlAppend(url, Ext.String.format("{0}={1}", me.getCacheString(), Ext.Date.now()));\r
        }\r
\r
        return url;\r
    },\r
\r
    /**\r
     * Get the url for the request taking into account the order of priority,\r
     * - The request\r
     * - The api\r
     * - The url\r
     * @private\r
     * @param {Ext.data.Request} request The request\r
     * @return {String} The url\r
     */\r
    getUrl: function(request) {\r
        var url;\r
        if (request) {\r
            url = request.getUrl() || this.getApi()[request.getAction()];\r
        }\r
        return url ? url : this.callParent();\r
    },\r
\r
    /**\r
     * In ServerProxy subclasses, the {@link #create}, {@link #read}, {@link #update} and {@link #erase} methods all\r
     * pass through to doRequest. Each ServerProxy subclass must implement the doRequest method - see {@link\r
     * Ext.data.proxy.JsonP} and {@link Ext.data.proxy.Ajax} for examples. This method carries the same signature as\r
     * each of the methods that delegate to it.\r
     *\r
     * @param {Ext.data.operation.Operation} operation The Ext.data.operation.Operation object\r
     * @param {Function} callback The callback function to call when the Operation has completed\r
     * @param {Object} scope The scope in which to execute the callback\r
     */\r
    doRequest: function(operation) {\r
        //<debug>\r
        Ext.raise("The doRequest function has not been implemented on your Ext.data.proxy.Server subclass. See src/data/ServerProxy.js for details");\r
        //</debug>\r
    },\r
\r
    /**\r
     * Optional callback function which can be used to clean up after a request has been completed.\r
     * @param {Ext.data.Request} request The Request object\r
     * @param {Boolean} success True if the request was successful\r
     * @protected\r
     * @template\r
     * @method\r
     */\r
    afterRequest: Ext.emptyFn,\r
\r
    destroy: function() {\r
        this.callParent();\r
        \r
        Ext.destroy(this.getReader(), this.getWriter());\r
        \r
        this.reader = this.writer = null;\r
    }\r
});\r