rpcmanager.js

javascript 很酷的类库

/*
 * Isomorphic SmartClient
 * Version 6.5 (2008-04-30)
 * Copyright(c) 1998-2007 Isomorphic Software, Inc. All rights reserved.
 * "SmartClient" is a trademark of Isomorphic Software, Inc.
 *
 * [e-mail]
 *
 * http://smartclient.com/license
 */

 



//>	@class RPCManager
// 
// RPCManager is a static singleton class that manages transparent client/server RPC (remote
// procedure call).  This class provides a generic, low-level client/server communication
// integration point.  You can use it to send arbitrary data to a URL of your choosing on the
// server and optionally be called back with server-returned data when the server replies.  
// You can process the RPC request in a JSP, Servlet or Filter on the server.
// <P>
// SmartClient's powerful +link{DataBoundComponent,DataBoundComponents} automatically issue
// RPCs as necessary, based on the 
// +link{group:dataSourceOperations,DataSource protocol}.  To integrate DataBoundComponents
// with your server, +link{group:clientServerIntegration,start here}.
// <P>
// <u>Simple example (client code):</u>
// <P><code>
// var data = { here: "is some data", to: ["send to the server"]};<br>
// RPCManager.sendRequest({ data: data, callback: "myCallback(data)", actionURL: "/rpcHandler.jsp"});<br>
// function myCallback(data) { alert("response from the server: " + data); }
// </code><br><br>
// <u>Simple example (server code: /rpcHandler.jsp):</u>
// <br><br><code>
// RPCManager rpc = new RPCManager(request, response, out);<br>
// Object data = rpc.getData();<br>
// System.out.println("client sent: " + data.toString());<br>
// rpc.send("here's a response");<br>
// </code>
// <P>
// Note that, while the example above uses the SmartClient Java Server, the RPCManager is also
// capable of issuing RPCs that do not require a SmartClient server.  See
// +link{group:clientDataIntegration,Client-Side Data Integration} for details.
// <P>
// <u><b>Queuing</b></u>
// <br>
// Because of browser limitations on the total number of simultaneous HTTP connections to a given
// server, batching multiple RPC requests into a single HTTP request is highly advisable whenever
// possible.  The RPCManager provides a queuing mechanism that allows this.
// <br><br>
// <u>Queuing example (client code):</u>
// <br><br><code>
// RPCManager.startQueue();<br>
// RPCManager.send("a string of data", "myCallback(data)", {actionURL: "/rpcHandler.jsp"});<br>
// RPCManager.sendRequest({ data: ["some", "more data", 2], callback: "myCallback(data)", actionURL: "/rpcHandler.jsp"});<br>
// RPCManager.sendRequest({ data: "different callback", callback: "myCallback2(data)", actionURL: "/rpcHandler.jsp"});<br>
// RPCManager.sendQueue()<br>
// function myCallback(data) { alert("response from the server: " + data); }<br>
// function myCallback2(data) { alert("response from the server (other callback): " + data); }
// </code><br><br>
// <u>Queuing example (server code: /rpcHandler.jsp):</u>
// <br><br><code>
// RPCManager rpc = new RPCManager(request, response, out);<br>
// for(Iterator i = rpc.getRequests().iterator(); i.hasNext();) {<br>
// &nbsp;&nbsp;&nbsp;&nbsp;RPCRequest rpcRequest = (RPCRequest)i.next();<br>
// &nbsp;&nbsp;&nbsp;&nbsp;Object data = rpcRequest.getData();<br>
// &nbsp;&nbsp;&nbsp;&nbsp;System.out.println("client sent:" + data.toString());<br>
// &nbsp;&nbsp;&nbsp;&nbsp;//send back the data sent to us by the client<br>
// &nbsp;&nbsp;&nbsp;&nbsp;rpc.send(rpcRequest, new RPCResponse(data));<br>
// }<br>
// </code>
// <br><br>
// <u><b>Error Handling</b></u>
// <br>
// The +link{RPCResponse} object has an integer status field that the RPCManager inspects when
// the response is received from the server. If the value of this field is less than zero, the
// request is considered to have failed.  Otherwise it is considered to have succeeded.  This
// value is settable via the setStatus() method call on the RPCResponse server-side object.
// <br><br>
// If the status field shows a failure, the RPCManager will, by default, show a dialog with the
// contents of the +link{rpcRequest.data} field (which is assumed to contain a 
// meaningful description of the error that occured).  If you specified a callback in your
// RPCRequest, it will <b>not</b> be called if the status shows a failure (see below for how to
// change this).
// <br><br>
// If the status field shows success, the RPCManager takes no special action.
// <br><br>
// The built-in status codes and default behavior are there for convenience.  You can choose to
// completely ignore it and handle errors as you see fit (for example by encoding them into the data
// field returned by the server, and always setting the RPCResponse status field to a success
// value).  In fact, the status field is automatically set to a success code
// (RPCResponse.STATUS_SUCCESS) by the constructor of the RPCResponse object on the server. 
// <br><br>
// If you choose to use the status field, but want to handle the errors yourself in your callback
// (and suppress the default error dialog popped up by the RPCManager), simply specify the
// +link{rpcRequest.willHandleError,willHandleError:true} on your RPCRequest object.  This
// allows you to use the RPCManager.sendError() convenience methods on the server without the
// default error handling behavior on the client.
//
// @treeLocation Client Reference/RPC
// @visibility external
//<
isc.ClassFactory.defineClass("RPCManager");
isc.RPC = isc.rpc = isc.RPCManager;
//>Offline
isc.Page.observe(isc, "goOffline", "isc.rpc.goOffline()");
isc.Page.observe(isc, "goOnline", "isc.rpc.goOnline()");
//<Offline

// ---------------------------------------------------------------------------------------
//>	@class RPCRequest
// 
// Encapsulates a client/server RPC request.  You'll need to provide an instance of this class (or a
// constructor for it) to the +link{classMethod:RPCManager.sendRequest()} method.  If you use the 
// +link{classMethod:RPCManager.send()} method, an instance of RPCRequest will be created for you.
//
// @see RPCManager.send()
// @see RPCManager.sendRequest()
// @visibility external
// @treeLocation Client Reference/RPC
//<
isc.ClassFactory.defineClass("RPCRequest");


//> @attr rpcRequest.data (any serializeable : null : IRW)
//
// This attribute specifies the payload of the RPCRequest.  When using the SmartClient server,
// any JavaScript simple type or arbitrarily nested set of Objects and Arrays can be sent
// to server and automatically translated to Java Objects.  Here are the 
// mapping of JavaScript types to their corresponding server object types:<br><br>
//
// <table class='normal' border='1'>
//   <tr><td><b>JS Type</b></td>     <td><b>Java Type</b></td> <td><b>C# Type</b></td> <td><b>Perl Type</b></td></tr>
//
//   <tr><td>Object: {}</td>         <td>Map</td>              <td>IDictionary</td>      <td>Associative Array: {}</td></tr>
//   <tr><td>Array: []</td>          <td>List</td>             <td>IList</td>      <td>Array: []</td></tr>
//   <tr><td>String</td>             <td>String</td>           <td>string</td>         <td>string</td></tr>
//   <tr><td>Number</td>             <td>Long|Double</td>      <td>long|double</td>    <td>string</td></tr>
//   <tr><td>Boolean</td>            <td>Boolean</td>          <td>bool</td>           <td>string</td></tr>
//   <tr><td>Date</td>               <td>java.util.Date</td>   <td>DateTime</td>       <td>string</td></tr>
// 
// </table>
// <br><br>
// Note that the order of keys/values in the Maps created on the server is not guaranteed
// because JavaScript Object literals do not guarantee order.
// <p>
// Server->client conversion follows the this table as well, with some extras.  See the toJS()
// method on JSTranslater in the server documentation for a description of additional
// behaviors.
// <P>
// When <b>not</b> communicating with the SmartClient server, <code>rpcRequest.data</code>
// becomes simple HTTP parameters or an HTTP request body - see +link{rpcRequest.useSimpleHttp}
// for details.
//
// @visibility external
//<

//> @attr rpcRequest.actionURL (URL : RPCManager.actionURL : IRW)
//
// Overrides RPCManager.actionURL for this request only.  If you're using queuing, note that queues
// as per-URL - in other words all RPCRequests in a queue must go to a single URL.  If you attempt
// to send a request with an actionURL that is different from those already in the queue, it
// will be sent to the server separately, ahead of the queue,  and a warning will be logged to
// the Developer Console.
// 
// @see classAttr:RPCManager.actionURL
//
// @visibility external
//<

//>@groupDef    rpcPrompt
// The properties in this group all deal with setting and styling a modal prompt during an RPC
// call to the server.
// @visibility external
//<

//> @attr rpcRequest.promptStyle (PromptStyle : RPCManager.promptStyle : IRW)
// Controls the prompt style for this request only.  Defaults to
// +link{RPCManager.promptStyle}.
//
// @see RPCManager.promptStyle
// @group rpcPrompt
// @visibility external
//<

//> @classAttr rpcRequest.useCursorTracker (boolean : platform-dependent : IRW)
//
// If true, an image is shown to the right of the cursor when +link{rpcRequest.promptStyle} is
// set to "cursor", otherwise the cursor itself is modified via css to the value of
// +link{rpcRequest.promptCursor}.  The default is platform-dependent.  In Safari, IE 5.5 and
// Firefox 1.0 the default is true, on all other platforms it is false.  The reason for this
// split is that the above browsers require that the cursor move before CSS settings are
// re-evaluated - this means the progress cursor can stick until the user moves the mouse.
// <p>
// If left unspecified, the default value is set by +link{RPCManager.useCursorTracker}.
//
// @see RPCManager.useCursorTracker
// @group rpcPrompt
// @visibility external
//<

//> @attr rpcRequest.promptCursor (String : browser-dependent : IRW)
// Controls the cursor shown when +link{rpcManager.promptStyle} is set to
// <code>"cursor"</code> for this request only. Defaults to +link{RPCManager.promptCursor}.
// <p>
// In Safari, IE 5.5 and Firefox 1.0 the default value is "wait", on all other platforms it is
// "progress".  The reason for this split is that the above-mentioned browsers do not support
// CSS2.1 - which is required for the "progress" cursor type.
//
// @see RPCManager.promptCursor
// @group rpcPrompt
// @visibility external
//<


//> @attr rpcRequest.prompt (string : RPCManager.defaultPrompt : IRW)
//
// Overrides RPCManager.defaultPrompt for this request only.  If you're using queuing, note that the
// prompt string from the first request in the queue is the one that is shown to the user.
// 
// @see classAttr:RPCManager.defaultPrompt
// @see classAttr:RPCManager.showPrompt
// @see classAttr:RPCManager.promptStyle
// @see classAttr:RPCManager.promptCursor
// @see attr:rpcRequest.showPrompt
// @see attr:rpcRequest.promptStyle
// @see attr:rpcRequest.promptCursor
//
// @group rpcPrompt
// @visibility external
//<

//> @attr rpcRequest.showPrompt (boolean : RPCManager.showPrompt : IRW)
//
// Overrides RPCManager.showPrompt for this request only.  If you're using queuing, note that
// if any of the requests in the queue specify showPrompt:true, then a prompt will be shown for
// the entire queue with the prompt text of the first request in the queue to specify a custom
// prompt if promptStyle is set to "dialog".  If promptStyle is set to "cursor" for the request
// that specified showPrompt: true, then the entire queue uses the "cursor" style for the
// prompt.
//
// @see classAttr:RPCManager.showPrompt
// @group rpcPrompt
// @visibility external
//<

//> @attr rpcRequest.callback (RPCCallback : null : IRW)
// 
// If you expect to receive a response to your RPC request, you can specify a callback that
// will be called with an instance or RPCResponse class as sent by the server.  Queuing does
// not affect callbacks in any way - your specified callback will be invoked for each
// RPCRequest that contained a callback regardless of whether the request was sent as part of a
// queue or not.
//
// @visibility external
//<

//> @attr rpcRequest.clientContext (Object : null : IRW)
// 
// An object to be held onto for the duration of the RPC turnaround to track
// application-specific context.
// <br>
// When an RPC turnaround completes, the <code>clientContext</code> is available in the
// +link{type:RPCCallback} as <code>rpcResponse.clientContext</code>.  The
// <code>clientContext</code> is never sent to the server.
// <br>
// The <code>clientContext</code> is useful for holding onto state that will be used when the
// +link{type:RPCCallback} fires, such as the name of a component that will receive the
// returned data.
// 
// @see RPCResponse.clientContext
//
// @visibility external
//<

//> @attr rpcRequest.willHandleError (boolean : false : IRW)
//
// With willHandleError:false, rpcResponses that indicate an error go through centralized
// handling in the RPCManager and rpcRequest.callback is never invoked.
// <P>
// Setting willHandleError:true means that your rpcRequest.callback will receive rpcResponses
// that have an error status and must handle them.
// <P>
// See also the error handling section in the +link{class:RPCManager} docs.
// 
// @see class:RPCManager
//
// @visibility external
//<

//> @attr rpcRequest.timeout (number : RPCManager.defaultTimeout : IRWA)