com.smartgwt.client.rpc
Class RPCManager

java.lang.Object
  extended by com.smartgwt.client.rpc.RPCManager

public class RPCManager
extends java.lang.Object

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.

SmartGWT's powerful DataBoundComponent automatically issue RPCs as necessary, based on the 'DataSource protocol'. To integrate DataBoundComponents with your server, 'start here'.

Simple example (client code):

var data = { here: "is some data", to: ["send to the server"]};
RPCManager.sendRequest({ data: data, callback: "myCallback(data)", actionURL: "/rpcHandler.jsp"});
function myCallback(data) { alert("response from the server: " + data); }


Simple example (server code: /rpcHandler.jsp):

RPCManager rpc = new RPCManager(request, response, out);
Object data = rpc.getData();
System.out.println("client sent: " + data.toString());
rpc.send("here's a response");

Note that, while the example above uses the SmartGWT Java Server, the RPCManager is also capable of issuing RPCs that do not require a SmartGWT server. See 'Client-Side Data Integration' for details.

Queuing
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.

Queuing example (client code):

RPCManager.startQueue();
RPCManager.send("a string of data", "myCallback(data)", {actionURL: "/rpcHandler.jsp"});
RPCManager.sendRequest({ data: ["some", "more data", 2], callback: "myCallback(data)", actionURL: "/rpcHandler.jsp"});
RPCManager.sendRequest({ data: "different callback", callback: "myCallback2(data)", actionURL: "/rpcHandler.jsp"});
RPCManager.sendQueue()
function myCallback(data) { alert("response from the server: " + data); }
function myCallback2(data) { alert("response from the server (other callback): " + data); }


Queuing example (server code: /rpcHandler.jsp):

RPCManager rpc = new RPCManager(request, response, out);
for(Iterator i = rpc.getRequests().iterator(); i.hasNext();) {
    RPCRequest rpcRequest = (RPCRequest)i.next();
    Object data = rpcRequest.getData();
    System.out.println("client sent:" + data.toString());
    //send back the data sent to us by the client
    rpc.send(rpcRequest, new RPCResponse(data));
}


Error Handling
The 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.

If the status field shows a failure, the RPCManager will, by default, show a dialog with the contents of the 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 not be called if the status shows a failure (see below for how to change this).

If the status field shows success, the RPCManager takes no special action.

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.

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 willHandleError 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.


Constructor Summary
RPCManager()
           
 
Method Summary
static void cancelQueue()
          Cancel a transaction (a queue of requests being sent to the server).
static void clearTransaction(java.lang.String transactionNum)
          Erase all client-side record of a transaction, such that any response from the server will be ignored.
static void resendTransaction()
          Resend a suspended transaction to the server.
static void resendTransaction(java.lang.String transactionNum)
          Resend a suspended transaction to the server.
static void sendQueue()
          Send all currently queued requests to the server.
static void setActionURL(java.lang.String actionURL)
          The actionURL specifies the URL to which the RPC request will be sent.
static void setCredentialsURL(java.lang.String credentialsURL)
          Specifies URL where credentials should be submitted to attempt relogin when session timeout is encountered during a background RPC.
static void setDefaultPrompt(java.lang.String defaultPrompt)
          If showPrompt is enabled for a given transaction, this is the defaultPrompt to be shown to the user in a modal dialog while the transaction occurs.
static void setDefaultTimeout(double defaultTimeout)
          In milliseconds, how long the RPCManager waits for an RPC request to complete before returning an error.
static void setFetchDataPrompt(java.lang.String fetchDataPrompt)
          Default prompt displayed to the user while an operation is running to fetch data from the server.
static void setHandleErrorCallback(HandleErrorCallback callback)
          By default handleError() always logs a warning.
static void setLoginRequiredCallback(LoginRequiredCallback callback)
          The rpcRequest parameter can be used to determine whether the suspended transaction can simply be dropped (eg, it's periodic polling request).
static void setPromptCursor(java.lang.String promptCursor)
          Controls the default cursor shown when RPCManager.promptStyle is set to "cursor".
static void setPromptStyle(PromptStyle promptStyle)
          Controls the default prompt style.
static void setRemoveDataPrompt(java.lang.String removeDataPrompt)
          Default prompt displayed to user while an opration is running to remove data from the server.
static void setSaveDataPrompt(java.lang.String saveDataPrompt)
          Default prompt displayed to the user while an opreration is running to save data to the server.
static void setShowPrompt(boolean showPrompt)
          If set to true, the RPCManager will block the UI with a modal dialog containing the text from RPCManager.defaultPrompt (or the per-RPCRequest override) until the RPC to the server completes.
static void setTimeoutErrorMessage(java.lang.String timeoutErrorMessage)
          Default message displayed to user when an opration fails to return from the server within the timeout period specified by RPCManager.defaultTimeout.
static void setUseCursorTracking(boolean useCursorTracking)
          If true, an image is shown to the right of the cursor when RPCRequest.promptStyle is set to "cursor", otherwise the cursor itself is modified via css to the value of RPCRequest.promptCursor.
static void setUseHttpProxy(java.lang.Boolean useProxy)
          Whether to ever attempt to use the "HttpProxy" servlet to enable web service requests to servers other than the origin server.
static void startQueue()
          Start queuing requests.
static void suspendTransaction()
          Suspends the current transaction, such that all processing of the transaction is halted, any remaining callback in the transaction won't fire, and the transaction can never timeout.
static void suspendTransaction(java.lang.String transactionID)
          Suspends the current transaction, such that all processing of the transaction is halted, any remaining callback in the transaction won't fire, and the transaction can never timeout.
static java.lang.Boolean xmlHttpRequestAvailable()
           Returns true if the XMLHttpRequest object is available, false otherwise.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RPCManager

public RPCManager()
Method Detail

xmlHttpRequestAvailable

public static java.lang.Boolean xmlHttpRequestAvailable()
Returns true if the XMLHttpRequest object is available, false otherwise. See PlatformDependencies for more information on when XMLHttpRequest parser may not available and what features are impacted as a result.

Returns:
true if XMLHttpRequest is available, false otherwise.

cancelQueue

public static void cancelQueue()
Cancel a transaction (a queue of requests being sent to the server).


clearTransaction

public static void clearTransaction(java.lang.String transactionNum)
Erase all client-side record of a transaction, such that any response from the server will be ignored.

A transaction means a batch of one or more RPCRequests that have already been sent to the server via sendQueue().

Parameters:
transactionNum - id of the transaction to be cleared

resendTransaction

public static void resendTransaction()
Resend a suspended transaction to the server. See suspendTransaction() for context.

Note that the transaction must have been previously suspended, and in particular suspended validly according to the rules described in the docs for suspendTransaction(), or undefined results will occur.

You can resend all suspended transactions by calling resendTransaction() with no arguments.


resendTransaction

public static void resendTransaction(java.lang.String transactionNum)
Resend a suspended transaction to the server. See suspendTransaction() for context.

Note that the transaction must have been previously suspended, and in particular suspended validly according to the rules described in the docs for suspendTransaction(), or undefined results will occur.

You can resend all suspended transactions by calling resendTransaction() with no arguments.

Parameters:
transactionNum - id of the transaction to be re-sent, or null to resend all suspended transactions

setActionURL

public static void setActionURL(java.lang.String actionURL)
The actionURL specifies the URL to which the RPC request will be sent. Note that if you override this global default and your application uses DataSource databound components, you'll need to dispatch the DataSource requests from your RPC handler. Your other option is to specify a url on a per-request basis.

Parameters:
actionURL - the action URL.

setCredentialsURL

public static void setCredentialsURL(java.lang.String credentialsURL)
Specifies URL where credentials should be submitted to attempt relogin when session timeout is encountered during a background RPC.

Parameters:
credentialsURL - default value http://localhost:8080/isomorphic/login/loginSuccessMarker.html

setDefaultPrompt

public static void setDefaultPrompt(java.lang.String defaultPrompt)
If showPrompt is enabled for a given transaction, this is the defaultPrompt to be shown to the user in a modal dialog while the transaction occurs. May be overridden at the request level via RPCRequest.prompt.

More targetted default prompts are also supported for certain code-paths. See the following set of properties for details:

Parameters:
defaultPrompt - the default value is 'Contacting Server...'

setDefaultTimeout

public static void setDefaultTimeout(double defaultTimeout)

In milliseconds, how long the RPCManager waits for an RPC request to complete before returning an error. If set to zero, the RPCManager will not enforce a timeout, but note that most browsers enforce their own timeouts on HTTP requests.

For the "xmlHttpRequest" transport, this timeout can only happen if the server actually fails to respond within the specified number of milliseconds. For the "hiddenFrames" transport, this timeout will occur for non-200 (HTTP_OK) responses.

Parameters:
defaultTimeout - the default value is 240000 [4 minutes]

setFetchDataPrompt

public static void setFetchDataPrompt(java.lang.String fetchDataPrompt)
Default prompt displayed to the user while an operation is running to fetch data from the server. Displayed as a result of ListGrid.filterData(), ListGrid.fetchData() and ListGrid.clearCriteria() code paths.

Parameters:
fetchDataPrompt - defaults to "Finding Records that match your criteria..."

setRemoveDataPrompt

public static void setRemoveDataPrompt(java.lang.String removeDataPrompt)
Default prompt displayed to user while an opration is running to remove data from the server. Displayed as a result of the ListGrid.removeSelectedData() code path.

Parameters:
removeDataPrompt - default value "Deleting Record(s)..."

setSaveDataPrompt

public static void setSaveDataPrompt(java.lang.String saveDataPrompt)
Default prompt displayed to the user while an opreration is running to save data to the server. Displayed as a result of the DynamicForm.saveData() code path.

Parameters:
saveDataPrompt - default value "Saving form..."

setPromptCursor

public static void setPromptCursor(java.lang.String promptCursor)
Controls the default cursor shown when RPCManager.promptStyle is set to "cursor". Overrideable by RPCRequest.promptCursor. 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.

Parameters:
promptCursor - default is browser dependant

setPromptStyle

public static void setPromptStyle(PromptStyle promptStyle)
Controls the default prompt style. Overrideable by RPCRequest.promptStyle.

Parameters:
promptStyle - default is PromptStyle.DIALOG

setShowPrompt

public static void setShowPrompt(boolean showPrompt)
If set to true, the RPCManager will block the UI with a modal dialog containing the text from RPCManager.defaultPrompt (or the per-RPCRequest override) until the RPC to the server completes.

If set to false, the RPC happens transparently, allowing the user to continue interacting with the UI

Parameters:
showPrompt - default is false

setTimeoutErrorMessage

public static void setTimeoutErrorMessage(java.lang.String timeoutErrorMessage)
Default message displayed to user when an opration fails to return from the server within the timeout period specified by RPCManager.defaultTimeout.

Parameters:
timeoutErrorMessage - default value is "Operation timed out"

setUseCursorTracking

public static void setUseCursorTracking(boolean useCursorTracking)
If true, an image is shown to the right of the cursor when RPCRequest.promptStyle is set to "cursor", otherwise the cursor itself is modified via css to the value of 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.

This value can be overridden on a per-request basis via RPCRequest.useCursorTracker.

Parameters:
useCursorTracking - default value is platform-dependant

setUseHttpProxy

public static void setUseHttpProxy(java.lang.Boolean useProxy)
Whether to ever attempt to use the "HttpProxy" servlet to enable web service requests to servers other than the origin server.

Parameters:
useProxy - enable or disable attempting to use the "HttpProxy" servlet

setLoginRequiredCallback

public static void setLoginRequiredCallback(LoginRequiredCallback callback)
The rpcRequest parameter can be used to determine whether the suspended transaction can simply be dropped (eg, it's periodic polling request).

The rpcResponse parameter has rpcResponse.data set to the raw text of the response that triggered loginRequired(). Some very advanced relogin strategies may need to inspect the raw response to get information needed for re-authentication.

Parameters:
callback - the LoginRequiredCallback

setHandleErrorCallback

public static void setHandleErrorCallback(HandleErrorCallback callback)
By default handleError() always logs a warning. In addition, if response.data was set to a String, a warning dialog will be shown to the user with response.data as the message, which allows the server to send user error messages back without writing custom client-side error handling.

To do custom error handling that is specific to a particular component or type of request, set RPCRequest.willHandleError and deal with errors in the rpcRequest.callback. To change the default system-wide error handling, register this callback.

If you're using the xmlHttpRequest RPCRequest.transport, you can access the HTTP status code of the response (eg 404 Not Found or 500 Server Error) as RPCResponse.httpResponseCode.

For very advanced usage, the response.xmlHttpRequest contains the native XMLHttpRequest object used to make the request. Accessing this object is subject to possible cross-platform bugs and inconsistencies, and we recommend that you wrap any access to the XMLHttpRequest object in a try/catch block because some browsers may throw exceptions when certain attributes of this object are accessed. For example, if you try to access XMLHttpRequest.status (for the HTTP status code) when the network cable is unpluged in Windows, you'll get an Exception in Firefox.

Parameters:
callback - the callback

startQueue

public static void startQueue()
Start queuing requests. When queuing requests, an HTTP request will not be sent to the server until RPCManager.sendQueue() is called.

All requests in a given queue must go to the same actionURL and use the same transport (XMLHttp or frames). If a request specifies a different actionURL or transport than that of the requests currently on the queue, it will be sent to the server separately, ahead of the queue, and a warning will be logged to the Developer Console.

Note that the server must process all requests sent as part of the queue before any response is sent to the client. You should avoid batching a request that will take a long time to process on the server with any other requests because it will delay the response of all requests in the queue.


sendQueue

public static void sendQueue()
Send all currently queued requests to the server. You need only call this method if you are using queuing otherwise your requests are synchronously submitted to the server.

NOTE: if you aren't the caller who first enables queuing (startQueue() returns true), you should in general avoid calling sendQueue(), because whoever was first to enable queuing may have more requests to add to the same queue.


suspendTransaction

public static void suspendTransaction()
Suspends the current transaction, such that all processing of the transaction is halted, any remaining callback in the transaction won't fire, and the transaction can never timeout.

suspendTransaction() is typically used to handle total failures for an entire transaction, such as HTTP status 500, or session timeout resulting in com.smartgwt.client.rpc.RPCManager#loginRequired being called. In both cases the intent is to put the transaction on hold so that a transient problem can be resolved, and then the transaction can be re-sent successfully. By using suspendTransaction(), components that submitted requests never realize there was a transient failure, and so error handling logic does not have to be implemented in every component.

Generally you can only validly suspend a transaction from either com.smartgwt.client.rpc.RPCManager#loginRequired or com.smartgwt.client.rpc.RPCManager#handleError, and in the case of handleError(), only when the first response in the transaction has an error. Suspending and re-sending a partially processed transaction means that some responses will be processed twice, with undefined results for requests issued automatically by UI components.

A suspended transaction must ultimately be either cleared via clearTransaction(java.lang.String) or re-sent via resendTransaction() or memory will be leaked.


suspendTransaction

public static void suspendTransaction(java.lang.String transactionID)
Suspends the current transaction, such that all processing of the transaction is halted, any remaining callback in the transaction won't fire, and the transaction can never timeout.

suspendTransaction() is typically used to handle total failures for an entire transaction, such as HTTP status 500, or session timeout resulting in com.smartgwt.client.rpc.RPCManager#loginRequired being called. In both cases the intent is to put the transaction on hold so that a transient problem can be resolved, and then the transaction can be re-sent successfully. By using suspendTransaction(), components that submitted requests never realize there was a transient failure, and so error handling logic does not have to be implemented in every component.

Generally you can only validly suspend a transaction from either com.smartgwt.client.rpc.RPCManager#loginRequired or com.smartgwt.client.rpc.RPCManager#handleError, and in the case of handleError(), only when the first response in the transaction has an error. Suspending and re-sending a partially processed transaction means that some responses will be processed twice, with undefined results for requests issued automatically by UI components.

A suspended transaction must ultimately be either cleared via clearTransaction(java.lang.String) or re-sent via resendTransaction() or memory will be leaked.

Parameters:
transactionID - transaction to delay. Defaults to the current transaction if there is one