Package com.smartgwt.client.rpc

# Class RPCManager

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

public class RPCManager extends 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
  Description
  `static final String`
  `ALL_GLOBALS`
  ALL_GLOBALS constant used by the `loadScreen(String, LoadScreenCallback, String[])` API.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RPCManager()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Integer`
  `addProcessingCompleteCallback(String callback)`
  This method will register a callback to fire every time the processing of an RPC transaction is fully complete, including any `request-level` or `queue-level` user callbacks.
  `static void`
  `cacheScreens(String screenName)`
  Loads the definitions of a set of screens saved in `Component XML` format, using the `ScreenLoaderServlet`.
  `static void`
  `cacheScreens(String... screenName)`
  Loads the definitions of a set of screens saved in `Component XML` format, using the `ScreenLoaderServlet`.
  `static void`
  `cacheScreens(String[] screenName, Function callback)`
  See `cacheScreens()`
  `static void`
  `cacheScreens(String[] screenName, Function callback, String locale)`
  See `cacheScreens()`
  `static void`
  `cacheScreens(String[] screenName, Function callback, String locale, RPCRequest requestProperties)`
  Loads the definitions of a set of screens saved in `Component XML` format, using the `ScreenLoaderServlet`.
  `static void`
  `cacheScreens(String screenName, Function callback)`
  See `cacheScreens()`
  `static void`
  `cacheScreens(String screenName, Function callback, String locale)`
  See `cacheScreens()`
  `static void`
  `cacheScreens(String screenName, Function callback, String locale, RPCRequest requestProperties)`
  Loads the definitions of a set of screens saved in `Component XML` format, using the `ScreenLoaderServlet`.
  `static void`
  `cancelDefaultErrorHandling()`
  Cancels default error handling for all `DSResponse`s in the current transaction, ensuring that the default error handling or current `error handler` is not called for any of them.
  `static void`
  `cancelQueue()`
  Cancel a queue of requests (also called a transaction).
  `static void`
  `cancelQueue(int transactionNum)`
  Cancel a queue of requests (also called a transaction).
  `static void`
  `cancelQueue(String transactionNum)`
  Deprecated.
  please use int methods when dealing with transaction number.
  `static void`
  `clearTransaction(int transactionNum)`
  Erase all client-side record of a transaction, such that any response from the server will be ignored.
  `static void`
  `clearTransaction(String transactionNum)`
  Deprecated.
  please use int methods when dealing with transaction number.
  `static Canvas`
  `createScreen(String screenName)`
  Creates a screen previously cached by a call to `cacheScreens()`.
  `static Canvas`
  `createScreen(String screenName, CreateScreenSettings settings)`
  Creates a screen previously cached by a call to `cacheScreens()`.
  `static Canvas`
  `createScreen(String screenName, String[] globals)`
  See `createScreen(String,com.smartgwt.client.rpc.CreateScreenSettings)`.
  `static void`
  `customizeTransforms(RequestTransformer requestTransformer)`
  Apply the specified `RequestTransformer` to override the default behavior of `transformRequest(RPCRequest)`.
  `static void`
  `exportContent(Canvas canvas)`
  Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).
  `static void`
  `exportContent(Canvas... canvas)`
  Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).
  `static void`
  `exportContent(Canvas[] canvas, DSRequest requestProperties)`
  Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).
  `static void`
  `exportContent(Canvas canvas, DSRequest requestProperties)`
  Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).
  `static void`
  `exportContent(String canvas)`
  Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).
  `static void`
  `exportContent(String canvas, DSRequest requestProperties)`
  Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).
  `static void`
  `exportImage(String svgString)`
  `static void`
  `exportImage(String svgString, DSRequest requestProperties)`
  `static void`
  `exportImage(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 String`
  `getActionURL()`
  Specifies the default URL for RPCRequests and DSRequests that do not specify a URL.
  `static String`
  `getCredentialsURL()`
  Specifies URL where credentials should be submitted to attempt relogin when session timeout is encountered during a background RPC.
  `static String`
  `getCurrentTransactionId()`
  Deprecated.
  please use int methods when dealing with transaction number.
  `static int`
  `getCurrentTransactionIdAsInt()`
  Same as getQueueTransactionId() but returns `-1` instead of `null` if there's no currently queued requests.
  `static String`
  `getFormattedTimingData(Integer transactionNum)`
  Returns formatted text visualising the tree of timing data available from the `getTimingData()` API.
  `static String`
  `getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback)`
  See `getFormattedTimingData()`
  `static String`
  `getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback, Integer operationNo)`
  See `getFormattedTimingData()`
  `static String`
  `getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback, Integer operationNo, boolean includeClient)`
  See `getFormattedTimingData()`
  `static String`
  `getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback, Integer operationNo, boolean includeClient, boolean includeServer)`
  See `getFormattedTimingData()`
  `static String`
  `getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback, Integer operationNo, boolean includeClient, boolean includeServer, Integer maxDepth)`
  Returns formatted text visualising the tree of timing data available from the `getTimingData()` API.
  `static String`
  `getLoadProjectErrorMessage(RPCResponse rpcResponse)`
  Convenience method that returns a message describing the error for a failed call to `loadProject()`.
  `static String`
  `getLoadProjectErrorStatus(RPCResponse rpcResponse)`
  Convenience method that returns the error status for a failed call to `loadProject()`.
  `static String`
  `getLoginRequiredMarker()`
  Marker the system will look for in XHTP responses in order to detect when login is required.
  `static String`
  `getLoginStatusCodeMarker()`
  String sequence which marks the response as a one which contains login status information.
  `static String`
  `getLoginSuccessMarker()`
  Marker the system will look for in order to detect when login was successful.
  `static void`
  `getMaxLoginAttemptsExceededMarker()`
  Get the marker the system will look for in order to detect when the number of maximum logins was exceeded.
  `static Integer`
  `getQueueTransactionId()`
  Returns the id of the current transaction (a queue of requests).
  `static Map`
  `getTimingData(Integer transactionNum)`
  Returns timing data gathered for the transaction number passed in.
  `static Map`
  `getTimingData(Integer transactionNum, TimingDataCallback callback)`
  See `getTimingData()`
  `static Map`
  `getTimingData(Integer transactionNum, TimingDataCallback callback, Integer operationNo)`
  See `getTimingData()`
  `static Map`
  `getTimingData(Integer transactionNum, TimingDataCallback callback, Integer operationNo, boolean includeClient)`
  See `getTimingData()`
  `static Map`
  `getTimingData(Integer transactionNum, TimingDataCallback callback, Integer operationNo, boolean includeClient, boolean includeServer)`
  Returns timing data gathered for the transaction number passed in.
  `static String`
  `getTransactionDescription(Integer transactionNum)`
  Returns a brief description of the transaction in the following format for logging purposes: `"Transaction with n operation(s).`
  `static Boolean`
  `hasCurrentTransactionQueued()`
  Returns true if there is a current transaction (queue of requests)
  `static void`
  `isScreenCached(String screenName)`
  Returns true if a screen with the given name has already been cached by a call to `cacheScreens()` or similar (e.g.
  `static void`
  `loadProject(String projectNames, LoadProjectCallback callback, LoadProjectSettings settings)`
  Loads projects using the `ProjectLoaderServlet`, reachable at `projectLoaderURL`, and fires the given callback after the project has been cached.
  `static void`
  `loadScreen(String screenName, LoadScreenCallback callback)`
  Loads a screen saved in `Component XML` format.
  `static void`
  `loadScreen(String screenName, LoadScreenCallback callback, LoadScreenSettings settings, String locale)`
  See `loadScreen(java.lang.String,com.smartgwt.client.rpc.LoadScreenCallback,java.lang.String[],java.lang.String,com.smartgwt.client.rpc.RPCRequest)`.
  `static void`
  `loadScreen(String screenName, LoadScreenCallback callback, String[] globals)`
  Loads a screen saved in `Component XML` format.
  `static void`
  `loadScreen(String screenName, LoadScreenCallback callback, String[] globals, RPCRequest requestProperties)`
  Loads a screen saved in `Component XML` format.
  `static void`
  `loadScreen(String screenName, LoadScreenCallback callback, String[] globals, String locale, RPCRequest requestProperties)`
  Loads a screen saved in `Component XML` format, using the `ScreenLoaderServlet`.
  `static void`
  `removeProcessingCompleteCallback(Integer index)`
  Unregister the `processingComplete` callback associated with the parameter index
  `static Boolean`
  `requestsArePending()`
  Returns whether there are any pending RPC requests.
  `static void`
  `resendTransaction()`
  Resend a suspended transaction to the server.
  `static void`
  `resendTransaction(int transactionNum)`
  Resend a suspended transaction to the server.
  `static void`
  `resendTransaction(String transactionNum)`
  Deprecated.
  please use int methods when dealing with transaction number.
  `static void`
  `runDefaultErrorHandling(DSResponse response, DSRequest request)`
  Runs the default error handling normally performed by `HandleErrorCallback.handleError()`.
  `static void`
  `send(JavaScriptObject data, RPCCallback callback, RPCRequest requestParams)`
  This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().
  `static void`
  `send(JavaScriptObject data, RPCCallback callback, Map requestParams)`
  This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().
  `static void`
  `send(String data, RPCCallback callback, RPCRequest requestParams)`
  This method is a convenience wrapper on RPCManager.sendRequest() - it calls through to sendRequest().
  `static void`
  `send(String data, RPCCallback callback, Map 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(String actionURL)`
  Setter for `actionURL`.
  `static void`
  `setAllowCrossDomainCalls(Boolean allowCrossDomainCalls)`
  By default Smart GWT 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(String credentialsURL)`
  Specifies URL where credentials should be submitted to attempt relogin when session timeout is encountered during a background RPC.
  `static void`
  `setDefaultPrompt(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(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 `RPCResponse.status` is negative and `RPCRequest.willHandleError` was not set.
  `static void`
  `setHandleTransportErrorCallback(HandleTransportErrorCallback callback)`
  Sets callback to handle server error responses for submitted transactions.
  `static void`
  `setLoginRequiredCallback(LoginRequiredCallback callback)`
  Called when a session timeout is encountered while trying to do a background RPC.
  `static void`
  `setLoginRequiredMarker(String loginRequiredMarker)`
  Marker the system will look for in XHTP responses in order to detect when login is required.
  `static void`
  `setLoginStatusCodeMarker(String loginStatusCodeMarker)`
  String sequence which marks the response as a one which contains login status information.
  `static void`
  `setLoginSuccessMarker(String loginSuccessMarker)`
  Marker the system will look for in order to detect when login was successful.
  `static String`
  `setMaxLoginAttemptsExceededMarker(String maxLoginAttemptsExceededMarker)`
  Set the marker the system will look for in order to detect when the number of maximum logins was exceeded.
  `static void`
  `setPromptCursor(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 are not using queuing, the system simply sends queues containing just one request, so this API is valid regardless).
  `static void`
  `setRemoveDataPrompt(String removeDataPrompt)`
  Default prompt displayed to user while an operation is running to remove data from the server.
  `static void`
  `setSaveDataPrompt(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(String timeoutErrorMessage)`
  Default message displayed to user when an operation fails to return from the server within the timeout period specified by `defaultTimeout`.
  `static void`
  `setTimingDataEnabled(boolean enabled)`
  Pass `true` or `false` to switch the gathering of timing metrics on and off programmatically.
  `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(Boolean useHttpProxy)`
  Whether the `HttpProxyServlet` should be used in order to get around the "same origin policy" that prevents web pages from contacting other sites.
  `static boolean`
  `startQueue()`
  Start queuing `DSRequests` and `RPCRequests` system-wide, for later sending when RPCManager.sendQueue() is called, at which time all queued requests will be sent as a single, combined HTTP request.
  `static boolean`
  `startQueue(boolean shouldQueue)`
  Start queuing `DSRequests` and `RPCRequests` system-wide, for later sending when RPCManager.sendQueue() is called, at which time all queued requests will be sent as a single, combined HTTP request.
  `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(int 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 void`
  `suspendTransaction(String transactionID)`
  Deprecated.
  please use int methods when dealing with transaction number.
  `static Object`
  `transformRequest(RPCRequest rpcRequest)`
  Returns the data that should be sent to the `actionURL`.
  `static 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 Details

  - ### ALL_GLOBALS

    public static final String ALL_GLOBALS
    ALL_GLOBALS constant used by the `loadScreen(String, LoadScreenCallback, String[])` API.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### RPCManager

    public RPCManager()

- ## Method Details

  - ### getActionURL

    public static String getActionURL()
    Specifies the default URL for RPCRequests and DSRequests that do not specify a URL.

    URLs can be set on a per-request basis via `RPCRequest.actionURL`, or on a per-DataSource or per-operationType basis via `DataSource.dataURL` and `OperationBinding.dataURL` respectively. However, note that in order to be able to make use of `queuing`, you should have all data loading and saving requests go to a single URL unless you are forced to use distinct URLs by legacy services.

    The primary use case for setting the default `actionURL` is to add a CSRF / XSRF (Cross-site Request Forgery) token. Assuming you are using a single URL for all data requests as covered above, adding a CSRF token to the default `actionURL` as a simple HTTP parameter will cause the CSRF token to be included in all RPCRequests and DSRequests from all DataSources without further effort.

    If the `actionURL` is changed while transactions are suspended, any suspended transactions whose `actionURL` was defaulted to this property (e.g. because `RPCRequest.actionURL` wasn't set) will be updated to have the new `actionURL`.

    Returns:
      current value of actionURL

  - ### setAllowCrossDomainCalls

    public static void setAllowCrossDomainCalls(Boolean allowCrossDomainCalls)
    By default Smart GWT 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 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 Smart GWT warning when such calls occur.

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

    Parameters:
      `allowCrossDomainCalls` - new allowCrossDomainCalls. Default value is false.

  - ### setCredentialsURL

    public static void setCredentialsURL(String credentialsURL)
    Specifies URL where credentials should be submitted to attempt relogin when session timeout is encountered during a background RPC. See `Relogin`
    Parameters:
      `credentialsURL` - new credentialsURL. Default value is http://localhost:8080/isomorphic/login/loginSuccessMarker.html.

  - ### getCredentialsURL

    public static String getCredentialsURL()
    Specifies URL where credentials should be submitted to attempt relogin when session timeout is encountered during a background RPC. See `Relogin`
    Returns:
      current value of credentialsURL

  - ### setLoginRequiredMarker

    public static void setLoginRequiredMarker(String loginRequiredMarker)
    Marker the system will look for in XHTP responses in order to detect when login is required. The default loginRequiredMarker is the following string:
    `"<SCRIPT>//'\"]]>>isc_loginRequired"`

    As described in `Relogin`, if this snippet is encountered in the response to a Smart GWT RPC request (with standard transport `"xmlHttpRequest"`), the RPCManager will suspend the current transaction and fire the `loginRequired()` notification.

    The default loginRequired marker should generally not be customized. It is designed to be safe to insert into any HTML page or other server response without affecting display or functionality, for example, within an HTML comment. You should *only* customize the `loginRequiredMarker` if you have absolutely no ability to change the response that the server will send when login is required.

    If you do customize the `loginRequiredMarker`, then the loginRequiredMarker, `loginSuccessMarker` and `maxLoginAttemptsExceededMarker` should all start with the `loginStatusCodeMarker`. If they do not, there will be a small impact on performance as every response must be separately scanned for each marker, instead of just scanning once for the `loginStatusCodeMarker`.

    In addition, the `loginStatusCodeMarker` should ideally contain text that could not possibly validly appear as a data value in a normal response, since if that were possible, end users could enter the loginRequiredMarker as a data value and cause Smart GWT to falsely detect session timeout when handling an ordinary data response. This is why the default marker has characters that make it impossible for it to be validly interpreted as a JavaScript String, XML document or HTML content - there is no way that an end user could enter this as a data value in an application and have it appear verbatim in a server response.

    Parameters:
      `loginRequiredMarker` - new loginRequiredMarker. Default value is <SCRIPT>//'\"]]>>isc_loginRequired.

  - ### getLoginRequiredMarker

    public static String getLoginRequiredMarker()
    Marker the system will look for in XHTP responses in order to detect when login is required. The default loginRequiredMarker is the following string:
    `"<SCRIPT>//'\"]]>>isc_loginRequired"`

    As described in `Relogin`, if this snippet is encountered in the response to a Smart GWT RPC request (with standard transport `"xmlHttpRequest"`), the RPCManager will suspend the current transaction and fire the `loginRequired()` notification.

    The default loginRequired marker should generally not be customized. It is designed to be safe to insert into any HTML page or other server response without affecting display or functionality, for example, within an HTML comment. You should *only* customize the `loginRequiredMarker` if you have absolutely no ability to change the response that the server will send when login is required.

    If you do customize the `loginRequiredMarker`, then the loginRequiredMarker, `loginSuccessMarker` and `maxLoginAttemptsExceededMarker` should all start with the `loginStatusCodeMarker`. If they do not, there will be a small impact on performance as every response must be separately scanned for each marker, instead of just scanning once for the `loginStatusCodeMarker`.

    In addition, the `loginStatusCodeMarker` should ideally contain text that could not possibly validly appear as a data value in a normal response, since if that were possible, end users could enter the loginRequiredMarker as a data value and cause Smart GWT to falsely detect session timeout when handling an ordinary data response. This is why the default marker has characters that make it impossible for it to be validly interpreted as a JavaScript String, XML document or HTML content - there is no way that an end user could enter this as a data value in an application and have it appear verbatim in a server response.

    Returns:
      current value of loginRequiredMarker

  - ### setLoginStatusCodeMarker

    public static void setLoginStatusCodeMarker(String loginStatusCodeMarker)
    String sequence which marks the response as a one which contains login status information.

    The default loginStatusCodeMarker is the following string: `"<SCRIPT>//'\"]]>>isc_"`

    Parameters:
      `loginStatusCodeMarker` - new loginStatusCodeMarker. Default value is <SCRIPT>//'\"]]>>isc_.

  - ### getLoginStatusCodeMarker

    public static String getLoginStatusCodeMarker()
    String sequence which marks the response as a one which contains login status information.

    The default loginStatusCodeMarker is the following string: `"<SCRIPT>//'\"]]>>isc_"`

    Returns:
      current value of loginStatusCodeMarker

  - ### setLoginSuccessMarker

    public static void setLoginSuccessMarker(String loginSuccessMarker)
    Marker the system will look for in order to detect when login was successful.

    The default loginSuccessMarker is the following string:
    `"<SCRIPT>//'\"]]>>isc_loginSuccess"`

    Parameters:
      `loginSuccessMarker` - new loginSuccessMarker. Default value is <SCRIPT>//'\"]]>>isc_loginSuccess.

  - ### getLoginSuccessMarker

    public static String getLoginSuccessMarker()
    Marker the system will look for in order to detect when login was successful.

    The default loginSuccessMarker is the following string:
    `"<SCRIPT>//'\"]]>>isc_loginSuccess"`

    Returns:
      current value of loginSuccessMarker

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

    DataSource requests, which are a particular type of RPCRequest, are controlled by the more-specific DataSource-level setting `DataSource.showPrompt`.

    Parameters:
      `showPrompt` - new showPrompt. Default value is RPCManager.showPrompt.

  - ### setTimeoutErrorMessage

    public static void setTimeoutErrorMessage(String timeoutErrorMessage)
    Default message displayed to user when an operation fails to return from the server within the timeout period specified by `defaultTimeout`.
    Parameters:
      `timeoutErrorMessage` - new timeoutErrorMessage. Default value is "Operation timed out".

  - ### setUseHttpProxy

    public static void setUseHttpProxy(Boolean useHttpProxy)
    Whether the `HttpProxyServlet` should be used in order to get around the "same origin policy" that prevents web pages from contacting other sites.

    Default behavior is to use the HttpProxyServlet whenever a URL appears to be pointing to another site. Set `RPCRequest.useHttpProxy` false to have a particular request avoid using the HttpProxyServlet even when it appears to be necessary, or set `RPCManager.useHttpProxy` to false to avoid ever attempting to use the HttpProxyServlet.

    Parameters:
      `useHttpProxy` - new useHttpProxy. Default value is true.

  - ### addProcessingCompleteCallback

    public static Integer addProcessingCompleteCallback(String callback)
    This method will register a callback to fire every time the processing of an RPC transaction is fully complete, including any `request-level` or `queue-level` user callbacks.
    Parameters:
      `callback` - Callback to fire when processing is complete. This takes a single parameter "transactionNum". See `Callback`
    Returns:
      Identifier for the registered callback. May be passed to `removeProcessingCompleteCallback()` to unregister this callback.
    See Also:
      - `removeProcessingCompleteCallback(java.lang.Integer)`
      - `getTimingData(java.lang.Integer)`
      - `Callback`

  - ### cacheScreens

    public static void cacheScreens(String screenName)
    Loads the definitions of a set of screens saved in `Component XML` format, using the `ScreenLoaderServlet`.

    Unlike `loadScreen()`, `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()` to create the actual screen, rather than contacting the `ScreenLoader` servlet and showing a loading message.

    If you're using `Reify`, and the screens are part of a `Project`, you should use `Reify.loadProject()` to cache the screens instead of this method. See help topic `Reify For Developers` for an overview of how you can integrate Reify into your development process.

    See `loadScreen()` 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
    See Also:
      - `Project`

  - ### cacheScreens

    public static void cacheScreens(String... screenName)
    Loads the definitions of a set of screens saved in `Component XML` format, using the `ScreenLoaderServlet`.

    Unlike `loadScreen()`, `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()` to create the actual screen, rather than contacting the `ScreenLoader` servlet and showing a loading message.

    If you're using `Reify`, and the screens are part of a `Project`, you should use `Reify.loadProject()` to cache the screens instead of this method. See help topic `Reify For Developers` for an overview of how you can integrate Reify into your development process.

    See `loadScreen()` 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
    See Also:
      - `Project`

  - ### cacheScreens

    public static void cacheScreens(String screenName, Function callback)
    See `cacheScreens()`

  - ### cacheScreens

    public static void cacheScreens(String[] screenName, Function callback)
    See `cacheScreens()`

  - ### cacheScreens

    public static void cacheScreens(String screenName, Function callback, String locale)
    See `cacheScreens()`

  - ### cacheScreens

    public static void cacheScreens(String[] screenName, Function callback, String locale)
    See `cacheScreens()`

  - ### cacheScreens

    public static void cacheScreens(String screenName, Function callback, String locale, RPCRequest requestProperties)
    Loads the definitions of a set of screens saved in `Component XML` format, using the `ScreenLoaderServlet`.

    Unlike `loadScreen()`, `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()` to create the actual screen, rather than contacting the `ScreenLoader` servlet and showing a loading message.

    If you're using `Reify`, and the screens are part of a `Project`, you should use `Reify.loadProject()` to cache the screens instead of this method. See help topic `Reify For Developers` for an overview of how you can integrate Reify into your development process.

    See `loadScreen()` 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` - optional properties for the request
    See Also:
      - `Project`

  - ### cacheScreens

    public static void cacheScreens(String[] screenName, Function callback, String locale, RPCRequest requestProperties)
    Loads the definitions of a set of screens saved in `Component XML` format, using the `ScreenLoaderServlet`.

    Unlike `loadScreen()`, `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()` to create the actual screen, rather than contacting the `ScreenLoader` servlet and showing a loading message.

    If you're using `Reify`, and the screens are part of a `Project`, you should use `Reify.loadProject()` to cache the screens instead of this method. See help topic `Reify For Developers` for an overview of how you can integrate Reify into your development process.

    See `loadScreen()` 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` - optional properties for the request
    See Also:
      - `Project`

  - ### 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 `getQueueTransactionId()` 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.

    Also, take into account that this method removes all queued requests from the current queue, but queueing is still active, so if you also want to disable queuing you should call `startQueue(false)`.

  - ### cancelQueue

    public static void cancelQueue(int 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 `getQueueTransactionId()` 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.

    Also, take into account that this method removes all queued requests from the current queue, but queueing is still active, so if you also want to disable queuing you should call `startQueue(false)`.

    Parameters:
      `transactionNum` - transactionId of the queue.

  - ### clearTransaction

    public static void clearTransaction(int 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()`.

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

    Parameters:
      `transactionNum` - id of the transaction to be cleared

  - ### createScreen

    public static Canvas createScreen(String screenName)
    Creates a screen previously cached by a call to `cacheScreens()`. (Compare with `Project.createScreen()` for `Reify` projects.)

    As with `loadScreen()`, 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 `getByLocalId()`

    Alternatively, as with `loadScreen()`, 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()` 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.

    Creating a screen may or may not cause it to draw, depending on current global autoDraw setting (`isc.setAutoDraw()`) and any `autoDraw` settings in the screen itself.

    Instead of `globals`, you may instead pass a `substitution configuration` to change what classes are used to construct widgets, or subsitute existing widgets for those to be constructed, by widget ID.

    During creation of screens originating from XML translation, Class.assumeGoodCode is automatically enabled for faster widget initialization.

    Parameters:
      `screenName` - name of the screen to create
    Returns:
      last top-level widget in the screen definition

  - ### createScreen

    public static Canvas createScreen(String screenName, CreateScreenSettings settings)
    Creates a screen previously cached by a call to `cacheScreens()`. (Compare with `Project.createScreen()` for `Reify` projects.)

    As with `loadScreen()`, 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 `getByLocalId()`

    Alternatively, as with `loadScreen()`, 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()` 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.

    Creating a screen may or may not cause it to draw, depending on current global autoDraw setting (`isc.setAutoDraw()`) and any `autoDraw` settings in the screen itself.

    Instead of `globals`, you may instead pass a `substitution configuration` to change what classes are used to construct widgets, or subsitute existing widgets for those to be constructed, by widget ID.

    During creation of screens originating from XML translation, Class.assumeGoodCode is automatically enabled for faster widget initialization.

    Parameters:
      `screenName` - name of the screen to create
      `settings` - widgets to allow to take their global IDs, or a widget remap config
    Returns:
      last top-level widget in the screen definition

  - ### exportContent

    public static void exportContent(Canvas canvas)
    Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).

    As with other exports, the resulting file can be `saved to the server filesystem` instead of, or in addition to being downloaded to the user. 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.

    You can either pass any `Canvas` to `exportContent`, or you can pass HTML that you have retrieved by calling `Canvas.getPrintHTML()`. When calling `getPrintHTML()` to retrieve HTML for use with `exportContent()`, you must pass the `PrintProperties.printForExport` or `DrawPane` and `FacetChart` instances will not export properly.

    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.

    Also, you can set the filename of the export via `DSRequest.exportFilename`. For example:

          DSRequest requestProperties = new DSRequest();
          requestProperties.setAttribute("exportFilename", "export");

    In case you do not provide a filename for your export, the system will assign the default filename "export".

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

    You can also inject a small amount of CSS from the browser via `DSRequest.exportCSS` - this is intended primarily for switching the page size on the fly, for exceptionally wide or tall exports.

    Note: PDF Export Resource Security

    It is possible to send custom HTML to the Smart GWT server that attempts to include resources from the local server filesystem (predominantly images) and export them to PDF. By default, all filesystem access during PDF export is denied — only HTTP and HTTPS resource URLs are permitted.

    To allow specific filesystem paths or restrict which HTTP hosts are permitted, use the `contentExport.allowedResourceLocations` setting in `server.properties`. This is a semicolon-separated list of path segments that identify allowed resource locations. A resource URL is allowed if its full path contains at least one of the listed segments as a substring. Disallowed resources are omitted from the PDF, and a warning is logged.

    The following placeholders are supported in the allowlist patterns:

    - `{webRoot}` – the application's web root directory on the filesystem (from the `webRoot` setting in `server.properties`). Expanded once at server startup. Useful for allowing filesystem paths under the web root.
    - `{app.host}` – the server hostname, expanded per-request from `HttpServletRequest.getServerName()` (typically the value of the incoming HTTP `Host` header, e.g. `myserver.example.com`). In environments with reverse proxies, load balancers, or multi-homed servers, this reflects how the client addressed the server, which may differ from the server's internal hostname. If the proxy does not forward the original `Host` header, or the server is known by multiple DNS names, hardcode the desired hostname directly instead of using this placeholder.
    - `{app.context}` – the webapp context path, expanded per-request from `HttpServletRequest.getContextPath()` (e.g. `/myapp`). This is the webapp's deployment path, set at deploy time and not affected by network topology.
    Examples:
    - `{webRoot};{app.host}` – filesystem access under the web root, plus HTTP/HTTPS to the same server (any port, any path).
    - `http://{app.host}:8080{app.context};https://{app.host}:8443{app.context}` – tighter: specific ports and only under the application context path.
    Important: when this setting is present, it restricts both filesystem and HTTP resources — only URLs matching a listed segment are permitted. Without this setting, all HTTP and HTTPS URLs are permitted and only filesystem access is denied.

    Note that the server cannot reliably determine whether an HTTP URL points to a resource under the web root (due to URL remapping, reverse proxies, etc.), so the allowlist uses a simple substring match against the full URL. When restricting HTTP access, list only the specific hosts and paths needed.

    In ContainerIO mode (WAR deployment where the framework loads resources from the classpath rather than the filesystem), filesystem access from user-provided HTML is always denied regardless of this setting. Internal skin resources (fonts, CSS, images) are loaded from known skin directories and are not affected by this setting in any deployment mode.

    Parameters:
      `canvas` - Canvas or canvas list that has exportable widgets, or an HTML fragment derived from `getPrintHTML()`

  - ### exportContent

    public static void exportContent(Canvas... canvas)
    Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).

    As with other exports, the resulting file can be `saved to the server filesystem` instead of, or in addition to being downloaded to the user. 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.

    You can either pass any `Canvas` to `exportContent`, or you can pass HTML that you have retrieved by calling `Canvas.getPrintHTML()`. When calling `getPrintHTML()` to retrieve HTML for use with `exportContent()`, you must pass the `PrintProperties.printForExport` or `DrawPane` and `FacetChart` instances will not export properly.

    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.

    Also, you can set the filename of the export via `DSRequest.exportFilename`. For example:

          DSRequest requestProperties = new DSRequest();
          requestProperties.setAttribute("exportFilename", "export");

    In case you do not provide a filename for your export, the system will assign the default filename "export".

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

    You can also inject a small amount of CSS from the browser via `DSRequest.exportCSS` - this is intended primarily for switching the page size on the fly, for exceptionally wide or tall exports.

    Note: PDF Export Resource Security

    It is possible to send custom HTML to the Smart GWT server that attempts to include resources from the local server filesystem (predominantly images) and export them to PDF. By default, all filesystem access during PDF export is denied — only HTTP and HTTPS resource URLs are permitted.

    To allow specific filesystem paths or restrict which HTTP hosts are permitted, use the `contentExport.allowedResourceLocations` setting in `server.properties`. This is a semicolon-separated list of path segments that identify allowed resource locations. A resource URL is allowed if its full path contains at least one of the listed segments as a substring. Disallowed resources are omitted from the PDF, and a warning is logged.

    The following placeholders are supported in the allowlist patterns:

    - `{webRoot}` – the application's web root directory on the filesystem (from the `webRoot` setting in `server.properties`). Expanded once at server startup. Useful for allowing filesystem paths under the web root.
    - `{app.host}` – the server hostname, expanded per-request from `HttpServletRequest.getServerName()` (typically the value of the incoming HTTP `Host` header, e.g. `myserver.example.com`). In environments with reverse proxies, load balancers, or multi-homed servers, this reflects how the client addressed the server, which may differ from the server's internal hostname. If the proxy does not forward the original `Host` header, or the server is known by multiple DNS names, hardcode the desired hostname directly instead of using this placeholder.
    - `{app.context}` – the webapp context path, expanded per-request from `HttpServletRequest.getContextPath()` (e.g. `/myapp`). This is the webapp's deployment path, set at deploy time and not affected by network topology.
    Examples:
    - `{webRoot};{app.host}` – filesystem access under the web root, plus HTTP/HTTPS to the same server (any port, any path).
    - `http://{app.host}:8080{app.context};https://{app.host}:8443{app.context}` – tighter: specific ports and only under the application context path.
    Important: when this setting is present, it restricts both filesystem and HTTP resources — only URLs matching a listed segment are permitted. Without this setting, all HTTP and HTTPS URLs are permitted and only filesystem access is denied.

    Note that the server cannot reliably determine whether an HTTP URL points to a resource under the web root (due to URL remapping, reverse proxies, etc.), so the allowlist uses a simple substring match against the full URL. When restricting HTTP access, list only the specific hosts and paths needed.

    In ContainerIO mode (WAR deployment where the framework loads resources from the classpath rather than the filesystem), filesystem access from user-provided HTML is always denied regardless of this setting. Internal skin resources (fonts, CSS, images) are loaded from known skin directories and are not affected by this setting in any deployment mode.

    Parameters:
      `canvas` - Canvas or canvas list that has exportable widgets, or an HTML fragment derived from `getPrintHTML()`

  - ### exportContent

    public static void exportContent(String canvas)
    Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).

    As with other exports, the resulting file can be `saved to the server filesystem` instead of, or in addition to being downloaded to the user. 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.

    You can either pass any `Canvas` to `exportContent`, or you can pass HTML that you have retrieved by calling `Canvas.getPrintHTML()`. When calling `getPrintHTML()` to retrieve HTML for use with `exportContent()`, you must pass the `PrintProperties.printForExport` or `DrawPane` and `FacetChart` instances will not export properly.

    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.

    Also, you can set the filename of the export via `DSRequest.exportFilename`. For example:

          DSRequest requestProperties = new DSRequest();
          requestProperties.setAttribute("exportFilename", "export");

    In case you do not provide a filename for your export, the system will assign the default filename "export".

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

    You can also inject a small amount of CSS from the browser via `DSRequest.exportCSS` - this is intended primarily for switching the page size on the fly, for exceptionally wide or tall exports.

    Note: PDF Export Resource Security

    It is possible to send custom HTML to the Smart GWT server that attempts to include resources from the local server filesystem (predominantly images) and export them to PDF. By default, all filesystem access during PDF export is denied — only HTTP and HTTPS resource URLs are permitted.

    To allow specific filesystem paths or restrict which HTTP hosts are permitted, use the `contentExport.allowedResourceLocations` setting in `server.properties`. This is a semicolon-separated list of path segments that identify allowed resource locations. A resource URL is allowed if its full path contains at least one of the listed segments as a substring. Disallowed resources are omitted from the PDF, and a warning is logged.

    The following placeholders are supported in the allowlist patterns:

    - `{webRoot}` – the application's web root directory on the filesystem (from the `webRoot` setting in `server.properties`). Expanded once at server startup. Useful for allowing filesystem paths under the web root.
    - `{app.host}` – the server hostname, expanded per-request from `HttpServletRequest.getServerName()` (typically the value of the incoming HTTP `Host` header, e.g. `myserver.example.com`). In environments with reverse proxies, load balancers, or multi-homed servers, this reflects how the client addressed the server, which may differ from the server's internal hostname. If the proxy does not forward the original `Host` header, or the server is known by multiple DNS names, hardcode the desired hostname directly instead of using this placeholder.
    - `{app.context}` – the webapp context path, expanded per-request from `HttpServletRequest.getContextPath()` (e.g. `/myapp`). This is the webapp's deployment path, set at deploy time and not affected by network topology.
    Examples:
    - `{webRoot};{app.host}` – filesystem access under the web root, plus HTTP/HTTPS to the same server (any port, any path).
    - `http://{app.host}:8080{app.context};https://{app.host}:8443{app.context}` – tighter: specific ports and only under the application context path.
    Important: when this setting is present, it restricts both filesystem and HTTP resources — only URLs matching a listed segment are permitted. Without this setting, all HTTP and HTTPS URLs are permitted and only filesystem access is denied.

    Note that the server cannot reliably determine whether an HTTP URL points to a resource under the web root (due to URL remapping, reverse proxies, etc.), so the allowlist uses a simple substring match against the full URL. When restricting HTTP access, list only the specific hosts and paths needed.

    In ContainerIO mode (WAR deployment where the framework loads resources from the classpath rather than the filesystem), filesystem access from user-provided HTML is always denied regardless of this setting. Internal skin resources (fonts, CSS, images) are loaded from known skin directories and are not affected by this setting in any deployment mode.

    Parameters:
      `canvas` - Canvas or canvas list that has exportable widgets, or an HTML fragment derived from `getPrintHTML()`
    See Also:
      - `HTMLString`

  - ### exportContent

    public static void exportContent(Canvas canvas, DSRequest requestProperties)
    Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).

    As with other exports, the resulting file can be `saved to the server filesystem` instead of, or in addition to being downloaded to the user. 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.

    You can either pass any `Canvas` to `exportContent`, or you can pass HTML that you have retrieved by calling `Canvas.getPrintHTML()`. When calling `getPrintHTML()` to retrieve HTML for use with `exportContent()`, you must pass the `PrintProperties.printForExport` or `DrawPane` and `FacetChart` instances will not export properly.

    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.

    Also, you can set the filename of the export via `DSRequest.exportFilename`. For example:

          DSRequest requestProperties = new DSRequest();
          requestProperties.setAttribute("exportFilename", "export");

    In case you do not provide a filename for your export, the system will assign the default filename "export".

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

    You can also inject a small amount of CSS from the browser via `DSRequest.exportCSS` - this is intended primarily for switching the page size on the fly, for exceptionally wide or tall exports.

    Note: PDF Export Resource Security

    It is possible to send custom HTML to the Smart GWT server that attempts to include resources from the local server filesystem (predominantly images) and export them to PDF. By default, all filesystem access during PDF export is denied — only HTTP and HTTPS resource URLs are permitted.

    To allow specific filesystem paths or restrict which HTTP hosts are permitted, use the `contentExport.allowedResourceLocations` setting in `server.properties`. This is a semicolon-separated list of path segments that identify allowed resource locations. A resource URL is allowed if its full path contains at least one of the listed segments as a substring. Disallowed resources are omitted from the PDF, and a warning is logged.

    The following placeholders are supported in the allowlist patterns:

    - `{webRoot}` – the application's web root directory on the filesystem (from the `webRoot` setting in `server.properties`). Expanded once at server startup. Useful for allowing filesystem paths under the web root.
    - `{app.host}` – the server hostname, expanded per-request from `HttpServletRequest.getServerName()` (typically the value of the incoming HTTP `Host` header, e.g. `myserver.example.com`). In environments with reverse proxies, load balancers, or multi-homed servers, this reflects how the client addressed the server, which may differ from the server's internal hostname. If the proxy does not forward the original `Host` header, or the server is known by multiple DNS names, hardcode the desired hostname directly instead of using this placeholder.
    - `{app.context}` – the webapp context path, expanded per-request from `HttpServletRequest.getContextPath()` (e.g. `/myapp`). This is the webapp's deployment path, set at deploy time and not affected by network topology.
    Examples:
    - `{webRoot};{app.host}` – filesystem access under the web root, plus HTTP/HTTPS to the same server (any port, any path).
    - `http://{app.host}:8080{app.context};https://{app.host}:8443{app.context}` – tighter: specific ports and only under the application context path.
    Important: when this setting is present, it restricts both filesystem and HTTP resources — only URLs matching a listed segment are permitted. Without this setting, all HTTP and HTTPS URLs are permitted and only filesystem access is denied.

    Note that the server cannot reliably determine whether an HTTP URL points to a resource under the web root (due to URL remapping, reverse proxies, etc.), so the allowlist uses a simple substring match against the full URL. When restricting HTTP access, list only the specific hosts and paths needed.

    In ContainerIO mode (WAR deployment where the framework loads resources from the classpath rather than the filesystem), filesystem access from user-provided HTML is always denied regardless of this setting. Internal skin resources (fonts, CSS, images) are loaded from known skin directories and are not affected by this setting in any deployment mode.

    Parameters:
      `canvas` - Canvas or canvas list that has exportable widgets, or an HTML fragment derived from `getPrintHTML()`
      `requestProperties` - Request properties for the export to pdf object

  - ### exportContent

    public static void exportContent(Canvas[] canvas, DSRequest requestProperties)
    Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).

    As with other exports, the resulting file can be `saved to the server filesystem` instead of, or in addition to being downloaded to the user. 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.

    You can either pass any `Canvas` to `exportContent`, or you can pass HTML that you have retrieved by calling `Canvas.getPrintHTML()`. When calling `getPrintHTML()` to retrieve HTML for use with `exportContent()`, you must pass the `PrintProperties.printForExport` or `DrawPane` and `FacetChart` instances will not export properly.

    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.

    Also, you can set the filename of the export via `DSRequest.exportFilename`. For example:

          DSRequest requestProperties = new DSRequest();
          requestProperties.setAttribute("exportFilename", "export");

    In case you do not provide a filename for your export, the system will assign the default filename "export".

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

    You can also inject a small amount of CSS from the browser via `DSRequest.exportCSS` - this is intended primarily for switching the page size on the fly, for exceptionally wide or tall exports.

    Note: PDF Export Resource Security

    It is possible to send custom HTML to the Smart GWT server that attempts to include resources from the local server filesystem (predominantly images) and export them to PDF. By default, all filesystem access during PDF export is denied — only HTTP and HTTPS resource URLs are permitted.

    To allow specific filesystem paths or restrict which HTTP hosts are permitted, use the `contentExport.allowedResourceLocations` setting in `server.properties`. This is a semicolon-separated list of path segments that identify allowed resource locations. A resource URL is allowed if its full path contains at least one of the listed segments as a substring. Disallowed resources are omitted from the PDF, and a warning is logged.

    The following placeholders are supported in the allowlist patterns:

    - `{webRoot}` – the application's web root directory on the filesystem (from the `webRoot` setting in `server.properties`). Expanded once at server startup. Useful for allowing filesystem paths under the web root.
    - `{app.host}` – the server hostname, expanded per-request from `HttpServletRequest.getServerName()` (typically the value of the incoming HTTP `Host` header, e.g. `myserver.example.com`). In environments with reverse proxies, load balancers, or multi-homed servers, this reflects how the client addressed the server, which may differ from the server's internal hostname. If the proxy does not forward the original `Host` header, or the server is known by multiple DNS names, hardcode the desired hostname directly instead of using this placeholder.
    - `{app.context}` – the webapp context path, expanded per-request from `HttpServletRequest.getContextPath()` (e.g. `/myapp`). This is the webapp's deployment path, set at deploy time and not affected by network topology.
    Examples:
    - `{webRoot};{app.host}` – filesystem access under the web root, plus HTTP/HTTPS to the same server (any port, any path).
    - `http://{app.host}:8080{app.context};https://{app.host}:8443{app.context}` – tighter: specific ports and only under the application context path.
    Important: when this setting is present, it restricts both filesystem and HTTP resources — only URLs matching a listed segment are permitted. Without this setting, all HTTP and HTTPS URLs are permitted and only filesystem access is denied.

    Note that the server cannot reliably determine whether an HTTP URL points to a resource under the web root (due to URL remapping, reverse proxies, etc.), so the allowlist uses a simple substring match against the full URL. When restricting HTTP access, list only the specific hosts and paths needed.

    In ContainerIO mode (WAR deployment where the framework loads resources from the classpath rather than the filesystem), filesystem access from user-provided HTML is always denied regardless of this setting. Internal skin resources (fonts, CSS, images) are loaded from known skin directories and are not affected by this setting in any deployment mode.

    Parameters:
      `canvas` - Canvas or canvas list that has exportable widgets, or an HTML fragment derived from `getPrintHTML()`
      `requestProperties` - Request properties for the export to pdf object

  - ### exportContent

    public static void exportContent(String canvas, DSRequest requestProperties)
    Exports the printable representation of a set of widgets as a .pdf that is then downloaded to the user (triggering the "Save As.." dialog).

    As with other exports, the resulting file can be `saved to the server filesystem` instead of, or in addition to being downloaded to the user. 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.

    You can either pass any `Canvas` to `exportContent`, or you can pass HTML that you have retrieved by calling `Canvas.getPrintHTML()`. When calling `getPrintHTML()` to retrieve HTML for use with `exportContent()`, you must pass the `PrintProperties.printForExport` or `DrawPane` and `FacetChart` instances will not export properly.

    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.

    Also, you can set the filename of the export via `DSRequest.exportFilename`. For example:

          DSRequest requestProperties = new DSRequest();
          requestProperties.setAttribute("exportFilename", "export");

    In case you do not provide a filename for your export, the system will assign the default filename "export".

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

    You can also inject a small amount of CSS from the browser via `DSRequest.exportCSS` - this is intended primarily for switching the page size on the fly, for exceptionally wide or tall exports.

    Note: PDF Export Resource Security

    It is possible to send custom HTML to the Smart GWT server that attempts to include resources from the local server filesystem (predominantly images) and export them to PDF. By default, all filesystem access during PDF export is denied — only HTTP and HTTPS resource URLs are permitted.

    To allow specific filesystem paths or restrict which HTTP hosts are permitted, use the `contentExport.allowedResourceLocations` setting in `server.properties`. This is a semicolon-separated list of path segments that identify allowed resource locations. A resource URL is allowed if its full path contains at least one of the listed segments as a substring. Disallowed resources are omitted from the PDF, and a warning is logged.

    The following placeholders are supported in the allowlist patterns:

    - `{webRoot}` – the application's web root directory on the filesystem (from the `webRoot` setting in `server.properties`). Expanded once at server startup. Useful for allowing filesystem paths under the web root.
    - `{app.host}` – the server hostname, expanded per-request from `HttpServletRequest.getServerName()` (typically the value of the incoming HTTP `Host` header, e.g. `myserver.example.com`). In environments with reverse proxies, load balancers, or multi-homed servers, this reflects how the client addressed the server, which may differ from the server's internal hostname. If the proxy does not forward the original `Host` header, or the server is known by multiple DNS names, hardcode the desired hostname directly instead of using this placeholder.
    - `{app.context}` – the webapp context path, expanded per-request from `HttpServletRequest.getContextPath()` (e.g. `/myapp`). This is the webapp's deployment path, set at deploy time and not affected by network topology.
    Examples:
    - `{webRoot};{app.host}` – filesystem access under the web root, plus HTTP/HTTPS to the same server (any port, any path).
    - `http://{app.host}:8080{app.context};https://{app.host}:8443{app.context}` – tighter: specific ports and only under the application context path.
    Important: when this setting is present, it restricts both filesystem and HTTP resources — only URLs matching a listed segment are permitted. Without this setting, all HTTP and HTTPS URLs are permitted and only filesystem access is denied.

    Note that the server cannot reliably determine whether an HTTP URL points to a resource under the web root (due to URL remapping, reverse proxies, etc.), so the allowlist uses a simple substring match against the full URL. When restricting HTTP access, list only the specific hosts and paths needed.

    In ContainerIO mode (WAR deployment where the framework loads resources from the classpath rather than the filesystem), filesystem access from user-provided HTML is always denied regardless of this setting. Internal skin resources (fonts, CSS, images) are loaded from known skin directories and are not affected by this setting in any deployment mode.

    Parameters:
      `canvas` - Canvas or canvas list that has exportable widgets, or an HTML fragment derived from `getPrintHTML()`
      `requestProperties` - Request properties for the export to pdf object
    See Also:
      - `HTMLString`

  - ### getFormattedTimingData

    public static String getFormattedTimingData(Integer transactionNum)
    Returns formatted text visualising the tree of timing data available from the `getTimingData()` API. Intended for use in log messages and other non-interactive, information-only settings. For more advanced usages, call `getTimingData()` and work directly with the tree structure that API returns.

    Please read the `getTimingData()` documentation for some important remarks about the availability of timing data, depending on where you are calling it from. These remarks apply equally to `getFormattedTimingData()`

    Parameters:
      `transactionNum` - The number of the transaction to return timing data for
    Returns:
      Formatted text visualising the tree of timing data, if the timing data can be retrieved synchronously

  - ### getFormattedTimingData

    public static String getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback)
    See `getFormattedTimingData()`

  - ### getFormattedTimingData

    public static String getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback, Integer operationNo)
    See `getFormattedTimingData()`

  - ### getFormattedTimingData

    public static String getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback, Integer operationNo, boolean includeClient)
    See `getFormattedTimingData()`

  - ### getFormattedTimingData

    public static String getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback, Integer operationNo, boolean includeClient, boolean includeServer)
    See `getFormattedTimingData()`

  - ### getFormattedTimingData

    public static String getFormattedTimingData(Integer transactionNum, FormattedTimingDataCallback callback, Integer operationNo, boolean includeClient, boolean includeServer, Integer maxDepth)
    Returns formatted text visualising the tree of timing data available from the `getTimingData()` API. Intended for use in log messages and other non-interactive, information-only settings. For more advanced usages, call `getTimingData()` and work directly with the tree structure that API returns.

    Please read the `getTimingData()` documentation for some important remarks about the availability of timing data, depending on where you are calling it from. These remarks apply equally to `getFormattedTimingData()`

    Parameters:
      `transactionNum` - The number of the transaction to return timing data for
      `callback` - A callback to invoke, passing the formatted timing data. This parameter is optional, but it is necessary if timing data cannot be obtained synchronously, as described in the `getTimingData()` documentation
      `operationNo` - Optionally, the index of a specific operation in the overall transaction. Only pass this parameter if you want to limit the returned data to a single request
      `includeClient` - Whether to include client-side timing data. Optional defaults to true
      `includeServer` - Whether to include server-side timing data. Optional, defaults to true
      `maxDepth` - The maximum depth to descend into the tree. The lowest meaningful value for this parameter is 1 - anything less will simply cause the API to return an empty string. This parameter is optional; if it not passed, we default to "no limit"
    Returns:
      Formatted text visualising the tree of timing data, if the timing data can be retrieved synchronously

  - ### getLoadProjectErrorMessage

    public static String getLoadProjectErrorMessage(RPCResponse rpcResponse)
    Convenience method that returns a message describing the error for a failed call to `loadProject()`. Calls `getLoadProjectErrorStatus()`.
    Parameters:
      `rpcResponse` - server response
    Returns:
      the error message (null if no error)

  - ### getLoadProjectErrorStatus

    public static String getLoadProjectErrorStatus(RPCResponse rpcResponse)
    Convenience method that returns the error status for a failed call to `loadProject()`. Applies the following rules:
    - reports "badCredentials" if the `RPCResponse.status` is `STATUS_LOGIN_REQUIRED` or `STATUS_LOGIN_INCORRECT`
    - reports "timeout" if the `RPCResponse.status` is `STATUS_SERVER_TIMEOUT`
    - reports "noResponseFromURL" if the `RPCResponse.httpResponseCode` is 0
    - reports "badReifyServerURL" if the `RPCResponse.httpResponseCode` is 404 or another code representing a transport error, such as 408 or 503
    - reports "projectNotFound" if the `RPCResponse.httpResponseCode` is 500 and the `RPCResponse.httpResponseText` contains the string "Unable to load any of the projects"
    - otherwise reports "servletError"
    Parameters:
      `rpcResponse` - server response
    Returns:
      the error status (null if no error)

  - ### getQueueTransactionId

    public static Integer getQueueTransactionId()
    Returns the id of the current transaction (a queue of requests).

    This method will return null if no requests are currently queued, even if `startQueue()` has been called.

    Returns:
      the transactionNum of the current transaction, or null

  - ### getTimingData

    public static Map getTimingData(Integer transactionNum)
    Returns timing data gathered for the transaction number passed in. The timing data is an instance of `the Smart GWT Tree class`, where parent nodes encapsulate the timings of their descendants. This timing data is what drives the "Timing" view of the `Developer Console RPC tab`. Note, the returned `Tree` has `modelType` "children", so it can easily be traversed manually by simply following the nodes' "children" property recursively from the tree's "root" element.

    Each node in the tree contains the following properties:

    `name` | A descriptive name
    `start` | The start time, in milliseconds since the epoch, recorded by either the client or the server, depending on where this data was gathered. See the important notes at the bottom of the `Developer Console RPC` article regarding the relevance of the `start` and `end` time properties
    `end` | The end time, in milliseconds since the epoch. See `start`, above
    `elapsed` | The elapsed time in milliseconds for this operation
    `children` | The list of this node's direct children, if it has any

    Note, if you call `getTimingData()` directly from a `DSRequest callback` or `queue callback`, the timing data will be incomplete, because the queue at that point is incomplete (user callback processing is part of the processing that is being measured). To get around this, you can either move your `getTimingData()` call to thread-end by calling it on a 0ms delay:

             isc.RPCManager.sendQueue(function(data) {
                 // Don't call getTimingData() directly - hang it on a timer
                 isc.Timer.setTimeout(function() {
                     var timingData = isc.RPCManager.getTimingData(data[0].transactionNum);
                     // Process data here...
                 }, 0);
             });

    Alternatively, you can move your `getTimingData()` call into a "processing complete" callback, and register it with the `addProcessingCompleteCallback()` API. Processing complete callbacks fire when the transaction is fully complete, including any user callbacks.

    Also note, if you are using the `Developer Console`, timing data may not be available synchronously from your application code, so you will have to implement a callback function and pass it as the second parameter. This is inconvenient, but it is a browser restriction that we have no control over.

    If you call `getTimingData()` from your queue callback on a 0ms delay, or using a processing complete callback, as described above, the synchronous call is likely to work. If you introduce any kind of delay, or call `getTimingData()` in a way that is not synchronized with the transaction - for example, periodically on a timer, or in response to some user action - the synchronous call is likely to return an error message stating that the timing data is unavailable synchronously, and you should provide a callback. Again, all of this applies only if you have the Smart GWT Developer Console open (and it applies equally to `getFormattedTimingData()`).

    Here is an example of how to provide a callback to the function:

             isc.RPCManager.getTimingData(myTransactionNum, function(retval) {
                 var root = retval.root;
                 // Whatever processing of the timing data is required...
             }, ... optional params if required ...);

    Parameters:
      `transactionNum` - The number of the transaction to return timing data for
    Returns:
      the tree of timing data, as described in the above documentation
    See Also:
      - `getFormattedTimingData(java.lang.Integer)`

  - ### getTimingData

    public static Map getTimingData(Integer transactionNum, TimingDataCallback callback)
    See `getTimingData()`

  - ### getTimingData

    public static Map getTimingData(Integer transactionNum, TimingDataCallback callback, Integer operationNo)
    See `getTimingData()`

  - ### getTimingData

    public static Map getTimingData(Integer transactionNum, TimingDataCallback callback, Integer operationNo, boolean includeClient)
    See `getTimingData()`

  - ### getTimingData

    public static Map getTimingData(Integer transactionNum, TimingDataCallback callback, Integer operationNo, boolean includeClient, boolean includeServer)
    Returns timing data gathered for the transaction number passed in. The timing data is an instance of `the Smart GWT Tree class`, where parent nodes encapsulate the timings of their descendants. This timing data is what drives the "Timing" view of the `Developer Console RPC tab`. Note, the returned `Tree` has `modelType` "children", so it can easily be traversed manually by simply following the nodes' "children" property recursively from the tree's "root" element.

    Each node in the tree contains the following properties:

    `name` | A descriptive name
    `start` | The start time, in milliseconds since the epoch, recorded by either the client or the server, depending on where this data was gathered. See the important notes at the bottom of the `Developer Console RPC` article regarding the relevance of the `start` and `end` time properties
    `end` | The end time, in milliseconds since the epoch. See `start`, above
    `elapsed` | The elapsed time in milliseconds for this operation
    `children` | The list of this node's direct children, if it has any

    Note, if you call `getTimingData()` directly from a `DSRequest callback` or `queue callback`, the timing data will be incomplete, because the queue at that point is incomplete (user callback processing is part of the processing that is being measured). To get around this, you can either move your `getTimingData()` call to thread-end by calling it on a 0ms delay:

             isc.RPCManager.sendQueue(function(data) {
                 // Don't call getTimingData() directly - hang it on a timer
                 isc.Timer.setTimeout(function() {
                     var timingData = isc.RPCManager.getTimingData(data[0].transactionNum);
                     // Process data here...
                 }, 0);
             });

    Alternatively, you can move your `getTimingData()` call into a "processing complete" callback, and register it with the `addProcessingCompleteCallback()` API. Processing complete callbacks fire when the transaction is fully complete, including any user callbacks.

    Also note, if you are using the `Developer Console`, timing data may not be available synchronously from your application code, so you will have to implement a callback function and pass it as the second parameter. This is inconvenient, but it is a browser restriction that we have no control over.

    If you call `getTimingData()` from your queue callback on a 0ms delay, or using a processing complete callback, as described above, the synchronous call is likely to work. If you introduce any kind of delay, or call `getTimingData()` in a way that is not synchronized with the transaction - for example, periodically on a timer, or in response to some user action - the synchronous call is likely to return an error message stating that the timing data is unavailable synchronously, and you should provide a callback. Again, all of this applies only if you have the Smart GWT Developer Console open (and it applies equally to `getFormattedTimingData()`).

    Here is an example of how to provide a callback to the function:

             isc.RPCManager.getTimingData(myTransactionNum, function(retval) {
                 var root = retval.root;
                 // Whatever processing of the timing data is required...
             }, ... optional params if required ...);

    Parameters:
      `transactionNum` - The number of the transaction to return timing data for
      `callback` - A callback to invoke, passing the timing data object tree. This parameter is optional, but it is necessary if timing data cannot be obtained synchronously, as described above
      `operationNo` - Optionally, the index of a specific operation in the overall transaction. Only pass this parameter if you want to limit the returned data to a single request
      `includeClient` - Whether to include client-side timing data. Optional defaults to true
      `includeServer` - Whether to include server-side timing data. Optional, defaults to true
    Returns:
      the tree of timing data, as described in the above documentation
    See Also:
      - `getFormattedTimingData(java.lang.Integer)`

  - ### getTransactionDescription

    public static String getTransactionDescription(Integer transactionNum)
    Returns a brief description of the transaction in the following format for logging purposes: `"Transaction with n operation(s). [dsName1.operationType; dsName2.operationType; ...]"`
    Parameters:
      `transactionNum` - The number of the transaction to return timing data for
    Returns:
      transaction description

  - ### setHandleErrorCallback

    public static void setHandleErrorCallback(HandleErrorCallback callback)
    `handleError()` will be called if `RPCResponse.status` is negative and `RPCRequest.willHandleError` was not set. It is called for both `DSResponse`s and `RPCResponse`s 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 `RPCRequest.willHandleError` and deal with errors in the rpcRequest.callback. To change the default system-wide error handling, install a `HandleErrorCallback` with this method. To invoke the default error handling in your new handler, you can simply call the method `runDefaultErrorHandling()`.

    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. This can be accessed via `DSResponse.getAttributeAsJavaScriptObject()`. 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.

    See the `overview of error handling` for additional guidance.

    Parameters:
      `callback` - HandleErrorCallback the callback to set.
    See Also:
      - `ErrorEvent`
      - `HandleTransportErrorCallback.handleTransportError(int, int, int, java.lang.String)`
      - `runDefaultErrorHandling(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest)`

  - ### hasCurrentTransactionQueued

    public static Boolean hasCurrentTransactionQueued()
    Returns true if there is a current transaction (queue of requests)

    This method will return false if no requests are currently queued, even if `startQueue()` has been called.

    Returns:
      true if there is a current transaction

  - ### isScreenCached

    public static void isScreenCached(String screenName)
    Returns true if a screen with the given name has already been cached by a call to `cacheScreens()` or similar (e.g. `loadProject()`), false otherwise.
    Parameters:
      `screenName` - name of the screen
    See Also:
      - `LoadScreenSettings.getCacheScreen()`

  - ### loadProject

    public static void loadProject(String projectNames, LoadProjectCallback callback, LoadProjectSettings settings)
    Loads projects using the `ProjectLoaderServlet`, reachable at `projectLoaderURL`, and fires the given callback after the project has been cached. When a project is loaded, all of its DataSources and screens (except where explicitly overridden by settings) are also cached in the project.

    Loading of a project merely caches DataSources and screens. No screens are created automatically. To create a screen, you must call `Project.createScreen()` or `Project.createStartScreen()`, which will automatically create any DataSource needed by the screen that's not already globally bound. You can also manually instantiate and globally bind (if not already bound) a screen DataSource without creating the screen, by calling `Project.getDataSource()`.

    Note that any screen cached in a loaded project will also be bound in the global cache if no screen of that name is present there. You can create a screen from the global cache using `createScreen()`.

    When projects are cached, they're made available via `Project.get()`. To remove a cached project, and release storage for its cached screens and DataSources, simply call `Project.destroy()`.

    Parameters:
      `projectNames` - Comma-separated string containing the names of project(s) to load.
      `callback` - Callback for notification of completion of project(s) loaded and screens cached.
      `settings` - Settings applicable to the loadProject operation.

  - ### 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 are 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 `RPCRequest`s passed to this method is strictly read-only.

    Parameters:
      `callback` - QueueSentCallback the callback to set.

  - ### removeProcessingCompleteCallback

    public static void removeProcessingCompleteCallback(Integer index)
    Unregister the `processingComplete` callback associated with the parameter index
    Parameters:
      `index` - The identifying index returned from `addProcessingCompleteCallback()`

  - ### requestsArePending

    public static 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 `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(int 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

  - ### runDefaultErrorHandling

    public static void runDefaultErrorHandling(DSResponse response, DSRequest request)
    Runs the default error handling normally performed by `HandleErrorCallback.handleError()`. May be called from a custom handler to achieve the default behavior if one has been installed.
    Parameters:
      `response` - response the response
      `request` - request the request
    See Also:
      - `HandleErrorCallback.handleError(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest)`

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

    This method will do nothing and the callback will not be called if no requests have actually been queued. You can detect whether the queue is empty by calling `getQueueTransactionId()`.

    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 `startQueue()` for more information about queuing.

    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.

    This method will do nothing and the callback will not be called if no requests have actually been queued. You can detect whether the queue is empty by calling `getQueueTransactionId()`.

    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 `startQueue()` for more information about queuing.

    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()`

  - ### setActionURL

    public static void setActionURL(String actionURL)
    Setter for `actionURL`.
    Parameters:
      `actionURL` - new actionURL. See `URL`
    See Also:
      - `URL`

  - ### setTimingDataEnabled

    public static void setTimingDataEnabled(boolean enabled)
    Pass `true` or `false` to switch the gathering of timing metrics on and off programmatically. The timing data thus gathered can be viewed in the "Timing" section of the `Developer Console RPC tab`, or retrieved by your own code by use of the `getTimingData()` API.
    Parameters:
      `enabled` - Whether to switch timing data on or off

  - ### startQueue

    public static boolean startQueue()
    Start queuing `DSRequests` and `RPCRequests` system-wide, for later sending when RPCManager.sendQueue() is called, at which time all queued requests will be sent as a single, combined HTTP request.

    Combining requests via queuing:

    - allows the server to implement transactional saving when multiple records are affected by actions in the UI
    - can reduce overhead by combining related requests, avoiding the use of multiple network connections, redundant authentication checks, and other redundant resource allocations that would otherwise happen if requests were processed separately
    - can simplify application logic that otherwise has to deal with multiple outstanding server requests that might complete in any order

    Queuing is used automatically by many, many framework features, including multi-row grid editing (`Grid Mass Editing`), multi-row drag & drop, `data paging for large trees`, `"serverCustom" validators`, Master-Detail saves, `OLAP / datacube functionalty`, and many others.

    Queuing also has subtler architectural benefits in terms of building reusable services - see the QuickStart Guide sections on Queuing for details.

    For all the reasons given above, it's extremely important to use DataSources that can support queuing. Queuing is automatically supported when using server-based DataSources with the Smart GWT Server Framework, and is supported by `RestDataSource`.

    Order of Execution

    When the Smart GWT Server framework receives a queued request, it will process all requests, in order, in a single thread, before any response is sent to the client. All client-side actions related to queued requests, such as `callbacks firing` on completion, likewise happen in queue order, after all server-side processing has taken place.

    Therefore when using queuing you can use the callback argument of `sendQueue()` to detect that all operations have completed, which is much simpler than the logic needed to track multiple asynchronous operations and wait for all to complete.

    Nested Queuing

    In some cases you may wish to combine requests being sent by application logic with queued requests automatically sent by components. For example, you may want to call `ListGrid.saveAllEdits()` but also add an additional request to the same queue.

    To do this, just call `startQueue()` before `saveAllEdits()` (or whatever other API would also normally perform a queued request), then call `sendQueue()`. Framework features that use queuing will automatically notice that you have already started a queue, and will not automatically call `sendQueue()` in this case. You can implement the same behavior in your own reusable components by checking the return value of `startQueue()`, which tells you whether queuing is already active.

    Requests that can't be queued

    When using queuing, all requests in a given queue must go to the same `RPCRequest.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.

    Due to browser security restrictions, at most one request with a `file\n upload` can be sent in a queue. If you attempt to add another, the existing queue will be sent immediately, logging a warning, and queueing restarted for the new request.

    Note that whenever requests are not sent in a single queue, order is not guaranteed, and the callback provided to `sendQueue()` at the end of your transaction may fire before requests not sent in the final queue have completed.

    Implementing your own Queuing

    If you are in the rare situation that:

    - you can't use the Smart GWT Server framework
    - the server you are integrating with some pre-existing support for combining operations in a flexible way, similar to queuing
    - you are totally unable to implement the RestDataSource protocol for this server, even through approaches such as adding it as an additional service while leaving the original services unchanged, or going through an intermediate server
    .. then you can implement a crude version of the built-in queuing feature by using `dataProtocol:"clientCustom"` to avoid HTTP requests being immediately sent when a DataSource executes. In outline:
    - create an API similar to `startQueue()` for managing a global setting reflecting whether your special queuing system is active. Your DataSources should check for this global setting in `DataSource.transformRequest()`, and, if queuing is active, store the request you received in `DataSource.transformRequest()` in memory, for example in an Array
    - implement your own equivalent of `RPCManager.sendQueue()` which sends an HTTP request representing your combined requests, then once you receive your combined response, call `DataSource.processResponse()` for each request.
    Note that attempting to integrate with `RPCManager`'s queuing system doesn't really make sense - `RPCManager` won't be aware of your separate, special queue of requests, so will reject calls to `sendQueue()` since RPCManager's queue is empty. Similarly, enabling queuing on `RPCManager` may cause inadvertent queuing of unrelated requests you did not intend to queue. Maintaining your own separate notion of whether queuing is active is simpler and less error prone.
    Returns:
      whether queuing was already enabled before we called.
    See Also:
      - `sendQueue()`

  - ### startQueue

    public static boolean startQueue(boolean shouldQueue)
    Start queuing `DSRequests` and `RPCRequests` system-wide, for later sending when RPCManager.sendQueue() is called, at which time all queued requests will be sent as a single, combined HTTP request.

    Combining requests via queuing:

    - allows the server to implement transactional saving when multiple records are affected by actions in the UI
    - can reduce overhead by combining related requests, avoiding the use of multiple network connections, redundant authentication checks, and other redundant resource allocations that would otherwise happen if requests were processed separately
    - can simplify application logic that otherwise has to deal with multiple outstanding server requests that might complete in any order

    Queuing is used automatically by many, many framework features, including multi-row grid editing (`Grid Mass Editing`), multi-row drag & drop, `data paging for large trees`, `"serverCustom" validators`, Master-Detail saves, `OLAP / datacube functionalty`, and many others.

    Queuing also has subtler architectural benefits in terms of building reusable services - see the QuickStart Guide sections on Queuing for details.

    For all the reasons given above, it's extremely important to use DataSources that can support queuing. Queuing is automatically supported when using server-based DataSources with the Smart GWT Server Framework, and is supported by `RestDataSource`.

    Order of Execution

    When the Smart GWT Server framework receives a queued request, it will process all requests, in order, in a single thread, before any response is sent to the client. All client-side actions related to queued requests, such as `callbacks firing` on completion, likewise happen in queue order, after all server-side processing has taken place.

    Therefore when using queuing you can use the callback argument of `sendQueue()` to detect that all operations have completed, which is much simpler than the logic needed to track multiple asynchronous operations and wait for all to complete.

    Nested Queuing

    In some cases you may wish to combine requests being sent by application logic with queued requests automatically sent by components. For example, you may want to call `ListGrid.saveAllEdits()` but also add an additional request to the same queue.

    To do this, just call `startQueue()` before `saveAllEdits()` (or whatever other API would also normally perform a queued request), then call `sendQueue()`. Framework features that use queuing will automatically notice that you have already started a queue, and will not automatically call `sendQueue()` in this case. You can implement the same behavior in your own reusable components by checking the return value of `startQueue()`, which tells you whether queuing is already active.

    Requests that can't be queued

    When using queuing, all requests in a given queue must go to the same `RPCRequest.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.

    Due to browser security restrictions, at most one request with a `file\n upload` can be sent in a queue. If you attempt to add another, the existing queue will be sent immediately, logging a warning, and queueing restarted for the new request.

    Note that whenever requests are not sent in a single queue, order is not guaranteed, and the callback provided to `sendQueue()` at the end of your transaction may fire before requests not sent in the final queue have completed.

    Implementing your own Queuing

    If you are in the rare situation that:

    - you can't use the Smart GWT Server framework
    - the server you are integrating with some pre-existing support for combining operations in a flexible way, similar to queuing
    - you are totally unable to implement the RestDataSource protocol for this server, even through approaches such as adding it as an additional service while leaving the original services unchanged, or going through an intermediate server
    .. then you can implement a crude version of the built-in queuing feature by using `dataProtocol:"clientCustom"` to avoid HTTP requests being immediately sent when a DataSource executes. In outline:
    - create an API similar to `startQueue()` for managing a global setting reflecting whether your special queuing system is active. Your DataSources should check for this global setting in `DataSource.transformRequest()`, and, if queuing is active, store the request you received in `DataSource.transformRequest()` in memory, for example in an Array
    - implement your own equivalent of `RPCManager.sendQueue()` which sends an HTTP request representing your combined requests, then once you receive your combined response, call `DataSource.processResponse()` for each request.
    Note that attempting to integrate with `RPCManager`'s queuing system doesn't really make sense - `RPCManager` won't be aware of your separate, special queue of requests, so will reject calls to `sendQueue()` since RPCManager's queue is empty. Similarly, enabling queuing on `RPCManager` may cause inadvertent queuing of unrelated requests you did not intend to queue. Maintaining your own separate notion of whether queuing is active is simpler and less error prone.
    Parameters:
      `shouldQueue` - whether queuing should be enabled, default true. Passing false will disable queuing but not send the queue yet, so that any queued requests will be sent along with the next send()/sendRequest()
    Returns:
      whether queuing was already enabled before we called.
    See Also:
      - `sendQueue()`

  - ### transformRequest

    public static Object transformRequest(RPCRequest rpcRequest)
    Returns the data that should be sent to the `actionURL`.

    In a manner analogous to `DataSource.transformRequest()`, this method allows you to transform an `RPCRequest`, such as by adding `HTTP headers`, to ensure proper handling on the server.

    This is not an override point. See `customizeTransforms(RequestTransformer)`.

    Parameters:
      `rpcRequest` - the RPCRequest being processed
    Returns:
      data to be sent to the actionURL

  - ### xmlHttpRequestAvailable

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

  - ### getMaxLoginAttemptsExceededMarker

    public static void getMaxLoginAttemptsExceededMarker()
    Get the marker the system will look for in order to detect when the number of maximum logins was exceeded.
    See Also:
      - `com.smartgwt.client.rpc.RPCManager#setLoginRequiredMarker()`

  - ### setMaxLoginAttemptsExceededMarker

    public static String setMaxLoginAttemptsExceededMarker(String maxLoginAttemptsExceededMarker)
    Set the marker the system will look for in order to detect when the number of maximum logins was exceeded.
    Parameters:
      `loginSuccessMarker` - default value <SCRIPT>//'\"]]>>isc_maxLoginAttemptsExceeded
    See Also:
      - `com.smartgwt.client.rpc.RPCManager#setLoginRequiredMarker()`

  - ### 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(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(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(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(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(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`

  - ### 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

  - ### cancelQueue

    public static void cancelQueue(String transactionNum)
    Deprecated.
    please use int methods when dealing with transaction number.
    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(String transactionNum)
    Deprecated.
    please use int methods when dealing with transaction number.
    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

  - ### resendTransaction

    public static void resendTransaction(String transactionNum)
    Deprecated.
    please use int methods when dealing with transaction number.
    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

  - ### 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(int)` or re-sent via `resendTransaction()` or memory will be leaked.

  - ### suspendTransaction

    public static void suspendTransaction(String transactionID)
    Deprecated.
    please use int methods when dealing with transaction number.
    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(int)` or re-sent via `resendTransaction()` or memory will be leaked.

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

  - ### suspendTransaction

    public static void suspendTransaction(int 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(int)` 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 String getCurrentTransactionId()
    Deprecated.
    please use int methods when dealing with transaction number.
    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.

  - ### getCurrentTransactionIdAsInt

    public static int getCurrentTransactionIdAsInt()
    Same as getQueueTransactionId() but returns `-1` instead of `null` if there's no currently queued requests.
    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(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(String data, RPCCallback callback, 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(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(JavaScriptObject data, RPCCallback callback, 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(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(String screenName, LoadScreenCallback callback, 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(String screenName, LoadScreenCallback callback, 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(String screenName, LoadScreenCallback callback, String[] globals, 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 `BaseWidget.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

  - ### loadScreen

    public static void loadScreen(String screenName, LoadScreenCallback callback, LoadScreenSettings settings, String locale)
    See `loadScreen(java.lang.String,com.smartgwt.client.rpc.LoadScreenCallback,java.lang.String[],java.lang.String,com.smartgwt.client.rpc.RPCRequest)`.
    Parameters:
      `screenName` - name of the screen to load
      `callback` - callback for notification of screen being loaded
      `settings` - customization settings for screen loading process
      `locale` - the locale name to use to resolve i18n tags in the screen component XML

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

  - ### createScreen

    public static Canvas createScreen(String screenName, String[] globals)
    See `createScreen(String,com.smartgwt.client.rpc.CreateScreenSettings)`.
    Parameters:
      `screenName` - name of the screen to create
      `globals` - widgets to allow to take their global IDs, or a widget remap config
    Returns:
      last top-level widget in the screen definition

  - ### exportImage

    public static void exportImage(String svgString)

  - ### exportImage

    public static void exportImage(String svgString, DSRequest requestProperties)

  - ### exportImage

    public static void exportImage(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.

  - ### setHandleTransportErrorCallback

    public static void setHandleTransportErrorCallback(HandleTransportErrorCallback callback)
    Sets callback to handle server error responses for 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 `RPCRequest.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 `handleError()`, or by the standard request callback methods, depending on request.willHandleError. To perform custom handing for transport errors, use this method to install a `HandleTransportErrorCallback`.

    See `cancelDefaultErrorHandling()` for details on how to stop the default error handling or current `error handler` if it interferes with what you're trying to do in the `HandleTransportErrorCallback` passed to this method.

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

    See this `separate article` on error handling for an overview.

    Parameters:
      `callback` - HandleTransportErrorCallback the callback to set.
    See Also:
      - `HandleErrorCallback.handleError(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest)`

  - ### cancelDefaultErrorHandling

    public static void cancelDefaultErrorHandling()
    Cancels default error handling for all `DSResponse`s in the current transaction, ensuring that the default error handling or current `error handler` is not called for any of them. This method is intended to be called inside a `HandleTransportErrorCallback`, to prevent any potential interference from the default handling.

  - ### customizeTransforms

    public static void customizeTransforms(RequestTransformer requestTransformer)
    Apply the specified `RequestTransformer` to override the default behavior of `transformRequest(RPCRequest)`.
    Parameters:
      `requestTransformer` - the request transformer.