com.smartgwt.client.rpc

Class RPCManager

java.lang.Object

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.

Smart GWT's powerful databinding subsystem (see DataSource, DataBoundComponents) automatically make use of this class to issue RPCs as necessary, based on the DataSource protocol. To integrate DataBoundComponents with your server, start here.

For arbitrary client/server interactions outside of the DataSource subsystem, the Smart GWT server also provides the Direct Method Invocation feature.

The RPCManager class can also be used directly to send data to a URL of your choosing and optionally be called back with server-returned data when the server replies.

The Smart GWT server code has APIs for processing RPC requests providing features such as automatic Java <--> JavaScript object translation and handling of queued requests.
The IDACall servlet makes use of these features to handle standard DataSource requests and DMI calls. Developers can also override the actionURL of specific requests and use these APIs directly in a JSP, Servlet or Filter.

Note: the client-side RPCManager class can also be used without the Smart GWT server. For an overview of client/server interactions without the Smart GWT server, see this overview.

Simple arbitrary Remote Procedure Call example (client code):

   RPCRequest request = new RPCRequest();
   // Note data could be a String, Map or Record
   request.setData("Some data to send to the client");
   request.setActionURL("/rpcHandler.jsp");
  
   RPCManager.sendRequest(request, 
       new RPCCallback () {
           public void execute(RPCResponse response, Object rawData, RPCRequest request) {
               SC.say("Response from the server:" + rawData);
           }
       }
   );
  

Simple arbitrary Remote Procedure Call 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");


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):

   boolean wasQueuing = RPCManager.startQueue();
   
   RPCCallback callback = new RPCCallback() {
       public void execute(RPCResponse response, Object rawData, RPCRequest request) {
           Window.alert("response from server:" + rawData);
       }
   };
    
   RPCRequest request1 = new RPCRequest();
   request1.setActionURL("/rpcHandler.jsp");
   request1.setData("A String of Data");
   RPCManager.sendRequest(request1, callback);
    
   RPCRequest request2 = new RPCRequest();
   request2.setActionURL("/rpcHandler.jsp");
   request2.setData("Another String of Data");
   RPCManager.sendRequest(request2, callback);
    
   if (!wasQueuing) RPCManager.sendQueue();
  

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

Please see this separate article on error handling.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ALL_GLOBALS ALL_GLOBALS constant used by the loadScreen(String, LoadScreenCallback, String[]) API.

Constructor Summary

Constructors

Constructor and Description
RPCManager()

Method Summary

Methods

Modifier and Type	Method and Description
static void	cacheScreens(java.lang.String[] screens, Function callback) Loads the definitions of a set of screens saved in Component XML format, using the ScreenLoaderServlet.
static void	cacheScreens(java.lang.String[] screens, Function callback, java.lang.String locale) Loads the definitions of a set of screens saved in Component XML format, using the ScreenLoaderServlet.
static void	cacheScreens(java.lang.String[] screens, Function callback, java.lang.String locale, RPCRequest requestProperties) Loads the definitions of a set of screens saved in Component XML format, using the ScreenLoaderServlet.
static void	cancelQueue() Cancel a queue of requests (also called a transaction).
static void	cancelQueue(java.lang.String transactionNum) Cancel a queue of requests (also called a transaction).
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 Canvas	createScreen(java.lang.String screenName) Creates a screen previously cached by a call to cacheScreens(String[], Function, String, RPCRequest).
static Canvas	createScreen(java.lang.String screenName, java.lang.String[] globals) Creates a screen previously cached by a call to cacheScreens(String[], Function, String, RPCRequest).
static void	exportContent(Canvas canvas) Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).
static void	exportContent(Canvas[] components) Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).
static void	exportContent(Canvas[] components, DSRequest requestProperties) Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).
static void	exportContent(Canvas canvas, DSRequest requestProperties) Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).
static void	exportContent(java.lang.String htmlFragment) Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).
static void	exportContent(java.lang.String htmlFragment, DSRequest requestProperties) Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).
static void	exportImage(java.lang.String svgString)
static void	exportImage(java.lang.String svgString, DSRequest requestProperties)
static void	exportImage(java.lang.String svgString, DSRequest requestProperties, ExportImageCallback callback) Converts an SVG string to one of several possible image formats, and can either initiate a download or return the base64-encoded image data.
static java.lang.String	getCurrentTransactionId() Returns the id of the current transaction (a queue of requests).
static void	loadScreen(java.lang.String screenName, LoadScreenCallback callback) Loads a screen saved in Component XML format.
static void	loadScreen(java.lang.String screenName, LoadScreenCallback callback, java.lang.String[] globals) Loads a screen saved in Component XML format.
static void	loadScreen(java.lang.String screenName, LoadScreenCallback callback, java.lang.String[] globals, RPCRequest requestProperties) Loads a screen saved in Component XML format.
static void	loadScreen(java.lang.String screenName, LoadScreenCallback callback, java.lang.String[] globals, java.lang.String locale, RPCRequest requestProperties) Loads a screen saved in Component XML format, using the ScreenLoaderServlet.
static java.lang.Boolean	requestsArePending() Returns whether there are any pending RPC requests.
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	send(com.google.gwt.core.client.JavaScriptObject data, RPCCallback callback, java.util.Map requestParams) This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().
static void	send(com.google.gwt.core.client.JavaScriptObject data, RPCCallback callback, RPCRequest requestParams) This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().
static void	send(java.lang.String data, RPCCallback callback, java.util.Map requestParams) This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().
static void	send(java.lang.String data, RPCCallback callback, RPCRequest requestParams) This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().
static void	sendProxied(RPCRequest request, RPCCallback callback) Send an HTTP request to a remote host, potentially through the HttpProxy servlet installed on the Smart GWT Server.
static void	sendQueue() Send all currently queued requests to the server.
static void	sendQueue(RPCQueueCallback callback) Send all currently queued requests to the server.
static void	sendRequest(RPCRequest rpcRequestProperties) Send the passed RPCRequest to the server.
static void	sendRequest(RPCRequest rpcRequestProperties, RPCCallback callback) Send the passed RPCRequest 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	setAllowCrossDomainCalls(java.lang.Boolean allowCrossDomainCalls) By default SmartGWT will show a warning message on attempted requests to another domain as this is usually not supported at the browser level by default due to security considerations.
static void	setAllowIE9Leak(boolean allowLeak) In Internet Explorer 9, when a string of JavaScript is evaluated via the native eval() function, objects created within that evaluation are not released from browser memory until the page is reloaded.
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) handleError will be called if status is negative and willHandleError was not set.
static void	setHandleTransportErrorCallback(HandleTransportErrorCallback callback) Method to handle server error responses to submitted transactions.
static void	setLoginRequiredCallback(LoginRequiredCallback callback) Called when a session timeout is encountered while trying to do a background RPC.
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	setQueueSentCallback(QueueSentCallback callback) This method is called by the RPCManager every time it sends a queue of requests to the server (note that if you not using queuing, the system simply sends queues containing just one request, so this API is valid regardless).
static void	setRemoveDataPrompt(java.lang.String removeDataPrompt) Default prompt displayed to user while an operation is running to remove data from the server.
static void	setSaveDataPrompt(java.lang.String saveDataPrompt) Default prompt displayed to the user while an operation 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 operation 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 boolean	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

Field Detail

ALL_GLOBALS

public static final java.lang.String ALL_GLOBALS

ALL_GLOBALS constant used by the loadScreen(String, LoadScreenCallback, String[]) API.

See Also:

Constant Field Values

Constructor Detail

RPCManager

public RPCManager()

Method Detail

cancelQueue

public static void cancelQueue()

Cancel a queue of requests (also called a transaction).

If a transactionId is passed, that transaction will be cancelled, otherwise, the current (not yet sent) transaction is cancelled. You can retrieve the id of the current transaction, if there is one, by calling getCurrentTransactionId() before the transaction has been sent.

Note that cancelQueue() calls clearTransaction() and attempts to abort the request. However, note also that whilst cancelling a transaction that has already been sent will not necessarily stop the HTTP request that has been issued - this is only possible on some browsers and with some transports - it will reliably cause Smart GWT to ignore any response returned by the server and not fire any callbacks that have been passed in.

cancelQueue

public static void cancelQueue(java.lang.String transactionNum)

Cancel a queue of requests (also called a transaction).

If a transactionId is passed, that transaction will be cancelled, otherwise, the current (not yet sent) transaction is cancelled. You can retrieve the id of the current transaction, if there is one, by calling getCurrentTransactionId() before the transaction has been sent.

Note that cancelQueue() calls clearTransaction() and attempts to abort the request. However, note also that whilst cancelling a transaction that has already been sent will not necessarily stop the HTTP request that has been issued - this is only possible on some browsers and with some transports - it will reliably cause Smart GWT to ignore any response returned by the server and not fire any callbacks that have been passed in.

Parameters:

transactionNum - transactionId of the queue.

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 RPCManager.sendQueue.

You can retrieve the id of the current transaction, if there is one, by getCurrentTransactionId() before the transaction is sent.

Parameters:

transactionNum - id of the transaction to be cleared

setHandleErrorCallback

public static void setHandleErrorCallback(HandleErrorCallback callback)

handleError will be called if status is negative and willHandleError was not set.

This method is called for both DSResponses and RPCResponses that have a non-success status. You can check whether the response is a DSResponse by checking response.isDSResponse.

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 willHandleError and deal with errors in the rpcRequest.callback. To change the default system-wide error handling, override this method. Note that since handleError() is a class method, to override it you will call addClassProperties() rather than addProperties(), like so:

      isc.RPCManager.addClassProperties({
          handleError : function (response, request) { .. custom handling .. }
      })
  

If you're using the xmlHttpRequest transport, you can access the HTTP status code of the response (eg 404 Not Found or 500 Server Error) as 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 Isomorphic recommends 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 - HandleErrorCallback the callback to set.

setHandleTransportErrorCallback

public static void setHandleTransportErrorCallback(HandleTransportErrorCallback callback)

Method to handle server error responses to submitted transactions. When the server responds to a submitted transaction with an HTTP error code this method will be called before any individual response callbacks are fired, regardless of whether willHandleError was specified on the submitted request[s].

This provides the developer with an opportunity to handle a server error by (for example) suspending and resubmitting the transaction before any other handling occurs.

The default implementation takes no action - by default transport errors are handled via RPCManager.handleError, or by the standard request callback methods, depending on request.willHandleError. To perform custom handing for transport errors this classMethod may be overridden as follows

      isc.RPCManager.addClassProperties({
          handleTransportError : function (transactionNum, status, httpResponseCode, httpResponseText) 
          {
                 .. custom handling .. 
          }
      })
  

Note: This method only applies to operations submitted via XMLHttpRequest - it is not possible to provide similar error handling for other transports.

Parameters:

callback - HandleTransportErrorCallback the callback to set.

setLoginRequiredCallback

public static void setLoginRequiredCallback(LoginRequiredCallback callback)

Called when a session timeout is encountered while trying to do a background RPC. See Relogin.

The transaction with the passed transactionId is suspended, and should either be cleared or resent after the user has been re-authenticated.

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 - LoginRequiredCallback the callback to set.

setQueueSentCallback

public static void setQueueSentCallback(QueueSentCallback callback)

This method is called by the RPCManager every time it sends a queue of requests to the server (note that if you not using queuing, the system simply sends queues containing just one request, so this API is valid regardless).

There is no default implementation of this method; it is simply an override point. It is intended to be used by user code that needs to be notified when Smart GWT sends requests to the server. Note that the list of RPCRequests passed to this method is strictly read-only.

Parameters:

callback - QueueSentCallback the callback to set.

requestsArePending

public static java.lang.Boolean requestsArePending()

Returns whether there are any pending RPC requests.

Returns:

true if one or more RPC requests are pending, false otherwise.

resendTransaction

public static void resendTransaction()

Resend a suspended transaction to the server. See RPCManager.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 RPCManager.suspendTransaction, or undefined results will occur.

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

resendTransaction

public static void resendTransaction(java.lang.String transactionNum)

Resend a suspended transaction to the server. See RPCManager.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 RPCManager.suspendTransaction, or undefined results will occur.

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

Parameters:

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

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.

See Also:

send(java.lang.String, com.smartgwt.client.rpc.RPCCallback, com.smartgwt.client.rpc.RPCRequest), sendRequest(com.smartgwt.client.rpc.RPCRequest), startQueue()

sendQueue

public static void sendQueue(RPCQueueCallback callback)

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.

Parameters:

callback - Callback to fire when the queued operations complete. Callback will be fired with 1 parameter: responses an array of DSResponse or RPCResponse objects that were part of the transaction fired by this method.

See Also:

send(java.lang.String, com.smartgwt.client.rpc.RPCCallback, com.smartgwt.client.rpc.RPCRequest), sendRequest(com.smartgwt.client.rpc.RPCRequest), startQueue()

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.

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

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]

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 targeted default prompts are also supported for certain code-paths. See the following set of properties for details:

• RPCManager.removeDataPrompt
• RPCManager.saveDataPrompt
• RPCManager.fetchDataPrompt

Parameters:

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

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 operation 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 operation 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". Overridable 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 dependent

setPromptStyle

public static void setPromptStyle(PromptStyle promptStyle)

Controls the default prompt style. Overridable 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 operation 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-dependent

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

setAllowCrossDomainCalls

public static void setAllowCrossDomainCalls(java.lang.Boolean allowCrossDomainCalls)

By default SmartGWT will show a warning message on attempted requests to another domain as this is usually not supported at the browser level by default due to security considerations.

Some browsers now do support cross domain requests through the use of Http Access Control headers (See the http://www.w3.org/TR/cors/,W3C Cross-Origin Resource Sharing recommendation). If your application intends to rely on this behavior to perform cross-domain requests, you can set allowCrossDomainCalls to true to disable the standard SmartGWT warning when such calls occur.

Note also that this is typically not an issue if you are using the SmartGWT server (part of Pro, Power and Enterprise editions of SmartClient), as this includes the HTTPProxy servlet.

Parameters:

-

startQueue

public static boolean 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.

Returns:

whether queuing was already enabled before we called

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

getCurrentTransactionId

public static java.lang.String getCurrentTransactionId()

Returns the id of the current transaction (a queue of requests).

This method must be called after startQueue() has been called and at least one request has been issued.

Returns:

the transactionNum of the current transaction.

sendProxied

public static void sendProxied(RPCRequest request,
               RPCCallback callback)

Send an HTTP request to a remote host, potentially through the HttpProxy servlet installed on the Smart GWT Server.

This API allows contacting services which are hosted on servers other than the origin server if the HttpProxy servlet is enabled on the Smart GWT Server.

The HttpProxy will be used if the actionURL starts with "http" and uses a hostname other than "localhost" or window.location.hostname, or if the port number differs, or if request.useHttpProxy is explicitly set. Otherwise the request goes to the origin server (the server that returned the current page).

The RPCRequest properties that will be respected when relaying requests via the HttpProxy are: actionURL, httpMethod, params, contentType, httpHeaders, and data. In this case "data", if set, will be used as the request body for an HTTP POST.

Higher-level APIs like DataSource or WebService call through this API, and so automatically use the HttpProxy if dataURL or webService.location is set to a foreign server.

This API is only suitable for direct use when loading unstructured data that will not be shown in a DataBoundComponent. For a WSDL-described web service, use XMLTools.loadWSDL instead. For other web services, use a DataSource with dataURL, and use DataSource.transformRequest and DataSource.transformResponse as necessary to form requests for the service and transform responses for display.

Parameters:

request - rpcRequest to be routed through the HttpProxy

callback - callback to invoke on RPC completion

sendRequest

public static void sendRequest(RPCRequest rpcRequestProperties)

Send the passed RPCRequest to the server. If queuing is in effect, this queues the request instead.

Parameters:

rpcRequestProperties - RPCRequest to send to the server

sendRequest

public static void sendRequest(RPCRequest rpcRequestProperties,
               RPCCallback callback)

Send the passed RPCRequest to the server. If queuing is in effect, this queues the request instead.

Parameters:

rpcRequestProperties - RPCRequest to send to the server

callback - callback to invoke on RPC completion

send

public static void send(java.lang.String data,
        RPCCallback callback,
        RPCRequest requestParams)

This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().

Parameters:

data - data to be passed to the server

callback - callback to invoke on RPC completion

requestParams - any additional properties you want to set - these will be applied to the RPCRequest object that will be auto-created for you.

send

public static void send(java.lang.String data,
        RPCCallback callback,
        java.util.Map requestParams)

This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().

Parameters:

data - data to be passed to the server

callback - callback to invoke on RPC completion

requestParams - any additional properties you want to set - these will be applied to the RPCRequest object that will be auto-created for you.

send

public static void send(com.google.gwt.core.client.JavaScriptObject data,
        RPCCallback callback,
        RPCRequest requestParams)

This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().

Parameters:

data - data to be passed to the server

callback - callback to invoke on RPC completion

requestParams - any additional properties you want to set - these will be applied to the RPCRequest object that will be auto-created for you.

send

public static void send(com.google.gwt.core.client.JavaScriptObject data,
        RPCCallback callback,
        java.util.Map requestParams)

This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().

Parameters:

data - data to be passed to the server

callback - callback to invoke on RPC completion

requestParams - any additional properties you want to set - these will be applied to the RPCRequest object that will be auto-created for you.

loadScreen

public static void loadScreen(java.lang.String screenName,
              LoadScreenCallback callback)

Loads a screen saved in Component XML format. See loadScreen(String, LoadScreenCallback, String[], String, RPCRequest)

Parameters:

screenName - name of the screen to load

callback - callback for notification of screen being loaded

loadScreen

public static void loadScreen(java.lang.String screenName,
              LoadScreenCallback callback,
              java.lang.String[] globals)

Loads a screen saved in Component XML format. See loadScreen(String, LoadScreenCallback, String[], String, RPCRequest)

Parameters:

screenName - name of the screen to load

callback - callback for notification of screen being loaded

globals - widgets to allow to take their global IDs

loadScreen

public static void loadScreen(java.lang.String screenName,
              LoadScreenCallback callback,
              java.lang.String[] globals,
              RPCRequest requestProperties)

Loads a screen saved in Component XML format. See loadScreen(String, LoadScreenCallback, String[], String, RPCRequest)

Parameters:

screenName - name of the screen to load

callback - callback for notification of screen being loaded

globals - widgets to allow to take their global IDs

requestProperties - optional properties for the request

loadScreen

public static void loadScreen(java.lang.String screenName,
              LoadScreenCallback callback,
              java.lang.String[] globals,
              java.lang.String locale,
              RPCRequest requestProperties)

Loads a screen saved in Component XML format, using the ScreenLoaderServlet.

The ScreenLoaderServlet will look for a file named screenName.ui.xml in the directory given by the "project.ui" setting, which defaults webroot/shared/ui and can be configured in server.properties.

The screen provided by the callback will be the outermost component if your loaded screen consists of a hierarchy of widgets all contained under one parent (which is true of any screens created in Visual Builder).

If you have multiple widget hierarchies in your screen, the screen returned will be the last top-level component created.

By default, components in the loaded screens that have global IDs will not actually be allowed to take those global IDs - instead, only widgets that have one of the global IDs passed as the globals parameter will actually receive their global IDs. To override this behavior, pass an array containing the special value ALL_GLOBALS for the globals parameter.

When globals are being suppressed, the screen available in the callback will provide access to widgets that did not receive their global IDs via Canvas.getByLocalId(String), and the suppressedGlobals available in the callback will be a mapping from suppressed global ID to the widget or other component that would have used that global ID if globals were not suppressed.

To load multiple screens at once, use cacheScreens(String[], Function, String, RPCRequest) and createScreen(String, String[]) instead.

Components in the screen will default to having Canvas.setAutoDraw(Boolean) set to false. This may be overridden by setting the RPCRequest.setSuppressAutoDraw(Boolean) attribute explicitly to false on the request properties object.

You can optionally provide a locale name to use when resolving any i18n tags in the screen's component XML. If you do not supply this, the locale will be derived from the servlet API, and so will generally be a locale appropriate to the client's operating system settings. Only provide a locale manually if you have a special requirement that requires the user's operating system locale to be overridden in your application. If you provide a locale name, it should be of the form "xx" or "xx_YY", where "xx" is a valid language code and "YY" is a valid country code. For example, "fr" or "en_GB".

This API assumes the ScreenLoaderServlet is installed at the default location - to use a different location, use the requestProperties parameter to specify a different URL via +link{rpcRequest.actionURL}. The requestProperties parameter can also be used to pass additional params to a custom ScreenLoaderServlet - see the "Dynamic Component XML" section of the Component XML overview.

Parameters:

screenName - name of the screen to load

callback - callback for notification of screen being loaded

globals - widgets to allow to take their global IDs

locale - the name of a locale to use for resolving i18n tags in the component XML of the screen

requestProperties - optional properties for the request

setAllowIE9Leak

public static void setAllowIE9Leak(boolean allowLeak)

In Internet Explorer 9, when a string of JavaScript is evaluated via the native eval() function, objects created within that evaluation are not released from browser memory until the page is reloaded.

SmartGWT uses the eval() function to evaluate JSON formatted responses to RPCRequests by default, making long running applications potentially susceptible to memory leaks over time.

Setting this property to false enables a workaround suggested on the Microsoft Knowledge Base to avoid such memory leaks by evaluating script in a hidden iframe and periodically refresh that frame. However developers should be aware of the following limitation with this setting: attempting to access certain object types including Date or function objects generated from such an evaluation can subsequently lead to a JavaScript error with the message "Can't execute code from a freed script".

This workaround therefore may not be suitable for all transactions or dataSources within a given application.

This property may also be specified for specific +link{RPCRequest.allowIE9Leak,RPCRequests}.

Note: This issue is discussed further in the online SmartGWT FAQ.

cacheScreens

public static void cacheScreens(java.lang.String[] screens,
                Function callback)

Loads the definitions of a set of screens saved in Component XML format, using the ScreenLoaderServlet.

Unlike loadScreen(String, LoadScreenCallback, String[]), cacheScreens() does not cause any UI components to be created or drawn, it just loads the definitions of the screens. This allows a subsequent, synchronous call to createScreen(String, String[]) to create the actual screen, or allows a +link{ScreenLoader} to be used which will likewise synchronously create the screen rather than contacting the ScreenLoader servlet and showing a loading message.

See loadScreen(String, LoadScreenCallback, String[]) for the meaning of the locale parameter.

Calling cacheScreens twice with the same screenName will re-load the definition of that screen from the server such that subsequent calls to createScreen() will use the new definition.

Parameters:

screenName - name of the screens to cache

callback - callback for notification of screens being successfully cached

cacheScreens

public static void cacheScreens(java.lang.String[] screens,
                Function callback,
                java.lang.String locale)

Loads the definitions of a set of screens saved in Component XML format, using the ScreenLoaderServlet.

Unlike loadScreen(String, LoadScreenCallback, String[]), cacheScreens() does not cause any UI components to be created or drawn, it just loads the definitions of the screens. This allows a subsequent, synchronous call to createScreen(String, String[]) to create the actual screen, or allows a +link{ScreenLoader} to be used which will likewise synchronously create the screen rather than contacting the ScreenLoader servlet and showing a loading message.

See loadScreen(String, LoadScreenCallback, String[]) for the meaning of the locale parameter.

Calling cacheScreens twice with the same screenName will re-load the definition of that screen from the server such that subsequent calls to createScreen() will use the new definition.

Parameters:

screenName - name of the screens to cache

callback - callback for notification of screens being successfully cached

locale - The name of a locale to use for resolving i18n tags in the component XML of the screen

cacheScreens

public static void cacheScreens(java.lang.String[] screens,
                Function callback,
                java.lang.String locale,
                RPCRequest requestProperties)

Loads the definitions of a set of screens saved in Component XML format, using the ScreenLoaderServlet.

Unlike loadScreen(String, LoadScreenCallback, String[]), cacheScreens() does not cause any UI components to be created or drawn, it just loads the definitions of the screens. This allows a subsequent, synchronous call to createScreen(String, String[]) to create the actual screen, or allows a +link{ScreenLoader} to be used which will likewise synchronously create the screen rather than contacting the ScreenLoader servlet and showing a loading message.

See loadScreen(String, LoadScreenCallback, String[]) for the meaning of the locale parameter.

Calling cacheScreens twice with the same screenName will re-load the definition of that screen from the server such that subsequent calls to createScreen() will use the new definition.

Parameters:

screenName - name of the screens to cache

callback - callback for notification of screens being successfully cached

locale - The name of a locale to use for resolving i18n tags in the component XML of the screen

requestProperties - properties for the request

createScreen

public static Canvas createScreen(java.lang.String screenName)

Creates a screen previously cached by a call to cacheScreens(String[], Function, String, RPCRequest).

As with loadScreen(String, LoadScreenCallback, String[]), the default behavior is to prevent any global widget IDs from being established, the returned Canvas will be the outermost component of the screen, and that Canvas will provide access to other widgets in the screen via Canvas.getByLocalId(String)

Alternatively, as with loadScreen(String, LoadScreenCallback, String[]), a list of IDs that should be allowed to become globals can be passed, allowing those widgets to be retrieved via a call to Canvas.getById(String) after the screen has been created.

If you do not pass globals and avoid depending on global IDs within the screen definition itself (for example, by embedding JavaScript event handlers in the screen definition that use global IDs), you can create the same screen multiple times.

Parameters:

screenName - name of the screen to create

Returns:

last top-level widget in the screen definition

createScreen

public static Canvas createScreen(java.lang.String screenName,
                  java.lang.String[] globals)

Creates a screen previously cached by a call to cacheScreens(String[], Function, String, RPCRequest).

As with loadScreen(String, LoadScreenCallback, String[]), the default behavior is to prevent any global widget IDs from being established, the returned Canvas will be the outermost component of the screen, and that Canvas will provide access to other widgets in the screen via Canvas.getByLocalId(String)

Alternatively, as with loadScreen(String, LoadScreenCallback, String[]), a list of IDs that should be allowed to become globals can be passed, allowing those widgets to be retrieved via a call to Canvas.getById(String) after the screen has been created.

If you do not pass globals and avoid depending on global IDs within the screen definition itself (for example, by embedding JavaScript event handlers in the screen definition that use global IDs), you can create the same screen multiple times.

Parameters:

screenName - name of the screen to create

globals - widgets to allow to take their global IDs

Returns:

last top-level widget in the screen definition

exportContent

public static void exportContent(Canvas canvas)

Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).

For DrawPane and subclasses (e.g. FacetChart) to export properly, the canvas parameter must be the widget itself, not the HTML obtained with getPrintHTML() unless the PrintProperties passed to getPrintHTML() had printForExport:true.

You can use a custom skin when exporting your HTML content. To use a custom skin, add a line to server.properties:

    skin.{skinName}.location: custom/skin
  

Where {skinName} is the name of your custom skin, and the value is the path to your skin resources from the application webroot.

Requires the Smart GWT server framework, but does not require use of server-based databinding - no .ds.xml files need to exist.

See server-side docs for com.isomorphic.contentexport.PdfExport for more details on server-side processing and code samples for redirecting PDF output to a file or in-memory buffer, as well as instructions for adding additional stylesheets.

Parameters:

canvas - Canvas that has exportable widgets

exportContent

public static void exportContent(Canvas[] components)

Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).

For DrawPane and subclasses (e.g. FacetChart) to export properly, the canvas parameter must be the widget itself, not the HTML obtained with getPrintHTML() unless the PrintProperties passed to getPrintHTML() had printForExport:true.

You can use a custom skin when exporting your HTML content. To use a custom skin, add a line to server.properties:

    skin.{skinName}.location: custom/skin
  

Where {skinName} is the name of your custom skin, and the value is the path to your skin resources from the application webroot.

Requires the Smart GWT server framework, but does not require use of server-based databinding - no .ds.xml files need to exist.

See server-side docs for com.isomorphic.contentexport.PdfExport for more details on server-side processing and code samples for redirecting PDF output to a file or in-memory buffer, as well as instructions for adding additional stylesheets.

Parameters:

components - Array of canvases that have exportable widgets.

exportContent

public static void exportContent(java.lang.String htmlFragment)

Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).

For DrawPane and subclasses (e.g. FacetChart) to export properly, the canvas parameter must be the widget itself, not the HTML obtained with getPrintHTML() unless the PrintProperties passed to getPrintHTML() had printForExport:true.

You can use a custom skin when exporting your HTML content. To use a custom skin, add a line to server.properties:

    skin.{skinName}.location: custom/skin
  

Where {skinName} is the name of your custom skin, and the value is the path to your skin resources from the application webroot.

Requires the Smart GWT server framework, but does not require use of server-based databinding - no .ds.xml files need to exist.

See server-side docs for com.isomorphic.contentexport.PdfExport for more details on server-side processing and code samples for redirecting PDF output to a file or in-memory buffer, as well as instructions for adding additional stylesheets.

Parameters:

htmlFragment - HTML fragment derived from getPrintHTML(). See HTMLString.

exportContent

public static void exportContent(Canvas canvas,
                 DSRequest requestProperties)

Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).

For DrawPane and subclasses (e.g. FacetChart) to export properly, the canvas parameter must be the widget itself, not the HTML obtained with getPrintHTML() unless the PrintProperties passed to getPrintHTML() had printForExport:true.

You can use a custom skin when exporting your HTML content. To use a custom skin, add a line to server.properties:

    skin.{skinName}.location: custom/skin
  

Where {skinName} is the name of your custom skin, and the value is the path to your skin resources from the application webroot.

Requires the Smart GWT server framework, but does not require use of server-based databinding - no .ds.xml files need to exist.

See server-side docs for com.isomorphic.contentexport.PdfExport for more details on server-side processing and code samples for redirecting PDF output to a file or in-memory buffer, as well as instructions for adding additional stylesheets.

Parameters:

canvas - Canvas that has exportable widgets

requestProperties - Request properties for the export to pdf object

exportContent

public static void exportContent(Canvas[] components,
                 DSRequest requestProperties)

Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).

For DrawPane and subclasses (e.g. FacetChart) to export properly, the canvas parameter must be the widget itself, not the HTML obtained with getPrintHTML() unless the PrintProperties passed to getPrintHTML() had printForExport:true.

You can use a custom skin when exporting your HTML content. To use a custom skin, add a line to server.properties:

    skin.{skinName}.location: custom/skin
  

Where {skinName} is the name of your custom skin, and the value is the path to your skin resources from the application webroot.

Requires the Smart GWT server framework, but does not require use of server-based databinding - no .ds.xml files need to exist.

See server-side docs for com.isomorphic.contentexport.PdfExport for more details on server-side processing and code samples for redirecting PDF output to a file or in-memory buffer, as well as instructions for adding additional stylesheets.

Parameters:

components - Array of canvases that have exportable widgets.

requestProperties - Request properties for the export to pdf object

exportContent

public static void exportContent(java.lang.String htmlFragment,
                 DSRequest requestProperties)

Converts printable HTML generated from live UI components into a .pdf and downloads it ("Save As.." dialog).

For DrawPane and subclasses (e.g. FacetChart) to export properly, the canvas parameter must be the widget itself, not the HTML obtained with getPrintHTML() unless the PrintProperties passed to getPrintHTML() had printForExport:true.

You can use a custom skin when exporting your HTML content. To use a custom skin, add a line to server.properties:

    skin.{skinName}.location: custom/skin
  

Where {skinName} is the name of your custom skin, and the value is the path to your skin resources from the application webroot.

Requires the Smart GWT server framework, but does not require use of server-based databinding - no .ds.xml files need to exist.

See server-side docs for com.isomorphic.contentexport.PdfExport for more details on server-side processing and code samples for redirecting PDF output to a file or in-memory buffer, as well as instructions for adding additional stylesheets.

Parameters:

htmlFragment - HTML fragment derived from getPrintHTML(). See HTMLString.

requestProperties - Request properties for the export to pdf object

exportImage

public static void exportImage(java.lang.String svgString)

exportImage

public static void exportImage(java.lang.String svgString,
               DSRequest requestProperties)

exportImage

public static void exportImage(java.lang.String svgString,
               DSRequest requestProperties,
               ExportImageCallback callback)

Converts an SVG string to one of several possible image formats, and can either initiate a download or return the base64-encoded image data. Control the image format via DSRequest.exportImageFormat.

Default is to download the image (triggering the browser's save dialog). DSRequest.exportFilename can be used to control the default filename provided in the save dialog.

To instead return the data as a normal DSResponse, set exportDisplay of requestProperties to ExportDisplay.RETURN. In this case the data is always base64 encoded.

Requires the SmartClient server framework, with the same set of required .jars as are required for PDF export of charts in legacy IE.

See also DrawPane.getSvgString() and DrawPane.getDataURL().

Parameters:

svgString - XML string containing SVG data

requestProperties - request properties controlling options for export

callback - optional callback when using exportDisplay:"return". Does not fire for other exportDisplay modes.