The new Application API in RAP

RAP 1.5 includes a new API to define and start RAP applications programmatically (up to RAP 1.4, this was only possible using Eclipse extensions or web.xml properties). With this new API, RAP can also be used for leightweight applications based on OSGi, but without the entire Eclipse stack, even with other OSGi containers like Apache Felix. Also traditional web applications, that use RWT as a library without OSGi, benefit from the new API.

This API contains a couple of interfaces that we had trouble to find suitable names for. If you’ve used this API already you know that there were two interfaces side-by-side in the same package with almost the same name: ApplicationConfigurator and ApplicationConfiguration. Even though these names seemed to be correct, it turned out that they were hard to tell apart, and if mixed up in a service declaration, the application did not start, without any warning.

So we reviewed the case and eventually came up with better names for the interfaces without changing the structure. Let me explain the new API and our reasoning behind it.

Implementing an ApplicationConfiguration

A RAP application consists of various parts, such as entrypoints, URL mappings, themes, service handlers, etc. All these parts constitute an ApplicationConfiguration. The configuration is like the blueprint for an application. Based on an ApplicationConfiguration, the framework can create and start an application instance. There can be more than one application instances at runtime, e.g. running on different network ports or different servlet contexts.

Hence, when you write a RAP application, you have to provide an ApplicationConfiguration.

An ApplicationConfiguration is used to configure an application before it is started. For this step, RAP follows a callback approach to leave the responsibility for creating and starting the application with the framework. Therefore, the configuration must actively configure the application. To do so, it has one method configure( Application ). The framework provides a reference to the created Application as a parameter to this method. Here’s how a simple implementation looks like:

public class SimpleConfiguration implements ApplicationConfiguration {

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

Registering the ApplicationConfiguration

When using OSGi, the ApplicationConfiguration can be registered as a service. I’d recommend using OSGi declarative services (DS) like this:

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. You can find an example of a simple RAP application using DS on github.

When using RWT as a library in a traditional web application, i.e. without OSGi, you can register your ApplicationConfiguration in the web.xml by adding a context-param with the fully qualified class name of the implementation:

  org.eclipse.rap.applicationConfiguration
  com.example.ExampleConfiguration

You can always look up the param-name in the constant ApplicationConfiguration#CONFIGURATION_PARAM. The RAP FAQ has a complete example.

Starting an Application

When an ApplicationConfiguration has been registered as described above, the application is automatically started by the framework. Alternatively, it can also be started explicitly using an ApplicationRunner:

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

There’s a saying that there were only two hard things in computer science, cache invalidation and naming things. I don’t happen to know what’s so tricky about cache invalidation ;-) But I can hardly remember any technical problem that caused me as much of a headache as these few names did. I hope that after so many discussions, this new API will prove to be simple to understand and to use.

Thanks to Frank, Rüdiger, Holger and Jordi for great discussions and especially to Frank for contributing this new API to RAP!

The changes are part of RAP 1.5M7, published this Friday, May 11.