|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.smartgwt.client.rpc.RPCManager
public 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.
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 |
---|
public RPCManager()
Method Detail |
---|
public static java.lang.Boolean xmlHttpRequestAvailable()
PlatformDependencies
for more information on when XMLHttpRequest parser may
not available and what features are
impacted as a result.
public static void cancelQueue()
public static void clearTransaction(java.lang.String transactionNum)
A transaction means a batch of one or more RPCRequests that have already been sent to
the server via sendQueue()
.
transactionNum
- id of the transaction to be clearedpublic static void resendTransaction()
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.
public static void resendTransaction(java.lang.String transactionNum)
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.
transactionNum
- id of the transaction to be re-sent, or null to resend all suspended transactionspublic static void setActionURL(java.lang.String actionURL)
actionURL
- the action URL.public static void setCredentialsURL(java.lang.String credentialsURL)
credentialsURL
- default value http://localhost:8080/isomorphic/login/loginSuccessMarker.htmlpublic static void setDefaultPrompt(java.lang.String defaultPrompt)
defaultPrompt
- the default value is 'Contacting Server...'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.
defaultTimeout
- the default value is 240000 [4 minutes]public static void setFetchDataPrompt(java.lang.String fetchDataPrompt)
fetchDataPrompt
- defaults to "Finding Records that match your criteria..."public static void setRemoveDataPrompt(java.lang.String removeDataPrompt)
removeDataPrompt
- default value "Deleting Record(s)..."public static void setSaveDataPrompt(java.lang.String saveDataPrompt)
saveDataPrompt
- default value "Saving form..."public static void setPromptCursor(java.lang.String promptCursor)
promptCursor
- default is browser dependantpublic static void setPromptStyle(PromptStyle promptStyle)
promptStyle
- default is PromptStyle.DIALOG
public static void setShowPrompt(boolean showPrompt)
showPrompt
- default is falsepublic static void setTimeoutErrorMessage(java.lang.String timeoutErrorMessage)
timeoutErrorMessage
- default value is "Operation timed out"public static void setUseCursorTracking(boolean useCursorTracking)
useCursorTracking
- default value is platform-dependantpublic static void setUseHttpProxy(java.lang.Boolean useProxy)
useProxy
- enable or disable attempting to use the "HttpProxy" servletpublic static void setLoginRequiredCallback(LoginRequiredCallback callback)
callback
- the LoginRequiredCallbackpublic static void setHandleErrorCallback(HandleErrorCallback callback)
callback
- the callbackpublic static void startQueue()
public static void sendQueue()
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.
public static void suspendTransaction()
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.
public static void suspendTransaction(java.lang.String transactionID)
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.
transactionID
- transaction to delay. Defaults to the current transaction if there is one
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |