Launch Shortcuts

If you are doing Test Driven Development you have to run your tests quite often. Obviously it gets somewhat tedious using e.g. the context menu of the editor to select the Run As -> JUnit Test to launch a test case under development. Fortunately the shortcut Alt+Shift+X,T does the same and Alt+Shift+D,T executes the test in debug mode. But there is more in that than meets the eye.

Consider the following situation: a unit under test does not work as expected anymore. You have recognized this because a certain test of your test suite fails. Having a look at the code might not be conclusive so you decide to start a debugging session. To do so you set a breakpoint at the current cursor position (Ctrl+Shift+B). In such a case you are probably not interested in re-running the suite or even all the tests of the given test class. You only want to launch the single failing test³.

Now it is important to know that the ‘Run as’ shortcuts described above are sensitive to the editor’s cursor position. Moving the cursor to a test method name allows to use those shortcuts to launch a JUnit process that runs this test method only⁴⁵.

Carrying on the example a little bit it is very likely that you will find a suspicious spot in your unit under test during the debugging session. Considering a solution you might change some code of that unit. After that you want to see if the test method still fails. Luckily there is another shortcut in Eclipse that allows you to re-run the latest executed launch configuration.

Use F11 to re-run your debug session and Ctrl-F11 to re-run the test method normally. However there is a preference setting that have to be set to make this work reliable. After opening the Launching preference page (Windows -> Preferences | Run/Debug -> Launching) there is a section called Launch Operation. Ensure that the Always launch the previously launched application radio button is selected.

Method Templates

Every time you are about to create a new test method you might consider using Eclipse editor templates to improve your coding efficiency. Once you have positioned the cursor at the location where the new test method should be located type test and hit the Ctrl+Space shortcut to pop up the content assist.

As shown in the first part of the picture above the content assist offers a test method template that will create a complete method stub on selection. Unfortunately this would be a JUnit 3 style method stub. But hitting Ctrl+Space again will reveal a second template that is written in JUnit 4 style. This is shown in the second part of the picture above.

In spite of all hitting the shortcut twice still seems to be too cumbersome for many developers. And writing test cases you often have to create setup and/or teardown methods annotated with the @Before/@After tag as well. But thankfully it is possible to provide your own editor templates in Eclipse. Holger Staudacher has written a good post called Simple JUnit4 templates for Eclipse where he explains how to do this and even provides a set of templates in a gist.

Favorites

JUnit tests rely heavily on the usage of the various assertXXX methods provided by the class junit.framework.Assert. Those methods are all declared as static and can be referred to as Assert.assertTrue(condition) for example. But as far as I know most people would use static imports to shorten the statement for the sake of readability to assertTrue(condition).

But by default the IDE’s content assist will not suggest the static methods of the Assert class. One way to get around this is to write the class name and let the content assist propose the available methods. The latter might be accelerated by using camel case matching. After that the use of Ctrl+Shift+M as described in Rüdiger’s post about static import shortens the statement and generates the import.

However I think the most efficient way is to configure the junit.framework.Assert class as content assist favorite to allow the proposal of the static members even if the import is still missing. The configuration takes place in (window -> Preferences | Java -> Editor -> Content Assist -> Favorites) and looks like this:

JUnit View Configuration

While working test driven running your tests regularly gets practically organic ⁶. However running a larger test suite takes some time. In the meanwhile the JUnit View pops up and continously updates the list of test results. But this can get enervating as it is distracting in the best – or even obstructing your work in the worst case.

With test driven development you expect your tests to succeed at a rate of 100%. And because of this many developers want to be informed about failing tests only – the exception of the rule. The JUnit view supports this with a configuration setting called Activate on Error/Failure Only available via the viewpart’s menu:

Every now and then your test suite will fail and there may be more than one problem at once. By default the JUnit view lists all test results. But as a developer you’re generally more interested in the failing ones and may percive the bulk of green tests as clutter. Here focus on your work means focus on the failing tests. There is a configuration setting called Show Failures Only available to change this behaviour. As people tend to change this setting more frequently a toggle button in the viewpart’s toolbar is provided.

Fast View

If your are working with Eclipse 3.x there is a nice feature called Fast View that allows to unclutter your UI a bit. In general I prefer this for views that I use regularly but not continously and/or for views that I consider more lucid if provided with more space. Examples for this might be the Coverage-, History- or the Call Hierarchy view. A viewpart tab provides a content menu that makes it possible to use a view as fast view:

This removes the view from its stack and shows a toggle button in the fast view toolbar at the left bottom corner of your workbench. With this button you can activate/deactivate a particular view as overlay⁷:

A specific feature of the JUnit fast view button is that it provides status info about the latest test run or progress info about a currently executed one. So this little button is all the UI you need for a good deal of the time you spent with JUnit:

Unfortunately fast views are no longer available in Eclipse 4.x. But there is a workaround that meets the behavior to a certain degree. You can move the views you want to use as ‘fast views’ into a designated view stack and minimize this stack. The toolbar representing the minimized view stack now serves as the former fast view bar. This works so-so as the activation/deactivation sometimes hangs and you have to fiddle a bit to hide the view and get back to the editor for example.

In essence I think the sections above are covering the main points we were talking about in the disscussion I mentioned at the beginning of this post. Maybe you also have some infos about useful JUnit shortcuts, using patterns or the like to share – feel welcome to add a comment.

While it is natural for me to write the service classes test driven using plain JUnit tests it is also very important to provide additional integration tests. Those tests allow to check runtime availability and functionality of such services. To provide the latter I used another little helper written by Holger – restfuse which is a JUnit extension for automated HTTP/REST Tests.

The scenario looks somewhat like this:

A service

@Path( "/message" )
public class SampleService {
  
  @GET
  @Produces( MediaType.TEXT_PLAIN )
  public String getMessage() {
    return "Hello World";
  }
}

A JUnit test case

public class SampleServiceTest {
  
  @Test
  public void testGetMessage() {
    SampleService service = new SampleService();
    
    String message = service.getMessage();
    
    assertEquals( "Hello World", message );
  }
}

The service registration

<?xml version="1.0" encoding="UTF-8"?>
<scr:component
  xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
  name="SampleService">
   <implementation class="sample.SampleService"/>
   <service>
      <provide interface="sample.SampleService"/>
   </service>
</scr:component>

The restfuse integration test

@RunWith( HttpJUnitRunner.class )
public class SampleServiceHttpTest {
  
  @Rule
  public Destination destination
    = new Destination( "http://localhost:9092" );
  
  @Context
  private Response response;
  
  @HttpTest( method = Method.GET, path = "/services/message" )
  public void checkMessage() {
    String body = response.getBody( String.class );
    assertOk( response );
    assertEquals( MediaType.TEXT_PLAIN, response.getType() );
    assertEquals( "HelloWorld", body );
  }
}

The running service

While all of this was quite straight forward it bugged me somehow that running the integration tests locally required first to launch the server before I was able to execute the integration test. Preoccupied by the task at hand I often forgot to launch the server and ran into connection timeouts or the like.

But I found a solution for this by using a PDE JUnit launch configuration, because such a configuration can be setup to start the server within the process that runs the tests.

To do so create and select a test suite that contains all the integration tests to run¹…

…after that switch to the main tab and select the headless mode…

… and last but not least configure the program arguments used by the server which in our case basically concerns the port definition.

The bundle selection in the Plug-ins tab contains the same bundles as those of the osgi launch configuration that is used to run the server standalone plus the JUnit-, PDE JUnit-, restfuse-bundles and their dependencies. The selected test suite may looks like this:

@RunWith( Suite.class ) 
@SuiteClasses( {
  SampleServiceHttpTest.class
} )
public class AllRestApiIntegrationTestSuite {
  
  public static String BASE_URL
    = "http://localhost:" 
    + System.getProperty( "org.osgi.service.http.port" );
}

The only unusual thing here is the BASE_URL constant definition. As mentioned above the server port of the test run is specified as a program argument in the launch configuration. But restfuse tests need to provide the port during the destination rule definition. Using the approach above allows to change the port in the configuration without affecting the tests. Simply use the constant as parameter in the definition as shown in the following snippet²³.

 @Rule
  public Destination destination
    = new Destination( BASE_URL );

This simple setup worked out very well and improved my workflow of running the integration tests locally. And saving the launch configuration in a shared project easily enables your team mates to reuse it.

So this is it for today and as always feedback is highly appreciated. By the way, Holger promised me to write a post about how to integrate that stuff described above into a maven/tycho based build⁴ – so stay tuned

While in the early days you always had to do the slot “What is RAP” and “How does it work” nowadays the majority of the people I speak to are pretty familiar with the technology. Even more I had very interesting conversations about how people use RAP, how they adopted the single sourcing approach with RCP and what they expect from the future development streams.

So I was very pleased to see that there is a huge interest in the native UI support of smartphone and tablets that RAP will offer within the next release. The underlying protocol implementation of the server-client communication needed for this, has been on the backlog for years, but so long there have not been a use case that justified the investment. Kudos goes to Holger doing the groundwork here.

The discussions also affirmed me that the RAP team is on the right track to press ahead with improving the RWT standalone capabilities and as a result of that the integration possibilities with containers like OSGi, Spring etc.

So if you missed the show here is a recording of the talk Ralf Sternberg and I were given at EclipseCon Europe:

Although I have finished my list of current sessions there are still opportunities to see the talk live as Ralf, Holger and Markus will present it at the following Eclipse democamps:

Hamburg, 23th November
Kaiserslautern, 24th November
Karlsruhe, 29th November
Vienna, 2nd Dezember

So if you want your piece of the 10 years of Eclipse birthday cake register now

The Example

Again I start with a short walk through of the example’s main functionality. The main development concepts behind the scenes are covered in the next section. Once you have imported the example projects into your Eclipse workspace you can use the RWT-OSGi-ConfigurationAdmin launch configuration contained in the configuration admin project to start the example.

As shown in the last post we can use the following console commands to start the example application:

startHttpService 10010
deployApplication ExampleUI1 10010

We are able to access this application in the browser using the URL “http://localhost:10010/example”:

The screenshot above shows basically an empty web application frame that is bare of any content yet. To change this use the following console command:

deployUIContribution HomePageTab ExampleUI1 10010

Well, on first sight the changes are not that impressing either. But actually the command added dynamically content to our application:

Using the command “ss” at the “osgi>” prompt provided by our UI contribution clarifies what our contribution is all about:

Having a console session available in our web application we can use it just as well to contribute further functionality. Using the command as shown in the following screenshot…

… contributes a new UI element to the application:

I think that is enough to grasp the basic idea of the example, so let us have a look into some of the programming details.

Behind the scenes

In our example application we use a little helper called UIContributorTracker³ to contribute content dynamically to RWT based web applications⁴. As the name implies it tracks UI contributions provided by instances of UIContributor. UIContributor implementations are meant to be used as UI builders and each contribution type is declared as OSGi service. The UIContributorTracker implementation uses a ServiceTracker to track the lifecycles of such contributions.

public interface UIContributor {
  String getId();
  Control contribute( Composite parent );
}

As you can see the contributor interface is straight forward. It demands an identifier that can be used by implementations of user interaction⁵ to identify and activate a certain contribution. Furthermore it provides the actual builder functionality that allows to embed UI contributions into the RWT based web frame application. A simple implementation may look like this:

public class HelloWorld implements UIContributor {

  @Override
  public String getId() {
    return "Hello";
  }

  @Override
  public Control contribute( Composite parent ) {
    Label label = new Label( parent, SWT.NONE );
    label.setText( "Hello World" );
    return label;
  }
}

The respective OSGi service declaration will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
  name="HelloWorld"
  configuration-policy="require">
  <implementation
    class="com.codeaffine.example.rwt.osgi.ui.example.HelloWorld"/>
  <property name="type" type="String" value="page"/>
  <service>
     <provide
    interface="com.codeaffine.example.rwt.osgi.ui.platform.UIContributor"/>
  </service>
</scr:component>

Nothing spectacular in it especially if you are familiar with the previous posts. We use the configuration-policy to keep the declared service dormant until it is explicitly invoked by the configuration admin service. The property “type” will be used in an LDAP filter expression to distinguish between different kinds of UI contributions. In the “HelloWorld” case above we decided that the contribution is used as an additional page. In our example webapp page contributions are presented to the end-user as selectable entry in the navigation bar.

Using the following command…

deployUIContribution HelloWorld ExampleUI1 10010

… will integrate the “HelloWorld” contribution into the running example instance:

That was not too difficult, was it?

Before comming an end I want to point out some of the noteworthiness things about the UIContributorTracker mentioned above.

• The tracker is intended to be extended. Implementers may override e.g. the. addingService() method.
• The tracker implementation relies on an OSGi ServiceTracker that is registered as an OSGi service itself. UIContributorTracker instances gain access to UIContributor services using this global tracker service. This approach allows that each contributor has only one reference counter and can be deregistered again easily. Contributor registration and deregistration events are broadcasted to the registered ContributorTrackers. So despite of the name the UIContributorTracker is not an OSGi service tracker.
• The tracker implementation already takes care of the background threads that notifies about service lifecycle changes. Updates of RWT UI elements are only allowed using the appropriate UIThread. Therefore the tracker decouples the background thread from the actual work of creating the UI parts using a callback functionality provided by RWT.

Here is a snippet that shows how the tracker can be used:

@Override
public UIContributor addingService( ServiceReference<UIContributor> reference, UIContributor service ) {
  if( ConfiguratorTracker.matchesType( "BundleUpload", reference ) ) {
    bundleUploadContributor = service;
    updatePage();
  }
  return result;
}

The code above shows how the added UIContributor service is used only in case of a matching contribution type. As mentioned above the contribution type is specified as a service property e.g. at service declaration time. The contributor is buffered⁶ and the call of updatePage() will supplement the contribution to the current page content by calling UIContributor#contribute(Composite) on the given contributor instance.

Conclusion

Although we do not have an out of the box application framework to create OSGi based web applications with RAP/RWT at the moment, I showed that there is already a lot of infrastructure available and with a little hands-on skills you can build some quite effective web apps on top of it⁷.

Last but not least I like to mention that a fellow developer, Ralf Sternberg, and I will talk at EclipseCon Europe about Dynamic Web Applications with OSGi and RAP. We also have a tutorial slot Lightweight, Dynamic Webapps Made Easy with RAP and OSGi that will go more into details of things. So if you interested and you happen to be at the event – don’t be shy, just drop by

The Example

I start with a short walk through of the example’s main functionality. Some of the development details behind the scenes are covered in the next section. The example project contained in the source repository mentioned above includes a launch configuration called RWT-OSGi-ConfigurationAdmin. After launching it we can type “help” ² into the OSGi console window of the newly created process. This displays a list of the commands available to control the system.

Those who are familiar with the equinox console will detect a new block:

---Configuration of ApplicationLauncher---
	startHttpService <port>
	stopHttpService <port>
	deployApplication <configurator name>|<port>|<contextName(optional)>
	undeployApplication <configurator name>|<port>|<contextName(optional)>

With the first two commands we can start and stop an instance of HttpService. The service will be bound to the port specified by the command parameter:

The screenshot shows the print out after starting two http service instances, one at port 10010 and one at 10020. Pointing your browser to the URL http://localhost:10010/ or http://localhost:10020/ respectively shows that the services are alive but return an HTTP 404. This is quite ok since we did not register any resources yet to be found. We will change this by typing:

Using the URLs http://localhost:10010/helloworld or http://localhost:10020/datepicker now show the following applications:

So the example enables us to start/stop http services dynamically in one process and deploy/undeploy³ various RWT applications at those services. The latter uses the port property of the http service as binding selector. Quite nice I think But actually it does a little bit more. Stopping and restarting the process shows that the latest configuration has been stored⁴. The system will start up the two services and deploy the RWT applications again to those services:

Behind the scenes

To be able to start and stop the http service instances we use the managed service factory implementation provided by the jetty⁵ control bundle. You can find the service in our example above using the services console command:

osgi> services org.osgi.service.cm.ManagedServiceFactory
{org.osgi.service.cm.ManagedServiceFactory}={service.pid=org.eclipse.equinox.http.jetty.config, service.id=40}
  Registered by bundle: org.eclipse.equinox.http.jetty_2.0.100.v20110502 [12]
  Bundles using service:
    org.eclipse.equinox.cm_1.0.300.v20110502 [6] 

Looking at the print out we also recognize the service.pid property which I use in the CommandProvider implementation to create a new http service configuration at runtime:

private Configuration createHttpServiceConfiguration()
  throws IOException
{
  ConfigurationAdmin configAdmin = getConfigurationAdmin();
  String location = findHttpServiceManagerLocation();
  String PID = "org.eclipse.equinox.http.jetty.config";
  return configAdmin .createFactoryConfiguration( PID, location );
}

The location is the location attribute of the jetty bundle that registers the factory. We can use the configuration created above to start a new equinox jetty based http service at a given port:

[...]
  Configuration configuration = createHttpServiceConfiguration();
  configuration.update( createHttpServiceSettings( port ) );
[...]

private Dictionary<String, Object> createHttpServiceSettings( String port ) {
  Dictionary<String,Object> result = new Hashtable<String, Object>();
  result.put( JettyConstants.HTTP_PORT, Integer.valueOf( port ) );
  result.put( JettyConstants.CUSTOMIZER_CLASS,
                 "org.eclipse.rap.jettycustomizer.internal.SessionCookieCustomizer" );
  return result;
}

The Configuration#update(Dictonary) method starts the service and persists its configuration. This allows the system to restart the service with the same configuration during the next lauch.

Note that the http service settings use constant definitions of the particular HttpService implementation. Therefore this will not work with another service implementation.

Now let us have a look at how to start and bind an RWT application to such an http service instance. The example provides several ApplicationConfiguration service declarations that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
  immediate="true"
  configuration-policy="require"
  name="helloWorld">
  <implementation
    class="com.codeaffine.example.rwt.osgi.configurationadmin.applications.HelloWorldApplicationConfiguration"/>
  <service>
     <provide
       interface="org.eclipse.rap.rwt.application.ApplicationConfiguration"/>
  </service>
</scr:component>

The interesting part for us is the property “configuration-policy” of the “component” tag. Setting it to “require” allows us to use the configuration admin to deploy RWT applications on various http services:

Configuration configuration = configurationAdmin.createFactoryConfiguration( configurationName );
configuration.update( createApplicationSettings([...], port, [...]) );

Where createApplicationSettings(…) creates the property that is used to bind the
application to a certain http service. The property uses the port number as selector in a filter expression. In case the binding should be done to an http service on port 10010 it would look like this:

httpService.target=(http.port=10010)

Conclusion

In this post I gave an impression of the possibilities using RWT in conjunction with the ConfigurationAdmin service. So if you want to play around with the stuff or want to look at the implementations in more detail simply pull the example from the repository. But keep in mind that the example is only meant for demonstration purpose and not intended to be production ready.

Now that we have seen how to start and stop RWT applications dynamically there is still the question of how to contribute UI elements dynamically to a running application – but this is a story I will probably cover in another post..

Last but not least I like to mention that a fellow developer, Ralf Sternberg, and I will talk at EclipseCon Europe about Dynamic Web Applications with OSGi and RAP. So if you interested and you happen to be at the event – don’t be shy, just drop by

During my time as RAP technology lead I took care of some consulting projects using RAP/RCP in single sourcing fashion. Although this approach has proven very powerful to help people to bring their RCP applications to the web, I consider the workbench concept often too cumbersome if you are writing pure web applications from scratch.

Hence it was a logical step to put the workbench aside and use only RAP’s widget toolkit (RWT) as standalone library in OSGi environment for some project work. Unfortunately this did not work out as easy as it sounds and it needed a little bit of insight knowledge (which I fortunately had) to get this done. As I was working with this approach for a while I was able to pick up experience about what refactorings and extensions would be needed to provide RWT as genuine OSGi service component out of the box.

Luckily I had some time in the first half of the year 2011 and so I could start with the refactorings. In the meanwhile I continued working on the RWT-OSGi integration and I am happy to say that the this integration is available with RAP 1.5.

RWT OSGi Integration

So what is it all about?

As I said above with the latest RAP version you can run RWT standalone as OSGi service without the need of the workbench and equinox-registry related stuff. Therefore you are not bound to a specific OSGi implementation anymore. So far I found the time to test this at least with equinox and felix.

How is it used?

The next two sections introduce the newly provided ApplicationLauncher functionality. First I show how to use the service programmatically for a better understanding of how things play together. After that I explain my preferred way of using it in a declarative manner.

Service API

In this section I assume your application is providing an up and running service instance of HttpService ¹. Add the RWT- and the RWT-OSGi integration bundle to your application and you are ready to go ². Using a programmatic approach you have to retrieve the HttpService instance and the ApplicationLauncher instance (provided by the RWT-OSGi integration bundle) to wire both together. Retrieving the services can be done using ServiceTracker ³.

Once you have both services the third thing you need is a configuration for your application. The newly provided ApplicationConfiguration API allows to register themes, branding information, entrypoints etc. at the application you are about to start. A simple configuration implementation may look like this:

public class HelloWorldConfiguration
  implements ApplicationConfiguration
{

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

As RWT is based on servlet technology the application given as parameter in the configure method also abstracts the ServletContext provided by an servlet container. The configuration is the place where you might register objects which live in application scope. Within your application you might access such objects using RWT#getApplicationStore()⁴.

Now we are able to start an application with the following line of code:

HttpService httpService = [...];
ApplicationLauncher launcher = [...];
ApplicationConfiguration configuration = [...];

ApplicationReference reference
  = launcher.launch(
      configuration, httpService, null, null, "<pathToContextDirectory>");

The pathToContextDirectory points to a directory on the system’s disk where RWT can write static web content files like images, javascript files and so on.

With the third parameter you can provide an HttpContext instance e.g. to allow servlets registered at the http service with the same http context to share sessions with RWT. In the scenario above where we use null as http context parameter an http context will be created internally.

The fourth parameter declares an application context name. In the example above the URL to access our application in the browser may look like “http://myserver:9876/helloworld”. Using “mycontext” as context name parameter the URL would look like “http://myserver:9876/mycontext/helloworld”. The latter allows to run multiple application instances bound to the same http service ⁵. Those instances are completely isolated from each other regarding heap memory and disk storage of static content.

Stopping an application is also very easy. Note that the example above returns an ApplicationReference instance. Calling ApplicationReference#stopApplication() on that instance will deregister the application from the http service instance. It conducts a defined shutdown process of the RWT subsystems and clean up the directory used for static content storage.

Declarative Approach

Given the same setup as in the chapter before registration of a single ApplicationReference gets very easy. Using Felix for example you simply have to add a component declaration to your configuration class. This effectively registers the configuration as a service and the rwt osgi integration does the wiring for you:

@Component( provide=ApplicationConfiguration.class)
public class HelloWorldConfiguration
  implements ApplicationConfiguration
{

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

The entrypoint implementation of HelloWorld may looks like:

public class HelloWorld implements IEntryPoint {

  @Override
  public int createUI() {
    Display display = new Display();
    int shellStyle = SWT.TITLE | SWT.MAX | SWT.RESIZE;
    Shell shell = new Shell( Display.getCurrent(), shellStyle );
    shell.setBounds( new Rectangle( 30, 30, 300, 250 ) );
    shell.setLayout( new FillLayout() );

    Label label = new Label( shell, SWT.NONE );
    label.setText( "HelloWorld" );

    shell.open();
    while( !shell.isDisposed() ) {
      if( !display.readAndDispatch() ) {
        display.sleep();
      }
    }

    return 0;
  }
}

Believe it or not that is all. Launch you application and use an URL that looks like “http://localhost:8080/rap” to look at your first RWT standalone app that runs in OSGi:

But this is not everything you can do with the ApplicationLauncher. Consider a situation where you run two http services in your OSGi server application. One for public access on port 80 and the other for internal adminstration purpose on port 8080. With the approach above the helloworld application would register automatically on both services which is probably not what you want.

Let us assume that we want to register the hello world application only at the http service that runs on port 80. So how do we achieve this? The following example shows an appropriate declaration with jetty http service on equinox:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
  immediate="true" 
  name="helloWorld">
   <implementation
     class="com.codeaffine.rwtosgi.HelloWorldConfiguration"/>
   <service>
      <provide interface="org.eclipse.rap.rwt.application.ApplicationConfiguration"/>
   </service>
   <property
     name="httpService.target"
     type="String" value="(http.port=80)"/>
</scr:component>

In principle this is equivalent to the annotation in the previous example. But look at the additional property definition at the bottom of the declaration. This property represents a target filter that refers to a property that is set on the equinox-jetty based http service. This property specifies the port to which the http service was bound. The application launcher instance recognizes this filter and deploys the newly created application only at the appropriate http service.

Using the configuration admin service you can use the target filter mechanism to dynamically register various rwt contexts on different http services and persist such configurations. But this is a story I will probably cover in another post…

Update 2011/11/05: Changed the technical terms and code snippets used in this post due to the results of the first refinements of the described API.

Update 2012/09/22: Changed the technical terms and code snippets used in this post due to the results of the finalized API.

RAP was basically created to enable RCP developers to build web applications reusing their knowledge and/or codebases. We have coined the term Single Sourcing for this. While RAP has been well adopted in the eclipse community there have always been folks using RWT to build web applications setting the workbench notion of RAP aside. This is quite understandable given the fact that the workbench concept forces you into a certain kind of UI paradigm that does not fit all use cases.

Unfortunately there are some difficulties buried in the depth of the library that hamper the standalone usage scenarios. One of those difficulties is the dated singleton structure used as implementation pattern for certain subsystems of the library. Consider for example multiple OSGi HttpServices in the same OSGi instance that run on different ports. Having RWT applications registered for at least two of those services would cause the singletons to be shared between those apps. This even may work to some extend, but it definitely opens up problems regarding the clean separation between applications on different ports. So I’ve opened a bug (#337787) targeting this problem and volunteered to provide a solution.

Looking into the code I have found over 20 singletons or classes with class variables. Although those classes are not API, but given the widespread use of e.g. the resource manager implementation, simply changing those classes into non singletons and provide a different approach of accessing them would have caused a huge rupture throughout the library’s codebase. So I had to find a less intrusive solution that allowed a step wise refactoring to get rid of the class variables.

Fortunately RWT comes with a comprehensive Testsuite that allows you to do substantial design changes without risking defects or compatibility breaches. So I felt comfortable to do a first “under the hood” refactoring step that reduced the static fields and singletons to exactly one singleton that would hold all the instances. In principle the idea looks like the following:

Singletons like

public class MySingleton {
  private static MySingleton instance = new MySingleton();

  public static MySingleton getInstance() {
    return instance;
  }
}

were refactored to

public class MySingleton {

  public static MySingleton getInstance() {
    return RWTContext.getInstance().getMySingleton();
  }
}

public class RWTContext {
  private static RWTContext instance = new RWTContext();

  private MySingleton mySingleton = new MySingleton();
  // [...] further singleton instances go here

  public static RWTContext getInstance() {
     return instance;
  }

  public MySingleton getMySingleton() {
    return mySingleton;
  }

  // [...] further singleton accessors go here
}

The real implementation of RWTContext is somewhat more complex and uses currently a generic approach due to a problem of keeping the test suites alive. But the code above intends to give you the basic idea. Interested readers may have a look at the bug comments and the CVS history for more information.

Another problem that arose was that not all class variables represented singleton instances in terms of the pattern. Such variables were often simple maps used for buffering purposes controlled by a lot of static methods of the surrounding class. In this case the first step was to refactor the classes internally to match the singleton pattern:

Classes like

public class MyStaticClass {
  private static Map buffer = new HashMap();

  public static Type get( String key ) {
    Type result = (Type )buffer.get( key );
    if( result == null ) {
      result = new Type();
      buffer.put( key, result );
    }
    return result;
  }

  // [...] further methods
}

were refactored to

public class MyStaticClass {
  private static MyStaticClass instance = new MyStaticClass();

  private Map buffer = new HashMap();

  public static Type get( String key ) {
    return getInstance().doGet( key );
  }

  private Type doGet( String key ) {
    Type result = (Type )buffer.get( key );
    if( result == null ) {
      result = new Type();
      buffer.put( key, result );
    }
    return result;
  }

  private static MyStaticClass getInstance() {
    return instance;
  }

  // [...] further methods
}

After that this could be refactored to move the instance to the RWTContext as explained above. Unfortunately this would led to classes that looks somewhat confusing having these ‘makeIt’ and ‘doMakeIt’ like method name pairs all over the place. To clean up the clutter a little bit I split those classes into two before refactoring the getInstance method:

public class MyStaticClass {
  private static MyStaticClass instance = new MyStaticClassInstance();

  public static Type get( String key ) {
    return getInstance().get( key );
  }

  private static MyStaticClass getInstance() {
    return instance;
  }

  // [...] further methods
}

class MyStaticClassInstance {
  private Map buffer = new HashMap();

  Type get( String key ) {
    Type result = (Type )buffer.get( key );
    if( result == null ) {
      result = new Type();
      buffer.put( key, result );
    }
    return result;
  }

  // [...] further methods
}

The next refactoring step was to change the singleton implementation of RWTContext to get a clean separation in case of running RWT in multiple http contexts or services on OSGi. To do so the RWTContext instance is buffered as attribute in the ServletContext instance at web context startup. This allows to use an separate instance for each web context. If a web context and with it the servlet context containing the RWTContext instance is destroyed there will be nothing left over of RWT.

But this left the question of how gaining access to the RWTContext within the library when you use one of the singletons we have successfully refactored to delegate to the RWTContext? Fortunately RWT has already a build in solution for this.

We have had a similar problem accessing instances of classes that are session scoped. To gain access to the session that belongs to the current request there is a class called ServiceContext. The idea behind this is simple: At the beginning of the request processing an instance of ServiceContext is tucked as thread local to the request thread. This instance is released at the end of the processing cycle. The service context is fed with the session, request, response and other useful things. A static accessor (ContextProvider.getContext()) allows us to access the service context throughout the request.

To solve the problem of RWTContext access the service context was enhanced to provide access to the RWTContext instance:

public class RWTContext {
  private static RWTContext instance = new RWTContext();

  public static RWTContext getInstance() {
    ServiceContext context = ContextProvider.getContext();
    return context.getRWTContext();
  }
}

The real implementation here is also slightly more complicated, but basically follows the idea explained above. Internally the service context implementation uses the servlet API to retrieve the ServletContext that contains the RWTContext instance.

Conclusion
The changes described above are committed into CVS Head and seem to work like charm as far as we can see. The main work was done on a rainy weekend, which I judge as a fair amount of time with respect to what have been achieved. Removing the singletons from RWT did not only improve the possibility to use the library standalone. It also enabled some follow up refactorings of the library code itself. In particular it helped to improve the testing infrastructure streamlining the setup and teardown mechanism for most of the test cases.

However as I mentioned at the beginning this was only the first step of a set of refactorings. The next steps will address the way of how RWT is initialized, how it runs within OSGi, how it handles the UI Thread and more. So stay tuned, I’ll keep you posted