The RAP Client

The term "RAP client" is used to identify the software that displays the actual UI of a RAP application, and communicates with the RAP server using the RAP Protocol. The term does not include the environment an instance of the client runs in (browser and/or OS), or the hardware ("device") itself.

The RAP project includes the default RAP client, written in JavaScript. It it will be referred to simply as the "web client" from here on. The web client is downloaded and started automatically when the URL of a RAP application is entered into a browser. In-depth technical information about this client can be found in the RAP Wiki. Other client implementations than the web client are currently not part of the RAP project.

The Client Interface

Every client implementation is represented by a class implementing the Client interface, e.g. WebClient. An instance of such a class can be obtained from RWT.getClient(). It represents the client instance connected to the current RAP session. By using the instanceof operator, the instance can be used to identify the client.

if( RWT.getClient() instanceof WebClient ) {
  ...
}

The client interface mainly specifies the getService() method (described below), while the client class may add some constants to be used in the application configuration.

Client Services

Client services are interfaces that can provide client-specific features. The getService() method of the client object can be used to obtain an implementation of a given service, provided it is supported by the connected client. Whether or not a service is supported depends on the RAP client implementation, but may also change depending on the clients runtime environment (browser) and configuration.

If a service is not supported, the method returns null. If this is a possibility given the used service and targeted RAP client, a null check should be performed before using the service. Currently, all services of the WebClient are supported at all times (i.e. on all browser).

Example usage of a service:

BrowserNavigation navigation = RWT.getClient().getService( BrowserNavigation.class );
if( navigation != null ) {
  ...
}

Services of the web client

These services are all supported by the web client and can be found in the package org.eclipse.rap.rwt.client.service.

• ClientInfo
  Provides the clients locale and timezone offset (in minutes). The locale may be null if the client does not specify a locale. In contrast, RWT.getLocale() will return the sessions locale which can also be changed programmatically and will never be null.
• BrowserNavigation: See "Deep Links" and "Browser History"
• ExitConfirmation: See "Exit Confirmation".
• URLLauncher: See "Open URLs in an external browser/application".
• JavaScriptExecuter
  Allows executing arbitrary JavaScript code in the window the RAP client runs in. This is usually not necessary, but may be useful to work around minor limitations in RAP or implement very simple features. NOTE: This feature allows manipulating to the HTML DOM or accessing internals of the web client. Doing so is not recommended and may have unintended consequences, including crashing the client.
• JavaScriptLoader
  Can be used to execute entire JavaScript files on the client. If a file has been executed by the client instance once, it will not be executed again. The URL has to point to the same domain the RAP server is in. This can be achieved by registering the file as static resource. Especially useful for custom widget / custom component development. NOTE: The warnings from JavaScriptExecuter also apply for JavaScriptLoader.