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 are 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 the HTML DOM or accessing internals of the web client. It is strongly recommended to use the official JavaScript API only.
• JavaScriptLoader
  Can be used to load and execute entire JavaScript files on the client. The file may be provided by the RAP application itself (by registering it as static resource), or (since RAP 2.2) from any other URL that is reachable by the client. When a file has been loaded and executed by the connected client instance once, it will not do so again if the method is called again with the same URL. This service is especially useful for custom widget / custom component development. NOTE: The warnings from JavaScriptExecuter also apply for JavaScriptLoader.

JavaScript API

The web client provides a JavaScript API that mirrors the server side Remote API and allows limited access to client widget instances. The purpose of this API is to support custom widget development and allow cross-widget scripting.