Twitter Logo Follow us on Twitter
Project Information About this project

RAP 2.0 Migration Guide

With the move to RAP 2.0, we've cleaned up our APIs and had to introduce some breaking changes. Existing RAP 1.x applications will therefore need some adjustments to work with RAP 2.x. This guide explains the steps to be taken to update existing applications.

Meanwhile, RAP 2.1 has been released. Except for changes to the Remote API (which did not exist prior to RAP 2.0) there are no breaking changes between 2.0 and 2.1.

Java Packages

Package org.eclipse.rwt renamed

The package org.eclipse.rwt has been renamed to org.eclipse.rap.rwt. You need to update your bundle manifest files and your Java code to this change. A brute-force search for “org.eclipse.rwt” may be helpful to discover all occurrences in your workspace.

Classes moved

The interface EntryPoint moved to the package org.eclipse.rap.rwt.application.

Bundle manifests

If you use Import-Package in your bundle manifests (META-INF/MANIFEST.MF files), you have to replace all imports of packages named org.eclipse.rwt* with the corresponding packages from org.eclipse.rap.rwt*, i.e. you have to insert an “.rap” before the “.rwt”.

Java code

Compile errors in your code can be fixed by using Eclipse's Organize Imports feature. To do so, select a single class or an entire project and select Source > Organize Imports from the main menu. If you find it easier, you can also replace all textual occurrences of org.eclipse.rwt with org.eclipse.rap.rwt.

Service components

Note that this change also affects service interfaces. If you're using declarative services, please also adjust your component definition files.

RWT Constants

WidgetUtil.CUSTOM_VARIANT
this constant has moved to the class RWT.
FileSettingStore.FILE_SETTING_STORE_DIR
this constant has changed its value to adjust to the new namespace.

I-prefixed Interfaces

The prefix “I” in interface names like IEntryPoint is a heritage from the Eclipse platform. This deviates from the naming pattern used in SWT and other libraries, and also from the Java class library. Since it is not even used consistently in RAP, we plan to remove the prefix from all interfaces.

Removed classes and interfaces

JSWriter, JSVar, JSListenerType, JSListenerInfo
removed together with the corresponding methods in WidgetLCAUtil and ControlLCAUtil. These classes were used for rendering JavaScript are now obsolete.
AdapterFactory
removed together with the extension point, see bug 344541
ResourceManagerFactory
see bug 348476
AbstractBranding, Header
Use entrypoint properties for branding in RWT applications. See class WebClient.
ILifeCycleAdapter
This interface was never meant to be used or implemented by clients, and you're probably not affected.
JSExecutor
an internal class, but frequently used in application code. Replaced by the new client service JavaScriptExecutor, see Client.getService(), bug 342995

Deprecated classes and interfaces

Where public interfaces have been renamed, we left the old name in place where possible to ease the migration and to leave a clue when adapting your application to RAP 2.0.

Graphics
This class had been used to create shared instances of resources like Color and Font before resource constructors were introduced in 1.3. This practice is problematic because instances created by Graphics cannot be disposed and are not garbage-collected. In RAP 2.0, resources should only be created using the constructors of Color, Font, Cursor, and Image. Graphics also provided methods for test size measurement. We expect that these methods are hardly used by application code and can be replaced by SWT's GC API. To measure a string in a given font, create a GC, set the font, and call the GC methods stringExtent or textExtent. Don't forget to dispose of the GC afterwards.
IServiceStore
The service store is used internally by the framework to store data in the scope of a request. Application developers shouldn't really need this store anymore. If an application needs to store any information in the request scope, it should use the request object directly, i.e. RWT.getRequest().setAttribute(...).
ExternalBrowser
Please use the new client service UrlLauncher instead.

Resource Manager and IResource

The resource manager (IResourceManager) has undergone a rework and has been reduced in its functionality (See the New and Noteworthy). These changes affect the following API:

RegisterOptions

The class RegisterOptions has been removed. If you used RegisterOptions other than RegisterOptions.NONE, your application will continue to work without these options, but your JavaScript code will no longer be compressed and the name of the registered resource will not contain a version hash anymore.

You may consider to minify JavaScript yourself and register a minified version. There are many free tools out there, such as YUI Compressor, Google Closure Compiler, or JSMin. If you need a version hash to prevent caching, you can add a URL parameter like “?nocache=4711” when requesting the resource.

Encoding

The resource manager now registers the bytes from a given input stream as is. If you used to register resources using a method with a charset parameter, please make sure that textual resources are read with the correct encoding by the client. If all your resources are UTF-8 encoded there will be no change to RAP 1.5.

ClassLoader

If you used a method that accepted or used a ClassLoader to register resources, please change your code to use the method register( String, inputStream ). You may have to call ClassLoader.getResourceAsStream( resourceName ) to open an input stream.

Closing InputStreams

The resource manager does not close input streams anymore after registering a resource, (bug 347615). Please double check that you're closing your input streams correctly.

IResource moved

The IResource interface is now only used in the extension point org.eclipse.rap.ui.resources and has therefore been moved to the bundle org.eclipse.rap.ui.workbench. The methods getCharset() and getOptions() have been removed because of the changes described above.

For resources that are registered in an ApplicationConfiguration, the method Application.addResource(…) now accepts a ResourceLoader instead of IResource.

Session Store replaced by UI Session

When working with RAP, you have to deal with two different types of sessions: the servlet container's HttpSession and RAP's UISession (formerly known as session store). Both sessions have a different scope and a different purpose. In recent projects we've noticed that the relationship between the HTTP session and RAP's “session store” led to confusion. By renaming the session store to UI session we hope to make it more clear that both are sessions with a different scope and meaning.

The interface ISessionStore has been renamed to UISession. An instance can be acquired from RWT.getUISession() which replaces RWT.getSessionStore(). The types SessionStoreListener and SessionStoreEvent have been renamed accordingly.

Application Store replaced by Application Context

The new ApplicationContext represents the running instance of a RAP application, it is shared by all UI sessions. This interface replaces IApplicationStore, it can be used to store shared data, and also to obtain application-scoped services such as the resource manager. Just like the UISession is built on the servlet container's HttpSession, the ApplicationContext is built on the ServletContext, and its life cycle is also bound to lifetime of the servlet context. We chose the name ApplicationContext to highlight this analogy.

The interface IApplicationStore has been renamed to ApplicationContext. An instance can be acquired from RWT.getApplicationContext() which replaces the old method RWT.getApplicationStore().

The ApplicationContext can also be used to get a reference of the resource manager and the service manager, e.g. applicationContext.getResourceManager().

Service Handlers

The interface ServiceHandler has been changed. The service method now provides two parameters request and response to the implementation. Developers don't have to obtain the request and reponse objects from static methods anymore.

public class MyServiceHandler implements ServiceHandler {

  public void service( HttpServletRequest request, HttpServletResponse response ) {
    HttpServletRequest request = RWT.getRequest();
    HttpServletResponse response = RWT.getResponse();
    response.setContentType( "text/plain" );
    response.getWriter().write( "Hello!" );
  }

}

The ServiceManager has got a new method getServiceHandlerUrl( String ). Developers should use this new method to obtain the URL to access a service handler instead of assembling the URL manually.

ServiceManager manager = RWT.getServiceManager();
manager.registerServiceHandler( "download", new DownloadServiceHandler() );
String url = manager.getServiceHandlerUrl( "download" );

UICallBack

The class UICallBack is going to be replaced by a new API for server push. Instead of calling UICallBack.activate( id ) to activate the server push, you now have to create a new ServerPushSession and start() it. To deactivate the server push, you call stop() on the same ServerPushSession instance. In contrast to the UICallBack, this can be done directly from the background thread without a UISession context.

final ServerPushSession pushSession = new ServerPushSession();
Runnable runnable = new Runnable() {
  public void run() {
    // do some background work ...
    // schedule the UI update
    display.asyncExec( new Runnable() {
      public void run() {
        if( !widget.isDisposed() ) {
          label.setText( "updated" );
        }
      }
    } );
    // close push session when finished
    UICallBack.runNonUIThreadWithFakeContext( display, new Runnable() {
      public void run() {
        UICallBack.deactivate( "someUniqueID" );
      }
    } );
    pushSession.stop();
  } );
};
UICallBack.activate( "someUniqueID" );
pushSession.start();
new Thread( runnable ).start();

To run code in the context of a UISession, e.g. in order to access a session singleton from a background thread, you can use the new method exec(Runnable) on the UISession instead of the infamous UICallBack.runNonUIThreadWithFakeContext(Display, Runnable).

BrowserHistory replaced by BrowserNavigation

The class BrowserHistory has been replaced by a more general client service BrowserNavigation that provides the same features with slightly different API. Here's an example how to change your code:

// OBSOLETE
BrowserHistory history = RWT.getBrowserHistory();
history.addBrowserHistoryListener( new BrowserHistoryListener() {
  public void navigated( BrowserHistoryEvent event ) {
    String state = event.entryId;
    // restore the application state
  }
} );
history.createEntry( "main", "Main View" );
// NEW CODE
BrowserNavigation navigation
  = RWT.getClient().getService( BrowserNavigation.class );
navigation.addBrowserNavigationListener( new BrowserNavigationListener() {
  public void navigated( BrowserNavigationEvent event ) {
    String state = event.getState();
    // restore the application state
  }
} );
navigation.pushState( "main", "Main View" );

Register EntryPoint and IApplication

RAP applications can not be accessed by startup parameter anymore:

http://hostname/webapp/rap?startup=example   (OBSOLETE)

Instead of this, every entrypoint must have a dedicated path (servlet name):

http://hostname/webapp/example

If you used to register entrypoints by parameter in your extensions, you have to use the attibute path instead:

<extension point="org.eclipse.rap.ui.entrypoint">
  <entrypoint id="example.entrypoint"
      class="example.MyEntryPoint"
      parameter="example"
      path="/example" />
  </entrypoint>
</extension>

To make an IApplication available at a certain path, you have to create a separate entrypoint extension and specify the id of the application extension in the new parameter applicationId.

<extension point="org.eclipse.rap.ui.entrypoint">
  <entrypoint id="example.application.entrypoint"
      applicationId="example.application"
      path="/example" />
  </entrypoint>
</extension>

Branding

Entrypoint mapping

The attributes servletName, defaultEntrypointId, and the element associatedEntrypoints have been removed from the brandings extension point. Instead of adding entrypoints to a branding, a branding can now be bound to an entrypoint by setting the new attribute brandingId in the entrypoint extension:

<extension point="org.eclipse.rap.ui.entrypoint">
  <entrypoint id="example.entrypoint"
      class="example.MyEntryPoint"
      path="/example"
      brandingId="example.branding" />
  </entrypoint>
</extension>

Exit confirmation

The attribute exitConfirmationClass is no longer supported by the branding extension point. The new client service ExitConfirmation should be used instead.

Changes for Custom Components

Custom widgets and other components must now read and write JSON protocol messages using the new RemoteObject APIs on client and server. Components that read parameters from the request or write JavaScript directly, e.g. using JSWriter, will not work anymore.

Please check the RAP Developer's Guide and the RAP 2.0 New and Noteworthy for more information about these new APIs. The CkEditor for RAP is a good example for a custom widget that uses these new APIs.

Please note that the Remote API has changed again in RAP 2.1.

Settings

Development Mode

To start a RAP application in development mode, please replace the VM parameter -Dorg.eclipse.rwt.clientLibraryVersion=DEBUG with -Dorg.eclipse.rap.rwt.developmentMode=true.

Features

The IDs of the features have been changed in order to follow the naming conventions that we use throughout all RAP components.

org.eclipse.rap.feature
contains all bundles from the RAP project. Its old ID was org.eclipse.rap.runtime.
org.eclipse.rap.equinox.target.feature
contains a set of Eclipse and Equinox bundles that are required to run the RAP bundles in an OSGi environment. Its old ID was org.eclipse.rap.runtime.requirements.
org.eclipse.rap.examples.feature
contains the demos and examples for RAP. Up to RAP 1.5, the demo had been included in the rap.runtime feature. Separating examples from the runtime makes it easier to keep the demo out of deployed applications.
org.eclipse.rap.tools.feature
contains the RAP Tools for installation in an Eclipse IDE. Its old ID was org.eclipse.rap.tools.

p2 Repositories

http://download.eclipse.org/rt/rap/2.0/
is the p2 repository for RAP 2.0, to be used in target platforms only. Some bundles declare negative p2 requirements to prevent installing them into the IDE.
http://download.eclipse.org/rt/rap/tools/2.0/
is the p2 repository for the RAP Tools 2.0, to be installed into the Eclipse IDE.