Upgrade to ExtJS 3.0.0 - Released 07/06/2009
[extjs.git] / src / direct / RemotingProvider.js
diff --git a/src/direct/RemotingProvider.js b/src/direct/RemotingProvider.js
new file mode 100644 (file)
index 0000000..3b0f2a4
--- /dev/null
@@ -0,0 +1,373 @@
+/*!
+ * Ext JS Library 3.0.0
+ * Copyright(c) 2006-2009 Ext JS, LLC
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+/**\r
+ * @class Ext.direct.RemotingProvider\r
+ * @extends Ext.direct.JsonProvider\r
+ * \r
+ * <p>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).</p>\r
+ * \r
+ * <p>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.</p>\r
+ * \r
+ * <p>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.</p>\r
+ */\r
+Ext.direct.RemotingProvider = Ext.extend(Ext.direct.JsonProvider, {       \r
+    /**\r
+     * @cfg {Object} actions\r
+     * Object literal defining the server side actions and methods. For example, if\r
+     * the Provider is configured with:\r
+     * <pre><code>\r
+"actions":{ // each property within the 'actions' object represents a server side Class \r
+    "TestAction":[ // array of methods within each server side Class to be   \r
+    {              // stubbed out on client\r
+        "name":"doEcho", \r
+        "len":1            \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
+                          // Ensure the server sends back a Number, not a String. \r
+    },{\r
+        "name":"doForm",\r
+        "formHandler":true, // direct the client to use specialized form handling method \r
+        "len":1\r
+    }]\r
+}\r
+     * </code></pre>\r
+     * <p>Note that a Store is not required, a server method can be called at any time.\r
+     * In the following example a <b>client side</b> handler is used to call the\r
+     * server side method "multiply" in the server-side "TestAction" Class:</p>\r
+     * <pre><code>\r
+TestAction.multiply(\r
+    2, 4, // pass two arguments to server, so specify len=2\r
+    // callback function after the server is called\r
+    // result: the result returned by the server\r
+    //      e: Ext.Direct.RemotingEvent object\r
+    function(result, e){\r
+        var t = e.getTransaction();\r
+        var action = t.action; // server side Class called\r
+        var method = t.method; // server side method called\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
+     * </code></pre>\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 <tt>result</tt> in the example above. \r
+     */\r
+    \r
+    /**\r
+     * @cfg {String/Object} namespace\r
+     * Namespace for the Remoting Provider (defaults to the browser global scope of <i>window</i>).\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
+     * <b>Required<b>. The url to connect to the {@link Ext.Direct} server-side router. \r
+     */\r
+    \r
+    /**\r
+     * @cfg {String} enableUrlEncode\r
+     * Specify which param will hold the arguments for the method.\r
+     * Defaults to <tt>'data'</tt>.\r
+     */\r
+    \r
+    /**\r
+     * @cfg {Number/Boolean} enableBuffer\r
+     * <p><tt>true</tt> or <tt>false</tt> 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 (defaults to <tt>10</tt>).</p>\r
+     * <br><p>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.</p>\r
+     */\r
+    enableBuffer: 10,\r
+    \r
+    /**\r
+     * @cfg {Number} maxRetries\r
+     * Number of times to re-attempt delivery on failure of a call.\r
+     */\r
+    maxRetries: 1,\r
+\r
+    constructor : function(config){\r
+        Ext.direct.RemotingProvider.superclass.constructor.call(this, config);\r
+        this.addEvents(\r
+            /**\r
+             * @event beforecall\r
+             * Fires immediately before the client-side sends off the RPC call.\r
+             * By returning false from an event handler you can prevent the call from\r
+             * executing.\r
+             * @param {Ext.direct.RemotingProvider} provider\r
+             * @param {Ext.Direct.Transaction} transaction\r
+             */            \r
+            'beforecall',\r
+            /**\r
+             * @event call\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
+             * @param {Ext.direct.RemotingProvider} provider\r
+             * @param {Ext.Direct.Transaction} transaction\r
+             */            \r
+            'call'\r
+        );\r
+        this.namespace = (typeof this.namespace === 'string') ? Ext.ns(this.namespace) : this.namespace || window;\r
+        this.transactions = {};\r
+        this.callBuffer = [];\r
+    },\r
+\r
+    // private\r
+    initAPI : function(){\r
+        var o = this.actions;\r
+        for(var c in o){\r
+            var cls = this.namespace[c] || (this.namespace[c] = {});\r
+            var ms = o[c];\r
+            for(var i = 0, len = ms.length; i < len; i++){\r
+                var m = ms[i];\r
+                cls[m.name] = this.createMethod(c, m);\r
+            }\r
+        }\r
+    },\r
+\r
+    // inherited\r
+    isConnected: function(){\r
+        return !!this.connected;\r
+    },\r
+\r
+    connect: function(){\r
+        if(this.url){\r
+            this.initAPI();\r
+            this.connected = true;\r
+            this.fireEvent('connect', this);\r
+        }else if(!this.url){\r
+            throw 'Error initializing RemotingProvider, no url configured.';\r
+        }\r
+    },\r
+\r
+    disconnect: function(){\r
+        if(this.connected){\r
+            this.connected = false;\r
+            this.fireEvent('disconnect', this);\r
+        }\r
+    },\r
+\r
+    onData: function(opt, success, xhr){\r
+        if(success){\r
+            var events = this.getEvents(xhr);\r
+            for(var i = 0, len = events.length; i < len; i++){\r
+                var e = events[i];\r
+                var t = this.getTransaction(e);\r
+                this.fireEvent('data', this, e);\r
+                if(t){\r
+                    this.doCallback(t, e, true);\r
+                    Ext.Direct.removeTransaction(t);\r
+                }\r
+            }\r
+        }else{\r
+            var ts = [].concat(opt.ts);\r
+            for(var i = 0, len = ts.length; i < len; i++){\r
+                var t = this.getTransaction(ts[i]);\r
+                if(t && t.retryCount < this.maxRetries){\r
+                    t.retry();\r
+                }else{\r
+                    var e = new Ext.Direct.ExceptionEvent({\r
+                        data: e,\r
+                        transaction: t,\r
+                        code: Ext.Direct.exceptions.TRANSPORT,\r
+                        message: 'Unable to connect to the server.',\r
+                        xhr: xhr\r
+                    });\r
+                    this.fireEvent('data', this, e);\r
+                    if(t){\r
+                        this.doCallback(t, e, false);\r
+                        Ext.Direct.removeTransaction(t);\r
+                    }\r
+                }\r
+            }\r
+        }\r
+    },\r
+\r
+    getCallData: function(t){\r
+        return {\r
+            action: t.action,\r
+            method: t.method,\r
+            data: t.data,\r
+            type: 'rpc',\r
+            tid: t.tid\r
+        };\r
+    },\r
+\r
+    doSend : function(data){\r
+        var o = {\r
+            url: this.url,\r
+            callback: this.onData,\r
+            scope: this,\r
+            ts: data\r
+        };\r
+\r
+        // send only needed data\r
+        var callData;\r
+        if(Ext.isArray(data)){\r
+            callData = [];\r
+            for(var i = 0, len = data.length; i < len; i++){\r
+                callData.push(this.getCallData(data[i]));\r
+            }\r
+        }else{\r
+            callData = this.getCallData(data);\r
+        }\r
+\r
+        if(this.enableUrlEncode){\r
+            var params = {};\r
+            params[typeof this.enableUrlEncode == 'string' ? this.enableUrlEncode : 'data'] = Ext.encode(callData);\r
+            o.params = params;\r
+        }else{\r
+            o.jsonData = callData;\r
+        }\r
+        Ext.Ajax.request(o);\r
+    },\r
+\r
+    combineAndSend : function(){\r
+        var len = this.callBuffer.length;\r
+        if(len > 0){\r
+            this.doSend(len == 1 ? this.callBuffer[0] : this.callBuffer);\r
+            this.callBuffer = [];\r
+        }\r
+    },\r
+\r
+    queueTransaction: function(t){\r
+        if(t.form){\r
+            this.processForm(t);\r
+            return;\r
+        }\r
+        this.callBuffer.push(t);\r
+        if(this.enableBuffer){\r
+            if(!this.callTask){\r
+                this.callTask = new Ext.util.DelayedTask(this.combineAndSend, this);\r
+            }\r
+            this.callTask.delay(typeof this.enableBuffer == 'number' ? this.enableBuffer : 10);\r
+        }else{\r
+            this.combineAndSend();\r
+        }\r
+    },\r
+\r
+    doCall : function(c, m, args){\r
+        var data = null, hs = args[m.len], scope = args[m.len+1];\r
+\r
+        if(m.len !== 0){\r
+            data = args.slice(0, m.len);\r
+        }\r
+\r
+        var t = new Ext.Direct.Transaction({\r
+            provider: this,\r
+            args: args,\r
+            action: c,\r
+            method: m.name,\r
+            data: data,\r
+            cb: scope && Ext.isFunction(hs) ? hs.createDelegate(scope) : hs\r
+        });\r
+\r
+        if(this.fireEvent('beforecall', this, t) !== false){\r
+            Ext.Direct.addTransaction(t);\r
+            this.queueTransaction(t);\r
+            this.fireEvent('call', this, t);\r
+        }\r
+    },\r
+\r
+    doForm : function(c, m, form, callback, scope){\r
+        var t = new Ext.Direct.Transaction({\r
+            provider: this,\r
+            action: c,\r
+            method: m.name,\r
+            args:[form, callback, scope],\r
+            cb: scope && Ext.isFunction(callback) ? callback.createDelegate(scope) : callback,\r
+            isForm: true\r
+        });\r
+\r
+        if(this.fireEvent('beforecall', this, t) !== false){\r
+            Ext.Direct.addTransaction(t);\r
+            var isUpload = String(form.getAttribute("enctype")).toLowerCase() == 'multipart/form-data',\r
+                params = {\r
+                    extTID: t.tid,\r
+                    extAction: c,\r
+                    extMethod: m.name,\r
+                    extType: 'rpc',\r
+                    extUpload: String(isUpload)\r
+                };\r
+            \r
+            // change made from typeof callback check to callback.params\r
+            // to support addl param passing in DirectSubmit EAC 6/2\r
+            Ext.apply(t, {\r
+                form: Ext.getDom(form),\r
+                isUpload: isUpload,\r
+                params: callback && Ext.isObject(callback.params) ? Ext.apply(params, callback.params) : params\r
+            });\r
+            this.fireEvent('call', this, t);\r
+            this.processForm(t);\r
+        }\r
+    },\r
+    \r
+    processForm: function(t){\r
+        Ext.Ajax.request({\r
+            url: this.url,\r
+            params: t.params,\r
+            callback: this.onData,\r
+            scope: this,\r
+            form: t.form,\r
+            isUpload: t.isUpload,\r
+            ts: t\r
+        });\r
+    },\r
+\r
+    createMethod : function(c, m){\r
+        var f;\r
+        if(!m.formHandler){\r
+            f = function(){\r
+                this.doCall(c, m, Array.prototype.slice.call(arguments, 0));\r
+            }.createDelegate(this);\r
+        }else{\r
+            f = function(form, callback, scope){\r
+                this.doForm(c, m, form, callback, scope);\r
+            }.createDelegate(this);\r
+        }\r
+        f.directCfg = {\r
+            action: c,\r
+            method: m\r
+        };\r
+        return f;\r
+    },\r
+\r
+    getTransaction: function(opt){\r
+        return opt && opt.tid ? Ext.Direct.getTransaction(opt.tid) : null;\r
+    },\r
+\r
+    doCallback: function(t, e){\r
+        var fn = e.status ? 'success' : 'failure';\r
+        if(t && t.cb){\r
+            var hs = t.cb;\r
+            var result = e.result || e.data;\r
+            if(Ext.isFunction(hs)){\r
+                hs(result, e);\r
+            } else{\r
+                Ext.callback(hs[fn], hs.scope, [result, e]);\r
+                Ext.callback(hs.callback, hs.scope, [result, e]);\r
+            }\r
+        }\r
+    }\r
+});\r
+Ext.Direct.PROVIDERS['remoting'] = Ext.direct.RemotingProvider;
\ No newline at end of file