[extjs.git] / extjs / packages / core / src / data / Connection.js

/**\r
 * The Connection class encapsulates a connection to the page's originating domain, allowing requests to be made either\r
 * to a configured URL, or to a URL specified at request time.\r
 *\r
 * Requests made by this class are asynchronous, and will return immediately. No data from the server will be available\r
 * to the statement immediately following the {@link #request} call. To process returned data, use a success callback\r
 * in the request options object, or an {@link #requestcomplete event listener}.\r
 *\r
 * # File Uploads\r
 *\r
 * File uploads are not performed using normal "Ajax" techniques, that is they are not performed using XMLHttpRequests.\r
 * Instead the form is submitted in the standard manner with the DOM &lt;form&gt; element temporarily modified to have its\r
 * target set to refer to a dynamically generated, hidden &lt;iframe&gt; which is inserted into the document but removed\r
 * after the return data has been gathered.\r
 *\r
 * The server response is parsed by the browser to create the document for the IFRAME. If the server is using JSON to\r
 * send the return object, then the Content-Type header must be set to "text/html" in order to tell the browser to\r
 * insert the text unchanged into the document body.\r
 *\r
 * Characters which are significant to an HTML parser must be sent as HTML entities, so encode `<` as `&lt;`, `&` as\r
 * `&amp;` etc.\r
 *\r
 * The response text is retrieved from the document, and a fake XMLHttpRequest object is created containing a\r
 * responseText property in order to conform to the requirements of event handlers and callbacks.\r
 *\r
 * Be aware that file upload packets are sent with the content type multipart/form and some server technologies\r
 * (notably JEE) may require some custom processing in order to retrieve parameter names and parameter values from the\r
 * packet content.\r
 *\r
 * Also note that it's not possible to check the response code of the hidden iframe, so the success handler will ALWAYS fire.\r
 *\r
 * # Binary Posts\r
 *\r
 * The class supports posting binary data to the server by using native browser capabilities, or a flash polyfill plugin in browsers that do not support native binary posting (e.g. Internet Explorer version 9 or less). A number of limitations exist when the polyfill is used:\r
 *\r
 * - Only asynchronous connections are supported.\r
 * - Only the POST method can be used.\r
 * - The return data can only be binary for now. Set the {@link Ext.data.Connection#binary binary} parameter to <tt>true</tt>.\r
 * - Only the 0, 1 and 4 (complete) readyState values will be reported to listeners.\r
 * - The flash object will be injected at the bottom of the document and should be invisible.\r
 * - Important: See note about packaing the flash plugin with the app in the documenetation of {@link Ext.data.flash.BinaryXhr BinaryXhr}.\r
 *\r
 */\r
Ext.define('Ext.data.Connection', {\r
    mixins: {\r
        observable: 'Ext.mixin.Observable'\r
    },\r
\r
    requires: [\r
        'Ext.data.request.Ajax',\r
        'Ext.data.request.Form',\r
        'Ext.data.flash.BinaryXhr',\r
        'Ext.Deferred'\r
    ],\r
\r
    statics: {\r
        requestId: 0\r
    },\r
\r
    enctypeRe: /multipart\/form-data/i,\r
\r
    config: {\r
        /**\r
         * @cfg {String} url\r
         * The URL for this connection.\r
         */\r
        url: null,\r
\r
        /**\r
         * @cfg {Boolean} async\r
         * `true` if this request should run asynchronously. Setting this to `false` should generally\r
         * be avoided, since it will cause the UI to be blocked, the user won't be able to interact\r
         * with the browser until the request completes.\r
         */\r
        async: true,\r
\r
        /**\r
         * @cfg {String} username\r
         * The username to pass when using {@link #withCredentials}.\r
         */\r
        username: '',\r
\r
        /**\r
         * @cfg {String} password\r
         * The password to pass when using {@link #withCredentials}.\r
         */\r
        password: '',\r
\r
        /**\r
         * @cfg {Boolean} disableCaching\r
         * True to add a unique cache-buster param to GET requests.\r
         */\r
        disableCaching: true,\r
\r
        /**\r
         * @cfg {Boolean} withCredentials\r
         * True to set `withCredentials = true` on the XHR object\r
         */\r
        withCredentials: false,\r
\r
        /**\r
         * @cfg {Boolean} binary\r
         * True if the response should be treated as binary data.  If true, the binary\r
         * data will be accessible as a "responseBytes" property on the response object.\r
         */\r
        binary: false,\r
\r
        /**\r
         * @cfg {Boolean} cors\r
         * True to enable CORS support on the XHR object. Currently the only effect of this option\r
         * is to use the XDomainRequest object instead of XMLHttpRequest if the browser is IE8 or above.\r
         */\r
        cors: false,\r
\r
        isXdr: false,\r
\r
        defaultXdrContentType: 'text/plain',\r
\r
        /**\r
         * @cfg {String} disableCachingParam\r
         * Change the parameter which is sent went disabling caching through a cache buster.\r
         */\r
        disableCachingParam: '_dc',\r
\r
        /**\r
         * @cfg {Number} [timeout=30000] The timeout in milliseconds to be used for \r
         * requests.  \r
         * Defaults to 30000 milliseconds (30 seconds).\r
         * \r
         * When a request fails due to timeout the XMLHttpRequest response object will \r
         * contain:\r
         * \r
         *     timedout: true\r
         */\r
        timeout: 30000,\r
\r
        /**\r
         * @cfg {Object} [extraParams] Any parameters to be appended to the request.\r
         */\r
        extraParams: null,\r
\r
        /**\r
         * @cfg {Boolean} [autoAbort=false]\r
         * Whether this request should abort any pending requests.\r
         */\r
        autoAbort: false,\r
\r
        /**\r
         * @cfg {String} method\r
         * The default HTTP method to be used for requests.\r
         *\r
         * If not set, but {@link #request} params are present, POST will be used;\r
         * otherwise, GET will be used.\r
         */\r
        method: null,\r
\r
        /**\r
         * @cfg {Object} defaultHeaders\r
         * An object containing request headers which are added to each request made by this object.\r
         */\r
        defaultHeaders: null,\r
\r
        /**\r
         * @cfg {String} defaultPostHeader\r
         * The default header to be sent out with any post request.\r
         */\r
        defaultPostHeader : 'application/x-www-form-urlencoded; charset=UTF-8',\r
\r
        /**\r
         * @cfg {Boolean} useDefaultXhrHeader\r
         * `true` to send the {@link #defaultXhrHeader} along with any request.\r
         */\r
        useDefaultXhrHeader : true,\r
\r
        /**\r
         * @cfg {String}\r
         * The header to send with Ajax requests. Also see {@link #useDefaultXhrHeader}.\r
         */\r
        defaultXhrHeader : 'XMLHttpRequest'\r
    },\r
\r
    /**\r
     * @event beforerequest\r
     * @preventable\r
     * Fires before a network request is made to retrieve a data object.\r
     * @param {Ext.data.Connection} conn This Connection object.\r
     * @param {Object} options The options config object passed to the {@link #request} method.\r
     */\r
    \r
    /**\r
     * @event requestcomplete\r
     * Fires if the request was successfully completed.\r
     * @param {Ext.data.Connection} conn This Connection object.\r
     * @param {Object} response The XHR object containing the response data.\r
     * See [The XMLHttpRequest Object](http://www.w3.org/TR/XMLHttpRequest/) for details.\r
     * @param {Object} options The options config object passed to the {@link #request} method.\r
     */\r
    \r
    /**\r
     * @event requestexception\r
     * Fires if an error HTTP status was returned from the server. This event may also\r
     * be listened to in the event that a request has timed out or has been aborted.\r
     * See [HTTP Status Code Definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)\r
     * for details of HTTP status codes.\r
     * @param {Ext.data.Connection} conn This Connection object.\r
     * @param {Object} response The XHR object containing the response data.\r
     * See [The XMLHttpRequest Object](http://www.w3.org/TR/XMLHttpRequest/) for details.\r
     * @param {Object} options The options config object passed to the {@link #request} method.\r
     */\r
     \r
    constructor: function(config) {\r
        // Will call initConfig\r
        this.mixins.observable.constructor.call(this, config);\r
        \r
        this.requests = {};\r
    },\r
\r
    /**\r
     * Sends an HTTP (Ajax) request to a remote server.\r
     *\r
     * **Important:** Ajax server requests are asynchronous, and this call will\r
     * return before the response has been received.\r
     *\r
     * Instead, process any returned data using a promise:\r
     *\r
     *      Ext.Ajax.request({\r
     *          url: 'ajax_demo/sample.json'\r
     *      }).then(function(response, opts) {\r
     *          var obj = Ext.decode(response.responseText);\r
     *          console.dir(obj);\r
     *      },\r
     *      function(response, opts) {\r
     *          console.log('server-side failure with status code ' + response.status);\r
     *      });\r
     *\r
     * Or in callback functions:\r
     *\r
     *      Ext.Ajax.request({\r
     *          url: 'ajax_demo/sample.json',\r
     *\r
     *          success: function(response, opts) {\r
     *              var obj = Ext.decode(response.responseText);\r
     *              console.dir(obj);\r
     *          },\r
     *\r
     *          failure: function(response, opts) {\r
     *              console.log('server-side failure with status code ' + response.status);\r
     *          }\r
     *      });\r
     *\r
     * To execute a callback function in the correct scope, use the `scope` option.\r
     *\r
     * @param {Object} options An object which may contain the following properties:\r
     *\r
     * (The options object may also contain any other property which might be needed to perform\r
     * postprocessing in a callback because it is passed to callback functions.)\r
     *\r
     * @param {String/Function} options.url The URL to which to send the request, or a function\r
     * to call which returns a URL string. The scope of the function is specified by the `scope` option.\r
     * Defaults to the configured `url`.\r
     *\r
     * @param {Boolean} options.async `true` if this request should run asynchronously.\r
     * Setting this to `false` should generally be avoided, since it will cause the UI to be\r
     * blocked, the user won't be able to interact with the browser until the request completes.\r
     * Defaults to `true`.\r
     *\r
     * @param {Object/String/Function} options.params An object containing properties which are\r
     * used as parameters to the request, a url encoded string or a function to call to get either. The scope\r
     * of the function is specified by the `scope` option.\r
     *\r
     * @param {String} options.method The HTTP method to use\r
     * for the request. Defaults to the configured method, or if no method was configured,\r
     * "GET" if no parameters are being sent, and "POST" if parameters are being sent.  Note that\r
     * the method name is case-sensitive and should be all caps.\r
     *\r
     * @param {Function} options.callback The function to be called upon receipt of the HTTP response.\r
     * The callback is called regardless of success or failure and is passed the following parameters:\r
     * @param {Object} options.callback.options The parameter to the request call.\r
     * @param {Boolean} options.callback.success True if the request succeeded.\r
     * @param {Object} options.callback.response The XMLHttpRequest object containing the response data.\r
     * See [www.w3.org/TR/XMLHttpRequest/](http://www.w3.org/TR/XMLHttpRequest/) for details about\r
     * accessing elements of the response.\r
     *\r
     * @param {Function} options.success The function to be called upon success of the request.\r
     * The callback is passed the following parameters:\r
     * @param {Object} options.success.response The XMLHttpRequest object containing the response data.\r
     * @param {Object} options.success.options The parameter to the request call.\r
     *\r
     * @param {Function} options.failure The function to be called upon failure of the request.\r
     * The callback is passed the following parameters:\r
     * @param {Object} options.failure.response The XMLHttpRequest object containing the response data.\r
     * @param {Object} options.failure.options The parameter to the request call.\r
     *\r
     * @param {Object} options.scope The scope in which to execute the callbacks: The "this" object for\r
     * the callback function. If the `url`, or `params` options were specified as functions from which to\r
     * draw values, then this also serves as the scope for those function calls. Defaults to the browser\r
     * window.\r
     *\r
     * @param {Number} options.timeout The timeout in milliseconds to be used for this \r
     * request.  \r
     * Defaults to 30000 milliseconds (30 seconds).\r
     * \r
     * When a request fails due to timeout the XMLHttpRequest response object will \r
     * contain:\r
     * \r
     *     timedout: true\r
     *\r
     * @param {Ext.Element/HTMLElement/String} options.form The `<form>` Element or the id of the `<form>`\r
     * to pull parameters from.\r
     *\r
     * @param {Boolean} options.isUpload **Only meaningful when used with the `form` option.**\r
     *\r
     * True if the form object is a file upload (will be set automatically if the form was configured\r
     * with **`enctype`** `"multipart/form-data"`).\r
     *\r
     * File uploads are not performed using normal "Ajax" techniques, that is they are **not**\r
     * performed using XMLHttpRequests. Instead the form is submitted in the standard manner with the\r
     * DOM `<form>` element temporarily modified to have its [target][] set to refer to a dynamically\r
     * generated, hidden `<iframe>` which is inserted into the document but removed after the return data\r
     * has been gathered.\r
     *\r
     * The server response is parsed by the browser to create the document for the IFRAME. If the\r
     * server is using JSON to send the return object, then the [Content-Type][] header must be set to\r
     * "text/html" in order to tell the browser to insert the text unchanged into the document body.\r
     *\r
     * The response text is retrieved from the document, and a fake XMLHttpRequest object is created\r
     * containing a `responseText` property in order to conform to the requirements of event handlers\r
     * and callbacks.\r
     *\r
     * Be aware that file upload packets are sent with the content type [multipart/form][] and some server\r
     * technologies (notably JEE) may require some custom processing in order to retrieve parameter names\r
     * and parameter values from the packet content.\r
     *\r
     * [target]: http://www.w3.org/TR/REC-html40/present/frames.html#adef-target\r
     * [Content-Type]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17\r
     * [multipart/form]: http://www.faqs.org/rfcs/rfc2388.html\r
     *\r
     * @param {Object} options.headers Request headers to set for the request.\r
     * The XHR will attempt to set an appropriate Content-Type based on the params/data passed\r
     * to the request. To prevent this, setting the Content-Type header to `null` or `undefined`\r
     * will not attempt to set any Content-Type and it will be left to the browser.\r
     *\r
     * @param {Object} options.xmlData XML document to use for the post. Note: This will be used instead\r
     * of params for the post data. Any params will be appended to the URL.\r
     *\r
     * @param {Object/String} options.jsonData JSON data to use as the post. Note: This will be used\r
     * instead of params for the post data. Any params will be appended to the URL.\r
     *\r
     * @param {String} options.rawData A raw string to use as the post. Note: This will be used\r
     * instead of params for the post data. Any params will be appended to the URL.\r
     *\r
     * @param {Array} options.binaryData An array of bytes to submit in binary form. Any params will be appended to the URL. If binaryData is present, you must set {@link Ext.data.Connection#binary binary} to <tt>true</tt> and options.method to <tt>POST</tt>.\r
     *\r
     * @param {Boolean} options.disableCaching True to add a unique cache-buster param to GET requests.\r
     *\r
     * @param {Boolean} options.withCredentials True to add the withCredentials property to the XHR object\r
     *\r
     * @param {String} options.username The username to pass when using `withCredentials`.\r
     *\r
     * @param {String} options.password The password to pass when using `withCredentials`.\r
     *\r
     * @param {Boolean} options.binary True if the response should be treated as binary data.  If true, the binary\r
     * data will be accessible as a "responseBytes" property on the response object.\r
     *\r
     * @return {Ext.data.request.Base} The request object. This may be used to abort the\r
     * request.\r
     */\r
    request: function(options) {\r
        options = options || {};\r
        \r
        var me = this,\r
            requestOptions, request;\r
        \r
        if (me.fireEvent('beforerequest', me, options) !== false) {\r
            requestOptions = me.setOptions(options, options.scope || Ext.global);\r
            \r
            request = me.createRequest(options, requestOptions);\r
            \r
            return request.start(requestOptions.data);\r
        }\r
\r
        Ext.callback(options.callback, options.scope, [options, undefined, undefined]);\r
\r
        return Ext.Deferred.rejected([options, undefined, undefined]);\r
    },\r
\r
    createRequest: function(options, requestOptions) {\r
        var me = this,\r
            type = options.type || requestOptions.type,\r
            request;\r
        \r
        // If request type is not specified we have to deduce it\r
        if (!type) {\r
            type = me.isFormUpload(options) ? 'form' : 'ajax';\r
        }\r
        \r
        // if autoabort is set, cancel the current transactions\r
        if (options.autoAbort || me.getAutoAbort()) {\r
            me.abort();\r
        }\r
        \r
        // It is possible for the original options object to be mutated if somebody\r
        // had overridden Connection.setOptions method; it is also possible that such\r
        // override would do a sensible thing and mutate outgoing requestOptions instead.\r
        // So we have to pass *both* to the Request constructor, along with the set\r
        // of defaults potentially set on the Connection instance.\r
        // If it looks ridiculous, that's because it is; things we have to do for\r
        // backward compatibility...\r
        request = Ext.Factory.request({\r
            type: type,\r
            owner: me,\r
            options: options,\r
            requestOptions: requestOptions,\r
            ownerConfig: me.getConfig()\r
        });\r
        \r
        me.requests[request.id] = request;\r
        me.latestId = request.id;\r
        \r
        return request;\r
    },\r
\r
    /**\r
     * Detects whether the form is intended to be used for an upload.\r
     * @private\r
     */\r
    isFormUpload: function(options) {\r
        var form = this.getForm(options);\r
        \r
        if (form) {\r
            return options.isUpload || this.enctypeRe.test(form.getAttribute('enctype'));\r
        }\r
        \r
        return false;\r
    },\r
\r
    /**\r
     * Gets the form object from options.\r
     * @private\r
     * @param {Object} options The request options\r
     * @return {HTMLElement} The form, null if not passed\r
     */\r
    getForm: function(options) {\r
        return Ext.getDom(options.form);\r
    },\r
\r
    /**\r
     * Sets various options such as the url, params for the request\r
     * @param {Object} options The initial options\r
     * @param {Object} scope The scope to execute in\r
     * @return {Object} The params for the request\r
     */\r
    setOptions: function(options, scope) {\r
        var me = this,\r
            params = options.params || {},\r
            extraParams = me.getExtraParams(),\r
            urlParams = options.urlParams,\r
            url = options.url || me.getUrl(),\r
            cors = options.cors,\r
            jsonData = options.jsonData,\r
            method,\r
            disableCache,\r
            data;\r
\r
        if (cors !== undefined) {\r
            me.setCors(cors);\r
        }\r
\r
        // allow params to be a method that returns the params object\r
        if (Ext.isFunction(params)) {\r
            params = params.call(scope, options);\r
        }\r
\r
        // allow url to be a method that returns the actual url\r
        if (Ext.isFunction(url)) {\r
            url = url.call(scope, options);\r
        }\r
\r
        url = this.setupUrl(options, url);\r
\r
        //<debug>\r
        if (!url) {\r
            Ext.raise({\r
                options: options,\r
                msg: 'No URL specified'\r
            });\r
        }\r
        //</debug>\r
\r
        // check for xml or json data, and make sure json data is encoded\r
        data = options.rawData || options.binaryData || options.xmlData || jsonData || null;\r
        if (jsonData && !Ext.isPrimitive(jsonData)) {\r
            data = Ext.encode(data);\r
        }\r
        // Check for binary data. Transform if needed\r
        if (options.binaryData) {\r
            //<debug>\r
            if (!Ext.isArray(options.binaryData)) {\r
                Ext.log.warn("Binary submission data must be an array of byte values! Instead got " + typeof(options.binaryData));\r
            }\r
            //</debug>\r
            if (me.nativeBinaryPostSupport()) {\r
                data = (new Uint8Array(options.binaryData));\r
                if ((Ext.isChrome && Ext.chromeVersion < 22) || Ext.isSafari || Ext.isGecko) {\r
                    data = data.buffer; //  send the underlying buffer, not the view, since that's not supported on versions of chrome older than 22\r
                }\r
            }\r
        }\r
\r
        // make sure params are a url encoded string and include any extraParams if specified\r
        if (Ext.isObject(params)) {\r
            params = Ext.Object.toQueryString(params);\r
        }\r
\r
        if (Ext.isObject(extraParams)) {\r
            extraParams = Ext.Object.toQueryString(extraParams);\r
        }\r
\r
        params = params + ((extraParams) ? ((params) ? '&' : '') + extraParams : '');\r
\r
        urlParams = Ext.isObject(urlParams) ? Ext.Object.toQueryString(urlParams) : urlParams;\r
\r
        params = this.setupParams(options, params);\r
\r
        // decide the proper method for this request\r
        method = (options.method || me.getMethod() || ((params || data) ? 'POST' : 'GET')).toUpperCase();\r
        this.setupMethod(options, method);\r
\r
        disableCache = options.disableCaching !== false ? (options.disableCaching || me.getDisableCaching()) : false;\r
        // if the method is get append date to prevent caching\r
        if (method === 'GET' && disableCache) {\r
            url = Ext.urlAppend(url, (options.disableCachingParam || me.getDisableCachingParam()) + '=' + (new Date().getTime()));\r
        }\r
\r
        // if the method is get or there is json/xml data append the params to the url\r
        if ((method == 'GET' || data) && params) {\r
            url = Ext.urlAppend(url, params);\r
            params = null;\r
        }\r
\r
        // allow params to be forced into the url\r
        if (urlParams) {\r
            url = Ext.urlAppend(url, urlParams);\r
        }\r
\r
        return {\r
            url: url,\r
            method: method,\r
            data: data || params || null\r
        };\r
    },\r
\r
    /**\r
     * Template method for overriding url\r
     * @private\r
     * @param {Object} options\r
     * @param {String} url\r
     * @return {String} The modified url\r
     */\r
    setupUrl: function(options, url) {\r
        var form = this.getForm(options);\r
        \r
        if (form) {\r
            url = url || form.action;\r
        }\r
        \r
        return url;\r
    },\r
\r
    /**\r
     * Template method for overriding params\r
     * @private\r
     * @param {Object} options\r
     * @param {String} params\r
     * @return {String} The modified params\r
     */\r
    setupParams: function(options, params) {\r
        var form = this.getForm(options),\r
            serializedForm;\r
        \r
        if (form && !this.isFormUpload(options)) {\r
            serializedForm = Ext.Element.serializeForm(form);\r
            params = params ? (params + '&' + serializedForm) : serializedForm;\r
        }\r
        \r
        return params;\r
    },\r
\r
    /**\r
     * Template method for overriding method\r
     * @private\r
     * @param {Object} options\r
     * @param {String} method\r
     * @return {String} The modified method\r
     */\r
    setupMethod: function(options, method) {\r
        if (this.isFormUpload(options)) {\r
            return 'POST';\r
        }\r
        \r
        return method;\r
    },\r
\r
    /**\r
     * Determines whether this object has a request outstanding.\r
     *\r
     * @param {Object} [request] Defaults to the last transaction\r
     *\r
     * @return {Boolean} True if there is an outstanding request.\r
     */\r
    isLoading: function(request) {\r
        if (!request) {\r
            request = this.getLatest();\r
        }\r
        \r
        return request ? request.isLoading() : false;\r
    },\r
\r
    /**\r
     * Aborts an active request.\r
     * @param {Ext.ajax.Request} [request] Defaults to the last request\r
     */\r
    abort: function(request) {\r
        if (!request) {\r
            request = this.getLatest();\r
        }\r
\r
        if (request && request.isLoading()) {\r
            request.abort();\r
        }\r
    },\r
\r
    /**\r
     * Aborts all active requests\r
     */\r
    abortAll: function() {\r
        var requests = this.requests,\r
            id;\r
\r
        for (id in requests) {\r
            this.abort(requests[id]);\r
        }\r
    },\r
\r
    /**\r
     * Gets the most recent request\r
     * @return {Object} The request. Null if there is no recent request\r
     * @private\r
     */\r
    getLatest: function() {\r
        var id = this.latestId,\r
            request;\r
\r
        if (id) {\r
            request = this.requests[id];\r
        }\r
        \r
        return request || null;\r
    },\r
\r
    /**\r
     * Clears the timeout on the request\r
     * @param {Object} request The request\r
     * @private\r
     */\r
    clearTimeout: function(request) {\r
        if (!request) {\r
            request = this.getLatest();\r
        }\r
        \r
        if (request) {\r
            request.clearTimer();\r
        }\r
    },\r
    \r
    onRequestComplete: function(request) {\r
        delete this.requests[request.id];\r
    },\r
    \r
    /**\r
     * @return {Boolean} `true` if the browser can natively post binary data.\r
     * @private\r
     */\r
    nativeBinaryPostSupport: function() {\r
        return Ext.isChrome ||\r
            (Ext.isSafari && Ext.isDefined(window.Uint8Array)) ||\r
            (Ext.isGecko && Ext.isDefined(window.Uint8Array));\r
    }\r
});\r