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 the framework can use 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 different servlet contexts.

RAP uses a callback approach to configure applications before they are started. For that, an implementation of the interface ApplicationConfiguration is required. There, 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 is recommended to extend AbstractEntryPoint

public class SimpleConfiguration implements ApplicationConfiguration {

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

}

Any application may have any number of entry points, as long as they are mapped to different paths. In this case the entry point would be executed when the URL http://<rapserver>:<port>/simple is typed into the browser.

The third argument of addEntryPoint can be a map that configures visual aspects of the entry point. These may be client-specific, and therefore the client class (i.e. WebClient) provides constants to be used with the map. It's possible to specify which theme to use, and which icon and name should be displayed in the browser title bar. If your favicon has to work with legacy browsers, use a file in the ICO format. It's also possible to add static HTML to the client documents head or body. That way a simple splash screen can be implemented.

Map<String, String> properties = new HashMap<String, String>();
properties.put( WebClient.PAGE_TITLE, "RAP Example" );
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.

The application instance also a method (setOperationMode) to set the operation mode and one to register service handler.

Registering the Application Configuration

When using OSGi, the application configuration can be registered as a service. We recommend using OSGi declarative services (DS). You can create a service component definition with Eclipse (New > Plug-in Development > Component Definition). The service component definition is an XML file, usually contained in a directory named OSGI-INF. Edit it to point to your configuration implementation as shown below:

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

When manually creating this file, it also has to be registered in the bundle manifest. Add a line like the following to the MANIFEST.MF:

Service-Component: OSGI-INF/configuration.xml

Custom context path

Applications configurations can be registered for a custom context path by adding the service parameter contextName to the service registration. When using declarative services, a line like the following can be added to the component definition:

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

With this configuration, the entry point simple defined above will be available at http://<host>:<port>/example/simple.

RWT stand-alone

When using RWT as a library in a traditional web application, i.e. without OSGi, the application configuration can be registered in the deployment descriptor- (web.xml) by adding a context-param with the fully qualified class name of the implementation:

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

You can always look up the param-name in the constant ApplicationConfiguration#CONFIGURATION_PARAM.

Starting an Application

When an application configuration has been registered as described above, the bundle org.eclipse.rap.rwt.osgi will automatically start this application on every 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();