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:

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

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:

<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. 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.

Just enable the markup support for a certain widget (see below), then you can make its text bold, italic, yellow or … no, not blinking! Actually, RAP will validate the markup and allows only a selection of tags (no <script> tags, please!). But since the <img> tag is in that list, you can add a smiley instead .

Table table = new Table( parent, SWT.BORDER );
table.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
TableItem item = new TableItem( table, SWT.NONE );
item.setText( "Some <em>text</em> with <strong>markup<strong>" );

This also means that you don’t have to break your neck anymore just to add an HTML link to your RAP UI. You can now place real links in any Label or CLabel:

Label label = new Label( parent, SWT.NONE );
label.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
label.setText( "<a href=\"http://eclipse.org/rap\" target=\"_blank\">RAP project page<a>" );

Don’t like the setData() programming? We don’t like it either. But for now, it’s the simplest way to expose additional functionality without changing the SWT API. For RAP 2.0, we plan to come up with some better API for our extensions.

Try out the markup support in our updated online demo! BTW, did you notice that this is a deep link into the demo application? Yes, there was a bug preventing them from working in RAP for long, and it’s now finally fixed! You can now use the BrowserHistory to navigate to a certain point in your application right on startup. Here’s the link to an example page that shows markup in a Table.

And there are more Table and Tree enhancements, such as the fixed columns support that lets you exclude one or more colums from horizontal scrolling. Check out the full list of changes in the New & Noteworthy.

Get it while it’s hot, this milestone is a must have

A while ago, we’ve tried to use JSLint, a tool written by JavaScript guru Douglas Crockford. Unfortunately, this tools produces several thousand warnings on our code base, many of them were not really problems but debatable coding style issues and there was no way to turn them off. JSLint’s lack of customizability recently lead to a fork named JSHint that is going to provide more flexible configuration options.

Like JSLint, JSHint is written in JavaScript, but can be run on the command line using tools like Rhino or JavaScriptCore. I tried JSHint on our codebase with good results using a shell script that runs it on top of Rhino. Unfortunately, checking all our 250+ *.js files keeps my machine busy for 5 minutes and 40 seconds and effectively turns it into a fan heater. This is not because JSHint itself is so demanding, but because for every file, a JVM has to be started, Rhino has to be loaded, then Rhino has to parse and load the JSHint JavaScript library, and then finally, jshint can parse and validate the source file.

Encouraged by the good results I tried to find a solution that doesn’t have this overhead. And as an Eclipse hacker and user, I certainly wanted to integrate the tool into my daily working environment. The result is a simple, yet efficient JSHint Eclipse integration that validates the same bunch of *.js files in less than 15 seconds.

This speedup could be achieved by exploiting the way Eclipse builds projects: It uses the same builder instance to visit all files of the project recursively. That makes it possible to load and configure the JSHint library only once for the entire project and reuse it for all files being checked. Of course, validating all files of a project is only necessary for a full rebuild. During normal work, single files are being validated instantly when they have changed.

Although the configuration options are still somewhat basic, this integration proved to be very helpful already. I thought that it may be useful for others as well and decided to build and publish a first version. It’s available on the jshint-eclipse page. There’s an update site that let’s you install the plug-in right into your Eclipse IDE. If you find the plug-in useful, have ideas for improvements, find a problem or want to contribute, I’m happy to hear about it. To report problems, please use the github issue tracker.

One of our goals for RAP 1.5 is to open the framework for alternative client implementations. After all, the messages from the server contain precise rendering commands that are not at all specific to JavaScript. Commands like “create a button with text ‘Ok‘, set its size to 190x25px, and place it at pos (23,42)” or “change the text color of the label with id ‘w47‘ to ‘#ff0000‘” can be rendered by any client that is able to create and manipulate widgets. It doesn’t have to be a JavaScript client, also clients written in other languages like Java or Objective C can implement it. Clients can render widgets with any UI technology, be it SVG or even a mobile device’s native widget set.

To allow for those cases, we exchanged the communication format with a simple predefined format based on JSON. With the M4 build published today, all responses from a RAP server are now plain JSON. This also makes the debugging much easier, since developer tools like Firebug display the structure of a message.

When designing the protocol, we took great care not to limit the exchange format to widgets. Instead, we created a generic synchronization protocol for any kind of objects. Objects are identified with a unique id, and every operation is related to a target object that is referenced by its unique id. There are different types of operations: one to create an object, one to destroy it, one to change some properties on an object, etc. Every message from the server contains a list of operations, besides some meta information.

You’ve guessed that we already have some prototypes for alternative RAP clients in progress. We’ll write about them soon…

On Thursday morning, Paul Petershagen of Vitaphone, a global provider of solutions in the telemedicine sector, will share their experience with a large RAP/RCP single-sourcing project. This is an good example of the power of single-sourcing. Paul also has some insights and figures from the project manager’s perspective.

Later that day, Frank Appel, one of our project pioneers, and me will show how RAP now supports the development of lightweight, modular, and dynamic web applications based on OSGi. This talk is 30 minutes so will not go into too much technical detail – instead, we’ll  show some cool examples and explain the new possibilities.

For those who want to understand the technical side better and try out the new features right away, we offer a 1.5 hours hands-on tutorial on Friday. In this tutorial, we’ll show how to create and structure your RAP project, and also how to build and deploy it using tycho. Frank, Rüdiger, Holger, and me will be around so you will have first-class support. By the way, did you know that RAP finally supports clustering? If you have specific questions about this feature, Friday is your chance to meet Rüdiger, who has been working on this stuff over the last months.

And, last but not least, we are happy that another Eclipse project has decided to build on RAP: the Scout project provides a framework for rapid development of complete enterprise applications. With the upcoming Juno release, Scout will provide a RAP integration. Project leads Matthias Zimmermann and Andreas Hoegger will present “the best of both worlds” on Thursday afternoon.

You will always find one of us at the EclipseSource booth. I hope to meet you in Ludwigsburg!

Update: APIs have changed a bit meanwhile, so I updated the code below accordingly. Entry points are now registered by path, and JEE_COMPLATIBILTIY has become the default mode, which makes the main loop obsolete in this kind of applications.

RAP is well known as an “RCP for the web browser”, including workbench, extension points, and all that stuff. Indeed, one of the greatest features of RAP is its ability to reuse RCP code in web applications. But did you know that you can also use RAP’s widget toolkit (RWT) to create simple web UIs for your applications, without the heavy weight Eclipse UI stack?

With RAP 1.5, you can now simply include RWT in any OSGi application. You only need two bundles: org.eclipse.rap.rwt (the RAP widget toolkit itself) and org.eclipse.rap.rwt.osgi which integrates RWT with the OSGi HTTP service. There are no tie-ins with Equinox anymore, thus RAP also works with other OSGi containers.

To create a UI with RWT, you have to implement the interface IEntryPoint, here’s a simple example:

  public int createUI() {
    // Create a maximized top-level shell without trimmings that represents the main "page"
    Display display = new Display();
    Shell page = new Shell( display, SWT.NO_TRIM );
    page.setMaximized( true );
    page.setLayout( new GridLayout() );
 
    // Create contents of main shell
    Label label = new Label( page, SWT.NONE );
    label.setText( "Hello" );
    Button button = new Button( page, SWT.PUSH );
    button.setText( "World" );
 
    // Open the top-level shell and run the main loop to process events
    page.layout();
    page.open();
    return 0;
  }

Now what’s new is that, instead of registering this entry point with an extension point, you can now implement the new ApplicationConfigurator interface like this:

  public void configure( Context context ) {
    context.addEntryPoint( "/simple", SimpleEntryPoint.class );
    context.addBranding( new AbstractBranding() {
      @Override
      public String getServletName() {
        return "simple";
      }
      @Override
      public String getTitle() {
        return "Simple RWT Example";
      }
    } );
  }

When this implementation is registered as an OSGi service, you can access the UI with a web browser:


You can check out the example project example.rwt.simple from my rap-helpers repository on github. Please note that for this example to run you need declarative services in your target platform, which are not included in the RAP 1.5M1 target but in the latest nightly build. Also be aware that the new API is still provisional and may change again until the final release.

Kudos to Frank Appel, who contributed the new OSGi integration. He has a more detailed introduction to the new OSGi integration and examples for configuration in his blog. BTW, Frank and me plan to demo the possibilities of this approach in our talk Dynamic web applications with OSGi and RAP at the EclipseCon Europe – vote for it if you’re interested!

I thought that this data would be a good example to show the ability of the new Tree widget in RAP to display huge datasets.

It’s clear that you cannot create half a million UI elements in a browser without running out of memory. Neither can you load the entire dataset (> 2GB on disk) into memory on the server. You need a mechanism to load and display data on demand.

As of this week, the RWT Tree widget has full SWT.VIRTUAL support, i.e. it is capable of creating Tree items only at the moment they become visible. This feature is used by the JFace TreeViewer to request data from a lazy content provider on demand.

So, in order to make a complex data set accessible with a web UI, you just need to write an ILazyTreeContentProvider implementation. That’s about one screen of Java code, mostly copied from a JFace snippet. That’s all.

Check out the example on our online demo (navigate to the tab called Complex Data). The source code of this demo page is available on github.

Full SWT.VIRTUAL support for the Tree widget is available in CVS and will be part of RAP 1.5M1.

The FileUpload is a new widget that wraps the HTML file selection <input> tag. It looks like a button, and when it’s pressed, a native file dialog opens up that lets users select a file from their local file system. On file selection, a SelectionEvent will be fired. You can then programmatically upload the selected file to an http server using FileUpload.submit( URL ).

In order to receive and store the uploaded files on the server, you also need a server-side component. We created such an upload server component in the RAP Incubator. It’s called FileUploadHandler and it uses the Apache fileupload component internally. It’s included in the bundle org.eclipse.rap.rwt.supplemental.fileupload. This handler accepts file uploads to a certain URL (FileUploadHandler.getUploadUrl()) and delegates the data to a FileUploadReceiver. You can either use the provided DiskFileUploadReceiver or create your own receiver to do whatever you like with the uploaded data: put it into a database, or simple analyze the data and discard it.

Sounds complicated? Well, there’s a much easier way to upload files with RAP 1.4! We’ve encapsulated the entire upload process in an implementation of the SWT FileDialog, which is also available in the incubator.

To make it easy to use, we now provide an update site for the Incubator. To use the FileDialog in your application, all you have to do is to:

1. include the bundles from the RAP Incubator repository http://download.eclipse.org/rt/rap/1.4/incubator/ in your RAP 1.4 target platform, and
2. add a bundle dependency to org.eclipse.rap.rwt.supplemental.filedialog to your project (yes, you have to use Require-Bundle here because this bundle contributes a class to the org.eclipse.swt.widgets package, effectively creating a split-package).

That’s all. Now you can use the FileDialog just like in SWT:

  FileDialog fileDialog = new FileDialog( shell, SWT.TITLE | SWT.MULTI );
  fileDialog.setText( "Upload Files" );?
  fileDialog.setAutoUpload( true ); // This API will change, see below!
  fileDialog.open();
  String[] fileNames = fileDialog.getFileNames();

After uploading, the dialog closes and the variable fileNames contains the absolute file names of the uploaded files on the server’s file system. There’s an auto-upload feature that is really nice (I think it should be the default) – with autoUpload on, the upload starts immediately after file selection. A user can still press Cancel to prevent the application from using the uploaded files.

Note: Please note that this stuff is in the incubator and not part of the 1.4 release. The API and implementation may (and will) have to change and mature over time. However, if you use the latest version from 1.4/incubator site, you’ll always get a file dialog that will work with RAP 1.4. The server-side upload receiver and the required Apache bundles are also included.

We hope you enjoy these new features. Please try them out, tell us what you think, open bugs for the new stuff, and help us improving them.

Kudos to our new RAP committers Austin Riddle and Cole Markham who created this great new feature!

Update: I mistakenly left out the “.rwt.” from the bundle namespace in the original post, the bundle names are fixed now in the text.

Update: The 1.4 incubator repository has been updated with a newer version of the file dialog that is compatible with RAP 1.4. This update fixes the problem with missing file names mentioned in the comments.

In M7, we now introduce a simple way of doing this. Let’s first have a look on how you would implement a key binding in SWT. You would have to register a global listener for key events on the display like this:

display.addFilter( SWT.KeyDown, new Listener() {
  public void handleEvent( Event event ) {
    if( event.stateMask == 0 && event.keyCode == SWT.ESCAPE ) {
      // handle escape key
    }
  }
} );

Well, you can now use the same code in RWT.

But there’s one more thing to it: RWT is a client-server architecture and we don’t want the browser client to send a request for each and every key stroke. The server should only be notified when the user presses one of the key sequences that we are really interested in. Therefore, we have to inform the client, which key sequences should be active. This information can now be attached to the display using Display.setData() with the new constant RWT.ACTIVE_KEYS as property key. The value of this property must be an array of strings, each one representing a single active key sequence. The syntax is the same that you know from key binding extensions for the workbench. So if you want to enable some simple key bindings like, for example, “c” for compose and “x” for delete, and maybe some more advanced key sequences like “Ctrl+F11″ for power-users, you could write something like this:

display.setData( RWT.ACTIVE_KEYS, new String[] { "C", "X", "CTRL+F11" } );
display.addFilter( SWT.KeyDown, new Listener() {
  public void handleEvent( Event event ) {
    if( event.stateMask == 0 && event.character == 'C' ) {
      handleCompose();
    } else if( event.stateMask == 0 && event.character == 'X' ) {
      handleDelete();
    } else if( event.stateMask == SWT.CTRL && event.keyCode == SWT.F11 ) {
      doSomeAdvancedStuff();
    }
  }
} );

Only the first line is RAP-specific. So for a single-sourcing RWT/SWT application, you only have to care about the constant. I’m sure you have an idea how to do that. M7 will be available on May 7–easy to remember.

*) Some shortcuts may be reserved by some browsers and cannot be used. Other shortcuts will override browser actions, like Ctrl-N (new window) Ctrl-T (new tab) etc. You also may not like to disable C&P in form fields by adding key bindings for Ctrl-C etc. So you have to choose your web key bindings wisely… Ah, and sequences of key strokes like Ctrl+X T are not yet supported.

In this milestone, we conentrated on optimizations to the Javascript code that we deliver to the client browser. We managed to reduce the size of this code by ~8%, making RAP apps load a litte bit faster again. More optimizations will follow.

As a nice side effect of using a new Javascript compressor, RAP does not interfere with JQuery anymore. That means that you can now use JQuery in your RAP applications, if you like.

In the next milestone, scheduled for Dec 17, you can expect updated JFace and Workbench bundles as well as key bindings support.