Application Configuration

This article explains how to configure a RAP application in an OSGi or in an RWT Standalone setup without the extension registry. This approach does not apply for workbench-based applications, which are configured using extensions (see Branding).

Implementing an ApplicationConfiguration

A RAP application consists of various parts, such as entry points, URL mappings, themes, service handlers, etc. All these parts constitute an application configuration, which is used by the framework to create and start an application instance. There can be more than one application instance at runtime, e.g. running on different network ports or in different servlet contexts.

An application configuration is an implementation of the interface ApplicationConfiguration. RAP uses a callback approach to configure applications before they are started. The method configure( Application ) is invoked with a reference to the created Application as the sole argument. A minimal implementation must register at least one implementation of the EntryPoint interface (it's recommended to extend AbstractEntryPoint).

public class SimpleConfiguration implements ApplicationConfiguration {

  public void configure( Application application ) {
    application.addEntryPoint( "/simple", SimpleEntryPoint.class, null );
  }

}

An application may have any number of entry points, each mapped to a separate servlet path. In case of the example above, the entry point would be available at the URL http://{rapserver}:{port}/simple.

The third argument of addEntryPoint is an optional map to configure visual aspects of the entry point. These may be client-specific, and therefore the Client implementation (e.g. WebClient) provides constants to be used with the map. For example, it's possible to specify a theme to use, native HTML document overflow behaviour, and an icon and title to be displayed in the browser title bar. It's also possible to add static HTML to the client documents head or body, e.g. to implement a simple splash screen.

Map<String, String> properties = new HashMap<String, String>();
properties.put( WebClient.PAGE_TITLE, "RAP Example" );
properties.put( WebClient.PAGE_OVERFLOW, "scrollY" );
properties.put( WebClient.BODY_HTML, "<big>Loading Application<big>" );
properties.put( WebClient.FAVICON, "icons/favicon.png" );
properties.put( WebClient.THEME_ID, "MyCustomTheme" );
application.addEntryPoint( "/example", Example.class, properties );

Note that the favicon and any images you might use in the additional HTML must be registered as a static resource. This can also be done in the application configuration with the method Application#addResource. Learn more about static resources here.

The theme-id (WebClient.THEME_ID) is the same that is used in the method Application#addStyleSheet. Learn more about custom themes and theme contributions here.

Moreover, the application instance provides methods to set the operation mode and to register a service handler.

Exception Handlers

By default, any exception that occurs during the event handling in a RAP application will lead to an HTTP 500 response (“Internal Server Error”). As an effect, the current UISession can not be continued. In a production environment, this is not always an appropriate response to an error.

Since RAP 2.1, a custom exception handler can be registered in an application configuration to process exceptions that happen in event handling code. When an exception handler is registered, all exceptions that occur while running the event loop will be forwarded to this handler. The exception handler can then decide to ignore the exception, to write it to a log, display a message to the user, or to gracefully terminate the UISession.

application.setExceptionHandler( new ExceptionHandler() {
  @Override
  public void handleException( Throwable exception ) {
    // display error dialog, redirect to error page,
    // write exception to log, ...
  }
});

To allow an exception handler to log all kinds of errors, it is even called for instances of Error. However, since errors must not be swallowed, they will be re-thrown after the handler was called.

Registering the Application Configuration

The application configuration needs to be registered in order to be found by the framework. When using OSGi, it can be registered as a service. This can be done either programmatically in a bundle activator or in a declarative way. Declarative services (DS) are the preferred way to register services in Equinox. For applications that don't use OSGi, the application configuration must be provided in a context parameter (see below).

Using OSGi Declarative Services (DS)

Using OSGi Declarative Services, a service component can be declared in an XML file inside the bundle. Here's an example that registers an application configuration:

<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0">
  <implementation class="com.example.ExampleConfiguration"/>
  <service>
     <provide interface="org.eclipse.rap.rwt.application.ApplicationConfiguration"/>
  </service>
</scr:component>

Adjust the element implementation to point to your application configuration. A common convention is to put this file in a directory named OSGI-INF in the bundle root. The file must be referenced in the bundle manifest (MANIFEST.MF) as follows:

Service-Component: OSGI-INF/configuration.xml

The Plug-in development tools in Eclipse include a wizard for creating service declarations: New > Plug-in Development > Component Definition.

Custom context path

By default, a RAP application is available directly at the servlet container's root. For example, the servlet path “/simple” will be mapped to a URL like http://example.com:8080/simple. When using the servlet bridge, an additional path segment will be included that represents the web application.

It is possible to specify a custom context path to be included in the URL. To do so, the application configuration service must be registered with a service parameter contextName. When using declarative services, a line like the following would be added to the component declaration:

  <property name="contextName" type="String" value="example"/>

With this configuration, the same entry point will be available at http://example.com:8080/example/simple.

RWT stand-alone

When using RWT as a library in a traditional web application (i.e. without OSGi) the application configuration must be registered using a context parameter. This can be done by adding a context-param element to the web.xml:

<context-param>
  <param-name>org.eclipse.rap.applicationConfiguration</param-name>
  <param-value>com.example.ExampleConfiguration</param-value>
</context-param>

Replace the parameter value with the fully qualified class name of your application configuration. The parameter name is also contained in the constant ApplicationConfiguration#CONFIGURATION_PARAM as a reference.

Starting the Application

When an application configuration has been registered as a service in OSGi, the bundle org.eclipse.rap.rwt.osgi will automatically start this application on any available HttpService. When using Equinox, don’t forget to also include the org.eclipse.equinox.ds bundle.

Please also ensure that the bundle org.eclipse.rap.ui.workbench is not included in your configuration. The workbench bundle automatically starts an application in the default context that clashes with the registered application unless the application is registered with a custom context.

As an alternative to letting the framework start the application automatically, applications can also be started explicitly using an ApplicationRunner:

ApplicationConfiguration configuration = new SimpleConfiguration();
ApplicationRunner runner = new ApplicationRunner( configuration, servletContext );
runner.start();