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. Other client implementations are not part of the RAP project itself.

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, for example to set a favicon or enable HTML document scrolling.

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.
• ClientFileLoader
  Can be used to load client-side JavaScript and CSS files. They will be added to the client documents "head" element. 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 ClientFileLoader. This service is a replacement of deprecated JavaScriptLoader.
• ClientFileUploader
  Can be used to upload files from the client device to any given URL. A client-side file is represented by the class ClientFile which can be obtained from a Drop event if ClientFileTransfer is used. To receive the file on the RAP server, use the FileUploadHandler from the RAP Incubator.
• StartupParameters
  Can be used to access startup parameters of an entry point. In the default web client, these parameters can be passed as HTTP request parameters in the initial request.

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.