Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / RemotingProvider.html
1 <html>\r
2 <head>\r
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
4   <title>The source code</title>\r
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
7 </head>\r
8 <body  onload="prettyPrint();">\r
9     <pre class="prettyprint lang-js"><div id="cls-Ext.direct.RemotingProvider"></div>/**\r
10  * @class Ext.direct.RemotingProvider\r
11  * @extends Ext.direct.JsonProvider\r
12  * \r
13  * <p>The {@link Ext.direct.RemotingProvider RemotingProvider} exposes access to\r
14  * server side methods on the client (a remote procedure call (RPC) type of\r
15  * connection where the client can initiate a procedure on the server).</p>\r
16  * \r
17  * <p>This allows for code to be organized in a fashion that is maintainable,\r
18  * while providing a clear path between client and server, something that is\r
19  * not always apparent when using URLs.</p>\r
20  * \r
21  * <p>To accomplish this the server-side needs to describe what classes and methods\r
22  * are available on the client-side. This configuration will typically be\r
23  * outputted by the server-side Ext.Direct stack when the API description is built.</p>\r
24  */\r
25 Ext.direct.RemotingProvider = Ext.extend(Ext.direct.JsonProvider, {       \r
26     <div id="cfg-Ext.direct.RemotingProvider-actions"></div>/**\r
27      * @cfg {Object} actions\r
28      * Object literal defining the server side actions and methods. For example, if\r
29      * the Provider is configured with:\r
30      * <pre><code>\r
31 "actions":{ // each property within the 'actions' object represents a server side Class \r
32     "TestAction":[ // array of methods within each server side Class to be   \r
33     {              // stubbed out on client\r
34         "name":"doEcho", \r
35         "len":1            \r
36     },{\r
37         "name":"multiply",// name of method\r
38         "len":2           // The number of parameters that will be used to create an\r
39                           // array of data to send to the server side function.\r
40                           // Ensure the server sends back a Number, not a String. \r
41     },{\r
42         "name":"doForm",\r
43         "formHandler":true, // direct the client to use specialized form handling method \r
44         "len":1\r
45     }]\r
46 }\r
47      * </code></pre>\r
48      * <p>Note that a Store is not required, a server method can be called at any time.\r
49      * In the following example a <b>client side</b> handler is used to call the\r
50      * server side method "multiply" in the server-side "TestAction" Class:</p>\r
51      * <pre><code>\r
52 TestAction.multiply(\r
53     2, 4, // pass two arguments to server, so specify len=2\r
54     // callback function after the server is called\r
55     // result: the result returned by the server\r
56     //      e: Ext.Direct.RemotingEvent object\r
57     function(result, e){\r
58         var t = e.getTransaction();\r
59         var action = t.action; // server side Class called\r
60         var method = t.method; // server side method called\r
61         if(e.status){\r
62             var answer = Ext.encode(result); // 8\r
63     \r
64         }else{\r
65             var msg = e.message; // failure message\r
66         }\r
67     }\r
68 );\r
69      * </code></pre>\r
70      * In the example above, the server side "multiply" function will be passed two\r
71      * arguments (2 and 4).  The "multiply" method should return the value 8 which will be\r
72      * available as the <tt>result</tt> in the example above. \r
73      */\r
74     \r
75     <div id="cfg-Ext.direct.RemotingProvider-namespace"></div>/**\r
76      * @cfg {String/Object} namespace\r
77      * Namespace for the Remoting Provider (defaults to the browser global scope of <i>window</i>).\r
78      * Explicitly specify the namespace Object, or specify a String to have a\r
79      * {@link Ext#namespace namespace created} implicitly.\r
80      */\r
81     \r
82     <div id="cfg-Ext.direct.RemotingProvider-url"></div>/**\r
83      * @cfg {String} url\r
84      * <b>Required<b>. The url to connect to the {@link Ext.Direct} server-side router. \r
85      */\r
86     \r
87     <div id="cfg-Ext.direct.RemotingProvider-enableUrlEncode"></div>/**\r
88      * @cfg {String} enableUrlEncode\r
89      * Specify which param will hold the arguments for the method.\r
90      * Defaults to <tt>'data'</tt>.\r
91      */\r
92     \r
93     <div id="cfg-Ext.direct.RemotingProvider-enableBuffer"></div>/**\r
94      * @cfg {Number/Boolean} enableBuffer\r
95      * <p><tt>true</tt> or <tt>false</tt> to enable or disable combining of method\r
96      * calls. If a number is specified this is the amount of time in milliseconds\r
97      * to wait before sending a batched request (defaults to <tt>10</tt>).</p>\r
98      * <br><p>Calls which are received within the specified timeframe will be\r
99      * concatenated together and sent in a single request, optimizing the\r
100      * application by reducing the amount of round trips that have to be made\r
101      * to the server.</p>\r
102      */\r
103     enableBuffer: 10,\r
104     \r
105     <div id="cfg-Ext.direct.RemotingProvider-maxRetries"></div>/**\r
106      * @cfg {Number} maxRetries\r
107      * Number of times to re-attempt delivery on failure of a call. Defaults to <tt>1</tt>.\r
108      */\r
109     maxRetries: 1,\r
110     \r
111     <div id="cfg-Ext.direct.RemotingProvider-timeout"></div>/**\r
112      * @cfg {Number} timeout\r
113      * The timeout to use for each request. Defaults to <tt>undefined</tt>.\r
114      */\r
115     timeout: undefined,\r
116 \r
117     constructor : function(config){\r
118         Ext.direct.RemotingProvider.superclass.constructor.call(this, config);\r
119         this.addEvents(\r
120             <div id="event-Ext.direct.RemotingProvider-beforecall"></div>/**\r
121              * @event beforecall\r
122              * Fires immediately before the client-side sends off the RPC call.\r
123              * By returning false from an event handler you can prevent the call from\r
124              * executing.\r
125              * @param {Ext.direct.RemotingProvider} provider\r
126              * @param {Ext.Direct.Transaction} transaction\r
127              */            \r
128             'beforecall',            \r
129             <div id="event-Ext.direct.RemotingProvider-call"></div>/**\r
130              * @event call\r
131              * Fires immediately after the request to the server-side is sent. This does\r
132              * NOT fire after the response has come back from the call.\r
133              * @param {Ext.direct.RemotingProvider} provider\r
134              * @param {Ext.Direct.Transaction} transaction\r
135              */            \r
136             'call'\r
137         );\r
138         this.namespace = (Ext.isString(this.namespace)) ? Ext.ns(this.namespace) : this.namespace || window;\r
139         this.transactions = {};\r
140         this.callBuffer = [];\r
141     },\r
142 \r
143     // private\r
144     initAPI : function(){\r
145         var o = this.actions;\r
146         for(var c in o){\r
147             var cls = this.namespace[c] || (this.namespace[c] = {}),\r
148                 ms = o[c];\r
149             for(var i = 0, len = ms.length; i < len; i++){\r
150                 var m = ms[i];\r
151                 cls[m.name] = this.createMethod(c, m);\r
152             }\r
153         }\r
154     },\r
155 \r
156     // inherited\r
157     isConnected: function(){\r
158         return !!this.connected;\r
159     },\r
160 \r
161     connect: function(){\r
162         if(this.url){\r
163             this.initAPI();\r
164             this.connected = true;\r
165             this.fireEvent('connect', this);\r
166         }else if(!this.url){\r
167             throw 'Error initializing RemotingProvider, no url configured.';\r
168         }\r
169     },\r
170 \r
171     disconnect: function(){\r
172         if(this.connected){\r
173             this.connected = false;\r
174             this.fireEvent('disconnect', this);\r
175         }\r
176     },\r
177 \r
178     onData: function(opt, success, xhr){\r
179         if(success){\r
180             var events = this.getEvents(xhr);\r
181             for(var i = 0, len = events.length; i < len; i++){\r
182                 var e = events[i],\r
183                     t = this.getTransaction(e);\r
184                 this.fireEvent('data', this, e);\r
185                 if(t){\r
186                     this.doCallback(t, e, true);\r
187                     Ext.Direct.removeTransaction(t);\r
188                 }\r
189             }\r
190         }else{\r
191             var ts = [].concat(opt.ts);\r
192             for(var i = 0, len = ts.length; i < len; i++){\r
193                 var t = this.getTransaction(ts[i]);\r
194                 if(t && t.retryCount < this.maxRetries){\r
195                     t.retry();\r
196                 }else{\r
197                     var e = new Ext.Direct.ExceptionEvent({\r
198                         data: e,\r
199                         transaction: t,\r
200                         code: Ext.Direct.exceptions.TRANSPORT,\r
201                         message: 'Unable to connect to the server.',\r
202                         xhr: xhr\r
203                     });\r
204                     this.fireEvent('data', this, e);\r
205                     if(t){\r
206                         this.doCallback(t, e, false);\r
207                         Ext.Direct.removeTransaction(t);\r
208                     }\r
209                 }\r
210             }\r
211         }\r
212     },\r
213 \r
214     getCallData: function(t){\r
215         return {\r
216             action: t.action,\r
217             method: t.method,\r
218             data: t.data,\r
219             type: 'rpc',\r
220             tid: t.tid\r
221         };\r
222     },\r
223 \r
224     doSend : function(data){\r
225         var o = {\r
226             url: this.url,\r
227             callback: this.onData,\r
228             scope: this,\r
229             ts: data,\r
230             timeout: this.timeout\r
231         }, callData;\r
232 \r
233         if(Ext.isArray(data)){\r
234             callData = [];\r
235             for(var i = 0, len = data.length; i < len; i++){\r
236                 callData.push(this.getCallData(data[i]));\r
237             }\r
238         }else{\r
239             callData = this.getCallData(data);\r
240         }\r
241 \r
242         if(this.enableUrlEncode){\r
243             var params = {};\r
244             params[Ext.isString(this.enableUrlEncode) ? this.enableUrlEncode : 'data'] = Ext.encode(callData);\r
245             o.params = params;\r
246         }else{\r
247             o.jsonData = callData;\r
248         }\r
249         Ext.Ajax.request(o);\r
250     },\r
251 \r
252     combineAndSend : function(){\r
253         var len = this.callBuffer.length;\r
254         if(len > 0){\r
255             this.doSend(len == 1 ? this.callBuffer[0] : this.callBuffer);\r
256             this.callBuffer = [];\r
257         }\r
258     },\r
259 \r
260     queueTransaction: function(t){\r
261         if(t.form){\r
262             this.processForm(t);\r
263             return;\r
264         }\r
265         this.callBuffer.push(t);\r
266         if(this.enableBuffer){\r
267             if(!this.callTask){\r
268                 this.callTask = new Ext.util.DelayedTask(this.combineAndSend, this);\r
269             }\r
270             this.callTask.delay(Ext.isNumber(this.enableBuffer) ? this.enableBuffer : 10);\r
271         }else{\r
272             this.combineAndSend();\r
273         }\r
274     },\r
275 \r
276     doCall : function(c, m, args){\r
277         var data = null, hs = args[m.len], scope = args[m.len+1];\r
278 \r
279         if(m.len !== 0){\r
280             data = args.slice(0, m.len);\r
281         }\r
282 \r
283         var t = new Ext.Direct.Transaction({\r
284             provider: this,\r
285             args: args,\r
286             action: c,\r
287             method: m.name,\r
288             data: data,\r
289             cb: scope && Ext.isFunction(hs) ? hs.createDelegate(scope) : hs\r
290         });\r
291 \r
292         if(this.fireEvent('beforecall', this, t) !== false){\r
293             Ext.Direct.addTransaction(t);\r
294             this.queueTransaction(t);\r
295             this.fireEvent('call', this, t);\r
296         }\r
297     },\r
298 \r
299     doForm : function(c, m, form, callback, scope){\r
300         var t = new Ext.Direct.Transaction({\r
301             provider: this,\r
302             action: c,\r
303             method: m.name,\r
304             args:[form, callback, scope],\r
305             cb: scope && Ext.isFunction(callback) ? callback.createDelegate(scope) : callback,\r
306             isForm: true\r
307         });\r
308 \r
309         if(this.fireEvent('beforecall', this, t) !== false){\r
310             Ext.Direct.addTransaction(t);\r
311             var isUpload = String(form.getAttribute("enctype")).toLowerCase() == 'multipart/form-data',\r
312                 params = {\r
313                     extTID: t.tid,\r
314                     extAction: c,\r
315                     extMethod: m.name,\r
316                     extType: 'rpc',\r
317                     extUpload: String(isUpload)\r
318                 };\r
319             \r
320             // change made from typeof callback check to callback.params\r
321             // to support addl param passing in DirectSubmit EAC 6/2\r
322             Ext.apply(t, {\r
323                 form: Ext.getDom(form),\r
324                 isUpload: isUpload,\r
325                 params: callback && Ext.isObject(callback.params) ? Ext.apply(params, callback.params) : params\r
326             });\r
327             this.fireEvent('call', this, t);\r
328             this.processForm(t);\r
329         }\r
330     },\r
331     \r
332     processForm: function(t){\r
333         Ext.Ajax.request({\r
334             url: this.url,\r
335             params: t.params,\r
336             callback: this.onData,\r
337             scope: this,\r
338             form: t.form,\r
339             isUpload: t.isUpload,\r
340             ts: t\r
341         });\r
342     },\r
343 \r
344     createMethod : function(c, m){\r
345         var f;\r
346         if(!m.formHandler){\r
347             f = function(){\r
348                 this.doCall(c, m, Array.prototype.slice.call(arguments, 0));\r
349             }.createDelegate(this);\r
350         }else{\r
351             f = function(form, callback, scope){\r
352                 this.doForm(c, m, form, callback, scope);\r
353             }.createDelegate(this);\r
354         }\r
355         f.directCfg = {\r
356             action: c,\r
357             method: m\r
358         };\r
359         return f;\r
360     },\r
361 \r
362     getTransaction: function(opt){\r
363         return opt && opt.tid ? Ext.Direct.getTransaction(opt.tid) : null;\r
364     },\r
365 \r
366     doCallback: function(t, e){\r
367         var fn = e.status ? 'success' : 'failure';\r
368         if(t && t.cb){\r
369             var hs = t.cb,\r
370                 result = Ext.isDefined(e.result) ? e.result : e.data;\r
371             if(Ext.isFunction(hs)){\r
372                 hs(result, e);\r
373             } else{\r
374                 Ext.callback(hs[fn], hs.scope, [result, e]);\r
375                 Ext.callback(hs.callback, hs.scope, [result, e]);\r
376             }\r
377         }\r
378     }\r
379 });\r
380 Ext.Direct.PROVIDERS['remoting'] = Ext.direct.RemotingProvider;</pre>    \r
381 </body>\r
382 </html>