[extjs.git] / extjs / packages / core / src / direct / RemotingProvider.js

/**\r
 * The {@link Ext.direct.RemotingProvider RemotingProvider} exposes access to\r
 * server side methods on the client (a remote procedure call (RPC) type of\r
 * connection where the client can initiate a procedure on the server).\r
 * \r
 * This allows for code to be organized in a fashion that is maintainable,\r
 * while providing a clear path between client and server, something that is\r
 * not always apparent when using URLs.\r
 * \r
 * To accomplish this the server-side needs to describe what classes and methods\r
 * are available on the client-side. This configuration will typically be\r
 * outputted by the server-side Ext Direct stack when the API description is built.\r
 */\r
Ext.define('Ext.direct.RemotingProvider', {\r
    extend: 'Ext.direct.JsonProvider', \r
    alias:  'direct.remotingprovider',\r
    \r
    requires: [\r
        'Ext.util.MixedCollection', \r
        'Ext.util.DelayedTask', \r
        'Ext.direct.Transaction',\r
        'Ext.direct.RemotingMethod',\r
        'Ext.direct.Manager'\r
    ],\r
    \r
    type: 'remoting',\r
    \r
    /**\r
     * @cfg {Object} actions\r
     *\r
     * Object literal defining the server side actions and methods. For example, if\r
     * the Provider is configured with:\r
     *\r
     *      // each property within the 'actions' object represents a server side Class\r
     *      actions: {\r
     *          // array of methods in each server side Class to be stubbed out on client\r
     *          TestAction: [{\r
     *              name: 'doEcho',   // stub method will be TestAction.doEcho\r
     *              len:  1,\r
     *              batched: false    // always send requests immediately for this method\r
     *          }, {\r
     *              name: 'multiply', // name of method\r
     *              len:  2           // The number of parameters that will be used to create an\r
     *                                // array of data to send to the server side function.\r
     *          }, {\r
     *              name: 'doForm',\r
     *              formHandler: true // tells the client that this method handles form calls\r
     *          }],\r
     *          \r
     *          // These methods will be created in nested namespace TestAction.Foo\r
     *          'TestAction.Foo': [{\r
     *              name: 'ordered',  // stub method will be TestAction.Foo.ordered\r
     *              len:  1\r
     *          }, {\r
     *              name: 'noParams', // this method does not accept any parameters\r
     *              len:  0\r
     *          }, {\r
     *              name: 'named',    // stub method will be TestAction.Foo.named\r
     *              params: ['foo', 'bar']    // parameters are passed by name\r
     *          }, {\r
     *              name: 'namedNoStrict',\r
     *              params: [],       // this method accepts parameters by name\r
     *              strict: false     // but does not check if they are required\r
     *                                // and will pass any to the server side\r
     *          }]\r
     *      }\r
     *\r
     * Note that starting with 4.2, dotted Action names will generate nested objects.\r
     * If you wish to reverse to previous behavior, set {@link #cfg-disableNestedActions}\r
     * to `true`.\r
     *\r
     * In the following example a *client side* handler is used to call the\r
     * server side method "multiply" in the server-side "TestAction" Class:\r
     *\r
     *      TestAction.multiply(\r
     *          // pass two arguments to server, so specify len=2\r
     *          2, 4,\r
     *          \r
     *          // callback function after the server is called\r
     *          //  result: the result returned by the server\r
     *          //       e: Ext.direct.RemotingEvent object\r
     *          // success: true or false\r
     *          // options: options to be applied to method call and passed to callback\r
     *          function (result, e, success, options) {\r
     *              var t, action, method;\r
     *              \r
     *              t = e.getTransaction();\r
     *              action = t.action; // server side Class called\r
     *              method = t.method; // server side method called\r
     *              \r
     *              if (e.status) {\r
     *                  var answer = Ext.encode(result); // 8\r
     *              }\r
     *              else {\r
     *                  var msg = e.message; // failure message\r
     *              }\r
     *          },\r
     *          \r
     *          // Scope to call the callback in (optional)\r
     *          window,\r
     *          \r
     *          // Options to apply to this method call. This can include\r
     *          // Ajax.request() options; only `timeout` is supported at this time.\r
     *          // When timeout is set for a method call, it will be executed immediately\r
     *          // without buffering.\r
     *          // The same options object is passed to the callback so it's possible\r
     *          // to "forward" some data when needed.\r
     *          {\r
     *              timeout: 60000, // milliseconds\r
     *              foo: 'bar'\r
     *          }\r
     *      );\r
     *\r
     * In the example above, the server side "multiply" function will be passed two\r
     * arguments (2 and 4). The "multiply" method should return the value 8 which will be\r
     * available as the `result` in the callback example above. \r
     */\r
    \r
    /**\r
     * @cfg {Boolean} [disableNestedActions=false]\r
     * In versions prior to 4.2, using dotted Action names was not really meaningful,\r
     * because it generated flat {@link #cfg-namespace} object with dotted property names.\r
     * For example, take this API declaration:\r
     *\r
     *      {\r
     *          actions: {\r
     *              TestAction: [{\r
     *                  name: 'foo',\r
     *                  len:  1\r
     *              }],\r
     *              'TestAction.Foo' [{\r
     *                  name: 'bar',\r
     *                  len: 1\r
     *              }]\r
     *          },\r
     *          namespace: 'MyApp'\r
     *      }\r
     *\r
     * Before 4.2, that would generate the following API object:\r
     *\r
     *      window.MyApp = {\r
     *          TestAction: {\r
     *              foo: function() { ... }\r
     *          },\r
     *          'TestAction.Foo': {\r
     *              bar: function() { ... }\r
     *          }\r
     *      }\r
     *\r
     * In Ext JS 4.2, we introduced new namespace handling behavior. Now the same API object\r
     * will be like this:\r
     *\r
     *      window.MyApp = {\r
     *          TestAction: {\r
     *              foo: function() { ... },\r
     *\r
     *              Foo: {\r
     *                  bar: function() { ... }\r
     *              }\r
     *          }\r
     *      }\r
     *\r
     * Instead of addressing Action methods array-style `MyApp['TestAction.Foo'].bar()`,\r
     * now it is possible to use object addressing: `MyApp.TestAction.Foo.bar()`.\r
     *\r
     * If you find this behavior undesirable, set this config option to `true`.\r
     */\r
    \r
    /**\r
     * @cfg {String/Object} namespace\r
     *\r
     * Namespace for the Remoting Provider (defaults to `Ext.global`).\r
     * Explicitly specify the namespace Object, or specify a String to have a\r
     * {@link Ext#namespace namespace} created implicitly.\r
     */\r
    \r
    /**\r
     * @cfg {String} url\r
     *\r
     * **Required**. The url to connect to the {@link Ext.direct.Manager} server-side router. \r
     */\r
    \r
    /**\r
     * @cfg {String} [enableUrlEncode=data]\r
     *\r
     * Specify which param will hold the arguments for the method.\r
     */\r
    \r
    /**\r
     * @cfg {Number/Boolean} [enableBuffer=10]\r
     *\r
     * `true` or `false` to enable or disable combining of method\r
     * calls. If a number is specified this is the amount of time in milliseconds\r
     * to wait before sending a batched request.\r
     *\r
     * Calls which are received within the specified timeframe will be\r
     * concatenated together and sent in a single request, optimizing the\r
     * application by reducing the amount of round trips that have to be made\r
     * to the server. To cancel buffering for some particular invocations, pass\r
     * `timeout` parameter in `options` object for that method call.\r
     */\r
    enableBuffer: 10,\r
    \r
    /**\r
     * @cfg {Number} bufferLimit The maximum number of requests to batch together.\r
     * By default, an unlimited number of requests will be batched. This option will\r
     * allow to wait only for a certain number of Direct method calls before\r
     * dispatching a request to the server, even if {@link #enableBuffer} timeout\r
     * has not yet expired.\r
     * \r
     * Note that this option does nothing if {@link #enableBuffer} is set to `false`.\r
     */\r
    bufferLimit: Number.MAX_VALUE,\r
    \r
    /**\r
     * @cfg {Number} [maxRetries=1]\r
     *\r
     * Number of times to re-attempt delivery on failure of a call.\r
     */\r
    maxRetries: 1,\r
    \r
    /**\r
     * @cfg {Number} [timeout]\r
     *\r
     * The timeout to use for each request.\r
     */\r
    \r
    /**\r
     * @event beforecall\r
     * @preventable\r
     *\r
     * Fires immediately before the client-side sends off the RPC call. By returning\r
     * `false` from an event handler you can prevent the call from being made.\r
     *\r
     * @param {Ext.direct.RemotingProvider} provider\r
     * @param {Ext.direct.Transaction} transaction\r
     * @param {Object} meta The meta data\r
     */            \r
\r
    /**\r
     * @event call\r
     *\r
     * Fires immediately after the request to the server-side is sent. This does\r
     * NOT fire after the response has come back from the call.\r
     *\r
     * @param {Ext.direct.RemotingProvider} provider\r
     * @param {Ext.direct.Transaction} transaction\r
     * @param {Object} meta The meta data\r
     */            \r
\r
    /**\r
     * @event beforecallback\r
     * @preventable\r
     *\r
     * Fires before callback function is executed. By returning `false` from an event handler\r
     * you can prevent the callback from executing.\r
     *\r
     * @param {Ext.direct.RemotingProvider} provider The provider instance\r
     * @param {Ext.direct.Event} event Event associated with the callback invocation\r
     * @param {Ext.direct.Transaction} transaction Transaction for which the callback\r
     * is about to be fired\r
     */\r
\r
    constructor: function(config) {\r
        var me = this;\r
\r
        me.callParent(arguments);\r
\r
        me.namespace = (Ext.isString(me.namespace)) ? Ext.ns(me.namespace) : me.namespace || Ext.global;\r
        me.transactions = new Ext.util.MixedCollection();\r
        me.callBuffer = [];\r
    },\r
    \r
    doConnect: function() {\r
        if (!this.apiCreated) {\r
            this.initAPI();\r
            this.apiCreated = true;\r
        }\r
    },\r
    \r
    /**\r
     * Get nested namespace by property.\r
     *\r
     * @private\r
     */\r
    getNamespace: function(root, action) {\r
        var parts, ns, i, len;\r
        \r
        root  = root || Ext.global;\r
        parts = action.toString().split('.');\r
\r
        for (i = 0, len = parts.length; i < len; i++) {\r
            ns   = parts[i];\r
            root = root[ns];\r
\r
            if (typeof root === 'undefined') {\r
                return root;\r
            }\r
        }\r
\r
        return root;\r
    },\r
\r
    /**\r
     * Create nested namespaces. Unlike {@link Ext#ns} this method supports\r
     * nested objects as root of the namespace, not only Ext.global (window).\r
     *\r
     * @private\r
     */\r
    createNamespaces: function(root, action) {\r
        var parts, ns, i, len;\r
        \r
        root  = root || Ext.global;\r
        parts = action.toString().split('.');\r
        \r
        for (i = 0, len = parts.length; i < len; i++) {\r
            ns = parts[i];\r
            \r
            root[ns] = root[ns] || {};\r
            root     = root[ns];\r
        }\r
        \r
        return root;\r
    },\r
    \r
    /**\r
     * Initialize the API\r
     *\r
     * @private\r
     */\r
    initAPI: function() {\r
        var me = this,\r
            actions = me.actions,\r
            namespace = me.namespace,\r
            Manager = Ext.direct.Manager,\r
            action, cls, methods, i, len, method, handler;\r
            \r
        for (action in actions) {\r
            if (actions.hasOwnProperty(action)) {\r
                if (me.disableNestedActions) {\r
                    cls = namespace[action];\r
                    \r
                    if (!cls) {\r
                        cls = namespace[action] = {};\r
                    }\r
                }\r
                else {\r
                    cls = me.getNamespace(namespace, action);\r
\r
                    if (!cls) {\r
                        cls = me.createNamespaces(namespace, action);\r
                    }\r
                }\r
\r
                methods = actions[action];\r
\r
                for (i = 0, len = methods.length; i < len; ++i) {\r
                    method = new Ext.direct.RemotingMethod(methods[i]);\r
                    cls[method.name] = handler = me.createHandler(action, method);\r
                    \r
                    Manager.registerMethod(handler.$name, handler);\r
                }\r
            }\r
        }\r
    },\r
    \r
    /**\r
     * Create a handler function for a direct call.\r
     *\r
     * @param {String} action The action the call is for\r
     * @param {Object} method The details of the method\r
     *\r
     * @return {Function} A JS function that will kick off the call\r
     *\r
     * @private\r
     */\r
    createHandler: function(action, method) {\r
        var me = this,\r
            slice = Array.prototype.slice,\r
            handler;\r
        \r
        if (!method.formHandler) {\r
            handler = function() {\r
                me.configureRequest(action, method, slice.call(arguments, 0));\r
            };\r
        }\r
        else {\r
            handler = function() {\r
                me.configureFormRequest(action, method, slice.call(arguments, 0));\r
            };\r
        }\r
        \r
        handler.name = handler.$name = action + '.' + method.name;\r
        handler.$directFn = true;\r
        \r
        handler.directCfg = handler.$directCfg = {\r
            action: action,\r
            method: method\r
        };\r
\r
        return handler;\r
    },\r
    \r
    /**\r
     * @inheritdoc\r
     */\r
    connect: function() {\r
        var me = this;\r
\r
        //<debug>\r
        if (!me.url) {\r
            Ext.raise('Error initializing RemotingProvider "' + me.id +\r
                            '", no url configured.');\r
        }\r
        //</debug>\r
        \r
        me.callParent();\r
    },\r
\r
    /**\r
     * Run any callbacks related to the transaction.\r
     *\r
     * @param {Ext.direct.Transaction} transaction The transaction\r
     * @param {Ext.direct.Event} event The event\r
     *\r
     * @private\r
     */\r
    runCallback: function(transaction, event) {\r
        var success = !!event.status,\r
            funcName = success ? 'success' : 'failure',\r
            callback, options, result;\r
        \r
        if (transaction && transaction.callback) {\r
            callback = transaction.callback;\r
            options  = transaction.callbackOptions;\r
            result   = typeof event.result !== 'undefined' ? event.result : event.data;\r
\r
            if (Ext.isFunction(callback)) {\r
                callback(result, event, success, options);\r
            }\r
            else {\r
                Ext.callback(callback[funcName], callback.scope, [result, event, success, options]);\r
                Ext.callback(callback.callback,  callback.scope, [result, event, success, options]);\r
            }\r
        }\r
    },\r
    \r
    /**\r
     * React to the ajax request being completed\r
     *\r
     * @private\r
     */\r
    onData: function(options, success, response) {\r
        var me = this,\r
            i, len, events, event, transaction, transactions;\r
            \r
        if (success) {\r
            events = me.createEvents(response);\r
\r
            for (i = 0, len = events.length; i < len; ++i) {\r
                event = events[i];\r
                transaction = me.getTransaction(event);\r
                me.fireEvent('data', me, event);\r
\r
                if (transaction && me.fireEvent('beforecallback', me, event, transaction) !== false) {\r
                    me.runCallback(transaction, event, true);\r
                }\r
                \r
                Ext.direct.Manager.removeTransaction(transaction);\r
            }\r
        }\r
        else {\r
            transactions = [].concat(options.transaction);\r
            \r
            for (i = 0, len = transactions.length; i < len; ++i) {\r
                transaction = me.getTransaction(transactions[i]);\r
\r
                if (transaction && transaction.retryCount < me.maxRetries) {\r
                    transaction.retry();\r
                }\r
                else {\r
                    event = new Ext.direct.ExceptionEvent({\r
                        data: null,\r
                        transaction: transaction,\r
                        code: Ext.direct.Manager.exceptions.TRANSPORT,\r
                        message: 'Unable to connect to the server.',\r
                        xhr: response\r
                    });\r
\r
                    me.fireEvent('data', me, event);\r
\r
                    if (transaction && me.fireEvent('beforecallback', me, event, transaction) !== false) {\r
                        me.runCallback(transaction, event, false);\r
                    }\r
                    \r
                    Ext.direct.Manager.removeTransaction(transaction);\r
                }\r
            }\r
        }\r
    },\r
    \r
    /**\r
     * Get transaction from XHR options\r
     *\r
     * @param {Object} options The options sent to the Ajax request\r
     *\r
     * @return {Ext.direct.Transaction} The transaction, null if not found\r
     *\r
     * @private\r
     */\r
    getTransaction: function(options) {\r
        return options && options.tid ? Ext.direct.Manager.getTransaction(options.tid) : null;\r
    },\r
    \r
    /**\r
     * Gets the Ajax call info for a transaction\r
     *\r
     * @param {Ext.direct.Transaction} transaction The transaction\r
     *\r
     * @return {Object} The call params\r
     *\r
     * @private\r
     */\r
    getPayload: function(transaction) {\r
        var result = {\r
            action: transaction.action,\r
            method: transaction.method,\r
            data: transaction.data,\r
            type: 'rpc',\r
            tid: transaction.id\r
        };\r
        \r
        if (transaction.metadata) {\r
            result.metadata = transaction.metadata;\r
        }\r
        \r
        return result;\r
    },\r
    \r
    /**\r
     * Sends a request to the server\r
     *\r
     * @param {Object/Array} transaction The transaction(s) to send\r
     *\r
     * @private\r
     */\r
    sendRequest: function(transaction) {\r
        var me = this,\r
            request, callData, params,\r
            enableUrlEncode = me.enableUrlEncode,\r
            payload, i, len;\r
\r
        request = {\r
            url: me.url,\r
            callback: me.onData,\r
            scope: me,\r
            transaction: transaction,\r
            timeout: me.timeout\r
        };\r
\r
        // Explicitly specified timeout for Ext Direct call overrides defaults\r
        if (transaction.timeout) {\r
            request.timeout = transaction.timeout;\r
        }\r
\r
        if (Ext.isArray(transaction)) {\r
            callData = [];\r
\r
            for (i = 0, len = transaction.length; i < len; ++i) {\r
                payload = me.getPayload(transaction[i]);\r
                callData.push(payload);\r
            }\r
        }\r
        else {\r
            callData = me.getPayload(transaction);\r
        }\r
\r
        if (enableUrlEncode) {\r
            params = {};\r
            params[Ext.isString(enableUrlEncode) ? enableUrlEncode : 'data'] = Ext.encode(callData);\r
            request.params = params;\r
        }\r
        else {\r
            request.jsonData = callData;\r
        }\r
\r
        Ext.Ajax.request(request);\r
    },\r
    \r
    /**\r
     * Add a new transaction to the queue\r
     *\r
     * @param {Ext.direct.Transaction} transaction The transaction\r
     *\r
     * @private\r
     */\r
    queueTransaction: function(transaction) {\r
        var me = this,\r
            callBuffer = me.callBuffer,\r
            enableBuffer = me.enableBuffer;\r
        \r
        if (transaction.form) {\r
            me.sendFormRequest(transaction);\r
            return;\r
        }\r
\r
        if (enableBuffer === false || transaction.disableBatching ||\r
            typeof transaction.timeout !== 'undefined') {\r
            me.sendRequest(transaction);\r
            return;\r
        }\r
        \r
        callBuffer.push(transaction);\r
\r
        if (enableBuffer && callBuffer.length < me.bufferLimit) {\r
            if (!me.callTask) {\r
                me.callTask = new Ext.util.DelayedTask(me.combineAndSend, me);\r
            }\r
\r
            me.callTask.delay(Ext.isNumber(enableBuffer) ? enableBuffer : 10);\r
        }\r
        else {\r
            me.combineAndSend();\r
        }\r
    },\r
    \r
    /**\r
     * Combine any buffered requests and send them off\r
     *\r
     * @private\r
     */\r
    combineAndSend : function() {\r
        var me = this,\r
            buffer = me.callBuffer,\r
            len = buffer.length;\r
            \r
        if (len > 0) {\r
            me.sendRequest(len === 1 ? buffer[0] : buffer);\r
            me.callBuffer = [];\r
        }\r
    },\r
    \r
    /**\r
     * Configure a transaction for a Direct request\r
     *\r
     * @param {String} action The action being executed\r
     * @param {Object} method The method being executed\r
     * @param {Array} args Method invocation arguments\r
     * @param {Boolean} isForm True for a form submit\r
     *\r
     * @return {Object} Transaction object\r
     *\r
     * @private\r
     */\r
    configureTransaction: function(action, method, args, isForm) {\r
        var data, cb, scope, options, params;\r
        \r
        data = method.getCallData(args);\r
        \r
        cb      = data.callback;\r
        scope   = data.scope;\r
        options = data.options;\r
        \r
        //<debug>\r
        if (cb && !Ext.isFunction(cb)) {\r
            Ext.raise("Callback argument is not a function " +\r
                            "for Ext Direct method " +\r
                            action + "." + method.name);\r
        }\r
        //</debug>\r
        \r
        // Callback might be unspecified for a notification\r
        // that does not expect any return value\r
        cb = cb && scope ? Ext.Function.bind(cb, scope) : cb;\r
        \r
        params = Ext.apply({}, {\r
            provider: this,\r
            args: args,\r
            action: action,\r
            method: method.name,\r
            form: data.form,\r
            data: data.data,\r
            metadata: data.metadata,\r
            callbackOptions: options,\r
            callback: cb,\r
            isForm: isForm,\r
            disableBatching: method.disableBatching\r
        });\r
        \r
        if (options && options.timeout != null) {\r
            params.timeout = options.timeout;\r
        }\r
        \r
        return new Ext.direct.Transaction(params);\r
    },\r
    \r
    /**\r
     * Configure a direct request\r
     *\r
     * @param {String} action The action being executed\r
     * @param {Object} method The method being executed\r
     *\r
     * @private\r
     */\r
    configureRequest: function(action, method, args) {\r
        var me = this,\r
            transaction;\r
        \r
        transaction = me.configureTransaction(action, method, args);\r
\r
        if (me.fireEvent('beforecall', me, transaction, method) !== false) {\r
            Ext.direct.Manager.addTransaction(transaction);\r
            me.queueTransaction(transaction);\r
            me.fireEvent('call', me, transaction, method);\r
        }\r
    },\r
    \r
    /**\r
     * Configure a form submission request\r
     *\r
     * @param {String} action The action being executed\r
     * @param {Object} method The method being executed\r
     * @param {Array} args Method invocation arguments\r
     *\r
     * @private\r
     */\r
    configureFormRequest: function(action, method, args) {\r
        var me = this,\r
            transaction, form, isUpload, postParams;\r
        \r
        transaction = me.configureTransaction(action, method, args, true);\r
        \r
        if (me.fireEvent('beforecall', me, transaction, method) !== false) {\r
            Ext.direct.Manager.addTransaction(transaction);\r
            \r
            form = transaction.form;\r
            \r
            isUpload = String(form.getAttribute("enctype")).toLowerCase() === 'multipart/form-data';\r
            \r
            postParams = {\r
                extTID: transaction.id,\r
                extAction: action,\r
                extMethod: method.name,\r
                extType: 'rpc',\r
                extUpload: String(isUpload)\r
            };\r
            \r
            if (transaction.metadata) {\r
                postParams.extMetadata = Ext.JSON.encode(transaction.metadata);\r
            }\r
            \r
            Ext.apply(transaction, {\r
                form: form,\r
                isUpload: isUpload,\r
                params: postParams\r
            });\r
\r
            me.sendFormRequest(transaction);\r
            me.fireEvent('call', me, transaction, method);\r
        }\r
    },\r
    \r
    /**\r
     * Sends a form request\r
     *\r
     * @param {Ext.direct.Transaction} transaction The transaction to send\r
     *\r
     * @private\r
     */\r
    sendFormRequest: function(transaction) {\r
        var me = this;\r
\r
        Ext.Ajax.request({\r
            url: me.url,\r
            params: transaction.params,\r
            callback: me.onData,\r
            scope: me,\r
            form: transaction.form,\r
            isUpload: transaction.isUpload,\r
            transaction: transaction\r
        });\r
    },\r
    \r
    inheritableStatics: {\r
        /**\r
         * @private\r
         * @static\r
         * @inheritable\r
         */\r
        checkConfig: function(config) {\r
            // RemotingProvider needs service URI,\r
            // type and array of Actions\r
            return config && config.type === 'remoting' &&\r
                   config.url && Ext.isArray(config.actions);\r
        }\r
    }\r
});\r