IDE Setup

The first thing you need to do is to download the latest “Eclipse IDE for Java EE Developers“. This package contains everything you need to create web applications and deploy them to the application servers of your choice. As we want to bootstrap the application with Maven, we also need to install additional tools called “m2e” which provide a Maven integration for Eclipse. So, after starting your new IDE, go to

“Help” -> “Install New Software” and paste the p2 repository url (http://download.eclipse.org/technology/m2e/releases) of m2e into the text box. This should look like the screenshot below.

After the installation was successful, you need to restart the IDE.

Create a Project

The next step is to create a new project. Tabris applications run on the server side. So, we want to create a Web-application project. For this go to “File” -> “New” -> “Dynamic Web Project”, which basically creates a JavaEE project.

In my example I have named the project “com.eclipsesource.hello.world” but you can choose whatever name you like.

Maven

To make things as easy as possible we want Maven to manage our dependencies. This involves two steps. Firstly, we want to have the dependencies during development time and secondly, we want Eclipse to put those dependencies in our “lib” folder during deployment time. The first step can be completed easily. Just right click on the newly created project and press “Configure” -> “Convert to Maven Project”.

This adds a pom.xml to our project to which we can later add dependencies. The second step is a little bit more complicated. To have the depencies copied into the “lib” folder we need to create a “Deployment Assembly”. To create this, right click on the project and select “Properties”. In the left hand navigation tree, select “Deployment Assembly”. Within this page we need to add a new assembly. So, click on Add and choose “Java Build Path Entries”.

After pressing “Next” we need to tell Eclipse which build path entry we want to have copied. As we want the Maven dependencies to be copied,  we will choose these.

On your machine the dependency tree may be empty, but this is not a problem. Just select “Maven Dependencies” and press “Finish”. After this you should see the newly created assembly pointing to the “lib” folder.

Add Tabris

After having completed the Maven setup, we can add  a dependency to Tabris because we want to build a Tabris app, right ? So, open the “pom.xml” of your project and go to the dependency section. Select “Add” and search for “tabris”. At this point in time Tabris 1.0 is the current version. Before you select it please make sure that the dependency scope is set to “runtime”.

After pressing OK and saving the pom.xml Eclipse (m2e) will download Tabris and it’s dependencies for you.

Creating the App

To create the hello world application we need just two classes. The first one is a configuration that tells the framework what to do. In our case it should tell the framework that we want a Tabris UI with only one page. This should look like this:

After the configuration is complete, we will need a page. I decided to go with an easy one . It’s just a pink colored page that does nothing.

Basically this is the whole application we want to create.

Configure the Web-Application

One last step is to configure the Web-Application. We need to tell the Application that it should use the ApplicationConfiguration created in the previous step. We can do this by modifying the web.xml. You can find this file within your project by expanding the “WebContent/WEB-INF” folder. The content of the web.xml should look like this:

Export

That’s it! Our application is ready to be exported. You can do this by right clicking on your project and selecting “Export” -> “WAR-file”.

After you have the .war file ready you can deploy it to whatever servlet container you want.

Access the Application

To access the application you need a Tabris mobile client. You can download them from the Tabris download page. I have used the iOS client and the application looks like the one in the screenshot below. You need to point your client to your server, e.g. http://localhost:8080/com.eclipsesource.hello.world/hello (Please Note: Maybe you have to replace localhost with the address of your servlet container. On Android devices localhost points to the device.).

If you have any open questions please don’t hesitate to leave a comment.

This milstone adds quite a few nice features like bézier curves for Canvas, background-position and -repeat for CSS theming, and (especially) improved multi-tab browsing: It is now possible to host multiple UI-Sessions within the same HTTP-Session, meaning that there are no more tricks required to use multiple tabs with RAP applications in the same browser. Lets look at an example how multiple browser tabs can be used within a RAP application by integrating it with the markup and BrowserNavigation features.

Assuming our application lets the user select a person from a database to edit, the typical setup would be a TableViewer that opens a Dialog on a DefaultSelection event. We want to give the user the additional option to open this dialog in a new browser tab. This tab may run the same EntryPoint, or in this case one designed for this specific purpose only.

We create a TableViewer with markup support:

viewer = new TableViewer( parent );
viewer.getTable().setData( RWT.MARKUP_ENABLED, Boolean.TRUE );

Then we insert a link in the last cell of each row, whereby “edit” is the name of another EntryPoint:

viewer.setLabelProvider( new CellLabelProvider() {
  @Override
  public void update( ViewerCell cell ) {
    Person person = ( Person )cell.getElement();
    switch( cell.getColumnIndex() ) {
      case COLUMN_FIRST_NAME:
        cell.setText( person.name );
      break;
      case COLUMN_PLACE_OF_BIRTH:
        cell.setText( person.nation );
      break;
      case COLUMN_LINKS:
        String url = "edit#person/" + persons.indexOf( person );
        cell.setText(  
          "<a href=\"" 
          + url 
          + "\" target=\"_blank\">edit</a>" 
        );
      break;
    }
  }
} );

In the other EntryPoint, we add deep-link support like this:

BrowserNavigation bn 
  = RWT.getClient().getService( BrowserNavigation.class );
bn.addBrowserNavigationListener( new BrowserNavigationListener() {
  @Override
  public void navigated( BrowserNavigationEvent event ) {
    String state = event.getState();
    if( state.startsWith( "person/" ) ) {
      int index = Integer.parseInt( state.substring( 7 ) );
      editPerson( persons.get( index ) );
    }
  }
} );

Done. You could also use the URLLauncher service to open the tab without using a “real” link.

Image via CC from Paul Gorbould

Recently I fell into the lost exception pitfall – when an exception thrown in a try block gets lost because another exception is thrown in the finally block. It wasn’t that I was not aware of the problem, but rather that I underestimated and therefore ignored it. This post describes an example where suppressed exceptions have fatal consequences, and describes possible solutions, one of them using Java 7′s try-with-resources.

The trap

Our web application is based on the Eclipse Remote Application Platform (RAP). The main loop of the session thread is wrapped into a try block, cleanup is done in the finally block. When the session times out, a java.lang.Error (more precisely, a java.lang.TreadDeath) is thrown from within the while loop:

try {
   // main loop
   while (!done) {
      // when the session times out, an error is thrown here
      ...
   }
} finally {
   // there is a bug in this method, causing a 
   // NullPointerException to be thrown
   cleanup();
}

Unfortunately the cleanup method was programmed sloppily and sometimes causes a NullPointerException. In that case the Error is swallowed and the NullPointerException is propagated instead.

In our case this leads to the situation where the session cannot be terminated correctly, resulting in a memory leak. This effect is similar to catching Throwable in application code as described in Ivan Furnadjiev’s post. Our case is even worse since the error is swallowed without a trace – when Throwable is caught, there is at least a slim chance of finding it in a log.

The situation described above is an example of a well-known problem in Java called suppressed, lost or masked exception.

Solution 1: Handle exceptions in the finally block and never let them out

Proposed for example, in the Exception-Handling Antipatterns, this solution handles exceptions in the finally block but never propagates them. The exception thrown in the try block is the only one visible to the outside.
For our use case, logging the exceptions is a proper handling:

} finally {
   try {
      cleanup();
   } catch (Exception ex) {
      log.error(ex);
   }
}

This solution is easy and quite readable, but the exceptions in the finally block are not available anymore for processing outside of this scope.

Solution 2: Collect all exceptions in a wrapper exception

The idea is to collect all exceptions occurring in the try and finally blocks, and to attach them to a single exception which is thrown in the end.
This article shows several code snippets on how to achieve that. This solution preserves all exceptions, but if you look at the article, you can see that the code quickly becomes unreadable and therefore unmaintainable.

Solution 3: Java 7 to the rescue

The try-with-resources statement introduced in Java 7 preserves suppressed exceptions and has a short and readable syntax. Exceptions formerly thrown in the finally block are automatically attached as suppressed exceptions to the Throwable thrown in the try block. The cleanup code has to be wrapped into the close method of a class which implements the AutoCloseable interface:

class Cleanup implements AutoCloseable {
 
    @Override
    public void close() throws Exception {
        cleanup();
    }
}
 
...
 
try (Cleanup cleanup = new Cleanup()) {
   while (!done) {
      ...
   }
}

The Error is now propagated properly, with the NullPointerException as a suppressed exception. Note that this is a simplified version of the close method – it should not suppress Exception in general but rather filter out relevant ones (see the JavaDoc of the close method for details).

If the Java 6 end of life did not convince you to migrate to Java 7, maybe the try-with-resources will.

Tabris sits on top of Eclipse RAP. RAP provides a UI Toolkit to write Web applications using Java. This UI Toolkit is based on Widgets, so you don’t have to mess around with HTML. To be able to display those widgets in a browser, RAP uses a protocol which is based on JSON. Within this protocol are messages that instruct the browser e.g. to display a button, or a tree, and so on. What Tabris does is to provide two alternative clients which are an iOS and an Android client. Those clients simply understand the RAP protocol messages and display widgets using the native counterparts.

On April 28th, 2010 we have previewed a version of the RAP protocol which basically marked the start of Tabris internally. Two months later (June 11th, 2010), we had the first working prototype which has used Apple’s iAd JavaScript framework for rendering. Since then we have worked on what is today released as Tabris. It includes two native clients and an extension of the server side RAP API. This extension, which is just another jar, is necessary because the RAP API is based on the Standard Widget Toolkit (SWT). SWT is limited when it is used on mobile devices. There are no APIs for Geolocation, Camera and other things a mobile App typically use.

The first time we made our mobile clients public was the start of our “developer preview” back in January 31st, 2012. At this time we concentrated on implementing a proper support for the SWT widgets. Since then, we have released 14 milestones. The last public milestone was tagged with 0.11.0. We think that this was the most important one for Tabris. It introduced a feature called the Tabris UI. Tabris UI is a higher level API for creating a frame for your mobile application. The native clients use native navigation concepts to display a Tabris UI-based application. On Android this is the ActionBar and on iOS these are the ViewControllers. So, since Tabris 0.11.0 it has been possible to write native applications using native Widgets combined with native navigation concepts.

In the last weeks we have concentrated on Bug fixing and API cleanup to ship a release we can be proud of. If you would like to try out Tabris yourself, just download the 30 day trial version. This trial has no functional limitations! To get started with this trial we have created some detailed getting started guides you can use. We have also created a bunch of screencasts that show some of the features Tabris provides. You can find the new & noteworthy articles so far below:

• Tabris 0.5.3
• Tabris 0.5.4
• Tabris 0.5.5
• Tabris 0.5.6
• Tabris 0.5.7
• Tabris 0.5.8
• Tabris 0.6.0
• Tabris 0.6.1
• Tabris 0.6.2
• Tabris 0.7.0
• Tabris 0.8.0
• Tabris 0.9.0
• Tabris 0.10.0
• Tabris 0.11.0

At this point I want to thank the community which has provided us with great feedback, feature requests and bug reports. I also want to thank the rest of the Tabris team: Jordi Böhme López, Johannes Eickhold, Moritz Post and Ivan Furnadjiev for doing a great job over the last year! And last but not least, many thanks to the Eclipse RAP team for their great support!

The Vision

My idea was to create a highly modular and especially flexible client that supports only a minimal subset of RAP features, but can very easily be extended and customized. RAP 2.0 introduced a simple JavaScript API for creating custom widgets. This client would go one step further and also allow you to change the presentation of existing widgets to your liking (also using JavaScript). For that you don’t have to implement a new Java API, the client-server communication is already in place, as is the internal logic of the widget (like selection management). Also, the widget will still be single-sourcing capable. Any RAP widgets or features that you might miss in the client you should easily be able to implement yourself after reading the documentation. It would basically be a D.I.Y. RAP Client construction kit, and not a replacement for the full-blown existing WebClient.

Another noticeable feature of this client would also be its ability to adapt to (and take advantage of) different environments. This would also mean that it breaks with RAPs paradigm of looking and working identically on all supported browsers. If you want to take advantage of exciting HTML5/CSS3 features you can but it won’t work/look like the same older browser. You could also create a very different presentation if you are on a touchscreen device, or if you want to optimize for performance on older hardware. You could even create a presentation built entirely on SVG, or for other environments than a browser, as long as they run JavaScript.

By the way, most custom widgets and ClientScripting components written for the default WebClient should also still work with this client.

So I went ahead and built a proof-of-concept/experimental version of this web client for RAP. It currently supports 5 widgets and is appropriately titled “RAP Lite”. The code can be viewed here. You can also download it and run the demo but remember that this is strictly a research project and only barely functional.

What can it currently do?

First of all, here are two screenshots of the Demo application included:

The screenshot on the left is the default WebClient, while the one on the right is RAP Lite. The first 5 buttons all only change the Label at the top.
So far it looks and works mainly in the same way, except that RAP Lite starts up faster.

“Visit the other side” brings a List widget to the front using a nice CSS3 animation in the latest FireFox and Chrome browsers:

Clicking on “Scroll” will animate the scroll position of the List to a random value. In a modern browser the scrollbar is a subwidget (iScroll) that looks the same on any OS. Let’s compare that with IE8:

In IE (on the right), the List now uses the traditional OS-native scrollbar without animation because the iScroll widget is not supported in IE. Also, the gradients are gone because RAP Lite will not go to the same lengths as the default client to render them. Lets modify the demo to tell the client to use another presentation for buttons:

Now RAP Lite uses the native HTML form elements for push buttons, which aren’t as flexible, but look somewhat better than flat rectangles.

Finally, lets have a look at a cool feature that I didn’t mention before at all: The ability to run RAP Lite inside of a traditional, static HTML website:

This is not RAP running in an iframe. Instead, there is a simple script within that static HTML site that assigns the RAP application a div to run in. However, that’s not all. Let’s assume you want to embedd RAP in your website, with some static content between the RAP components. You can do that too. The button at the bottom of the demo opens another Shell which now looks like this:

Notice that the text flows around the new Shell, and even adapts when it changes it size.

How does it work?

RAP Lite can be separated into three layers (+libaries):

The first layer provides the core infrastructure for communicating with a RAP server. The code is taken directly from the existing WebClient and could be used to build any kind of JavaScript-based RAP client on top. (This is not quite the case yet, but almost).

The second layer provides the widget data models and internal logic, and connects the models with the first layer. It does not, however, include any HTML/CSS rendering or DOM event handling. As such it should, like the first layer, be able to run in any JavaScript environment, even non-browser.

The third and final layer does the actual presentation. Each widget model is assigned one or more (alternative) views that can render their content. The views use HTML templates and/or subwidgets (standalone widgets not based on a model) to generate the widget representation. DOM Events are pre-processed by the view, then forwarded to the model. The theming is applied using central CSS rules generated at runtime, and every view can contribute it’s own rules. Most changes in the model are either reflected by adding/removing CSS classes, or by re-rendering all or most of the HTML. While more incremental changes may be more efficient in some cases, this approach keeps the code very simple and the number of DOM operations small.

What does it all mean?

There are currently no concrete plans for a more “official” version of this client. The fact that is’s based on underscore.js sadly means that it can not become part of the RAP project for legal reasons. However, if I’m ever involved in creating another web client for RAP, it will most likely look a lot like this experiment.

If you are writing unit tests for your Java code, then you should also write them for any other code you wrote for the same project. Otherwise these tests only give you a false sense of security. RAP 2.0 provides a new JavaScript API to extend the framework with custom components, as you can read here. Using third party JavaScript libaries (jQuery, D3, etc) or widgets/applications (like GMaps, CKEditor… ) makes the task manageable even if you are not an HTML/CSS/JavaScript expert. But what about tests?

As Java/RCP/RAP developer you may be used to JUnit, and perhaps Mockito (if not: read this). Now, Java/JavaScript differences aside, I like Jasmine even better. I used it to test my JavaScript code when porting the CKEditor add-on for RAP (demo, download) to RAP 2.0. In this article I will use this project to demonstrate one way to use Jasmine with RAP.
You can look at the editors Java implementation here, and at the JavaScript code we want to test here.

Remote API Basics

To fully understand the examples i’ll show here, you should be familiar with the RAP Remote API, but you’ll get the gist of it either way. If you want, you can jump straight to the next chapter.

A brief introduction to Remote API is also given here. Basically, each side (client and server) have one “half” of the custom widget, and a representation of the other side’s “half” as an instance of RemoteObject:

Therefore RAP includes a RemoteObject implementation for Java and one for JavaScript. The main difference is that the server can create new remote objects…

Connection connection = RWT.getUISession().getConnection();
RemoteObject remoteObject 
  = connection.createRemoteObject( "MyWidget" );

… while the client can only get existing ones:

  var remoteObject = rap.getRemoteObject( widgetInstance );

In addition, the Server can also receive remote operations via the remote object, while the client object has to implement methods (especially setter) that can be directly called by the framework.

Typically, a simple custom widgets client-side life cycle looks like this:

• The client component has to register a TypeHandler (once). This is basically the glue between your custom widget and the framework. The type handler consist of a factory for the client object, and a list of properties, methods and events it supports.
• The server side creates an RemoteObject instance. With this, a “create” operation is send to the client and invokes the type handler’s factory.
• Using the id of a Composite (which the server typically provides in a “set” operation), the custom widget can obtain the client side instance and attach itself to it: rap.getObject( parentId ).append( htmlElement );
• All invocations of “set” or “call” on the server side RemoteObject will cause the matching methods of the client widget to be called. To send messags back, the client widget can itself obtain a RemoteObject to send operations to the server.
• When the server remote object is destroyed, so is the client object.

Jasmine at a glance

The Jasmine project site already gives a good tutorial, so I’ll try to keep this short. Jasmine allows for Behavior-Driven Development (BDD), which is similar to Test-Driven Development (TDD). It basically means that your tests will read like a “story” written in plain English. (Or any other language, if you’re crazy.)

For example, a traditional test in JUnit…

public class Math_Test extends TestCase
  public void test_RoundsUp2Point5() {
    assertEquals( 3, Math.round( 2.5 ) );
  }
};

… may look like this in Jasmine:

describe("Math", function() {
  it("should round 2.5 to 3", function() {
    expect( Math.round( 2.5 ).toBe( 3 );
  });
});

As you can see it’s not that different at first, except it’s easier to describe what exactly you are testing. The “describe” function seems similar to a test class (it is called a “Suite”), “it” to a test method (actually a “Spec”), and “expect” looks a bit like Mockitos “verify”. The “setUp” and “tearDown” methods in JUnit would be “beforeEach” and “afterEach” functions in Jasmine.

However, the advantage is that unlike JUnit tests, “describe” functions can be nested. And what I personally love about that, is that each can have it’s very own beforeEach/afterEach functions, and they are executed for all the “describe” functions the “it” is in. That made my tests a lot more readable. In JUnit I would often have a lot of similar setup code at the beginning for each test, and multiple asserts the end. Sure, there ways to reduce it, but I think it’s a pain. My Jasmine Specs on the other hand are usually around three lines only.

What to test?

There may be several parts to your JavaScript component. The RAP type handler has little to no logic of it’s own, and would require a “real” RAP client to be tested. Therefore we omit it, and only test the widget “class” itself.

If your custom widget is basically a wrapper for an existing JavaScript app (like CKEditor), then you might want to test only the wrapper. If so, you can also replace the app with your own mock, though you have to know the app’s API really well for that to work. In my case, I first did a untested prototype to figure out how to get the CKEditor to cooperate with RAP. Then I started again from scratch, writing tests first using a CKEditor mock I created myself.

If you are writing the entire widget yourself, you should of course test all of it, not just the part that connects to RAP.

Setting Up Jasmine with a RAP enviroment

Download the Jasmine Standalone Release and unzip it to a folder in your test project. You don’t need the included examples, so delete the src and specs folder. Open the SpecRunner.html in an editor. We are interested in the <script> tags only. Remove those that point to the deleted files. Then get the “rap-mock.js from our GitHub repository and include it with a new script tag. This is key, as the file contains a mock implementation of the RAP JavaScript API, so that your custom component can be tested outside an actual RAP application.

Below the rap-mock.js, add the JavaScript file(s) from your own RAP JavaScript component. If they are in another bundle, it may have to look like this:

<script 
  type="text/javascript" 
  src="../../com.eclipsesource.widgets.ckeditor/src/resources/handler.js">
</script>

Finally, create a new JavaScript file like “CKEditorSpec.js” and also include it in the HTML file. This is where we will put the tests.

The rap mock is initialized automatically by including the file itself, but to be sure that everything is reset with each test, your outmost “beforeEach” should look like this:

 beforeEach( function() {
  rap = new RapMock();
} );

In addition to the official API of the “rap” object, this one has two fields “fakeRemoteObject” and “fakeComposite”. Like “rap” itself, they are only empty implementations of the RemoteObject and Composite types, which are returned if rap.getRemoteObject() or rap.getObject() (respectively) are called. That makes it a lot easier to test interactions with these objects later on. (Note that it always returns the same instances, but since they dont have any state it shouldn’t matter.)

My First Spec

Since variables have function scope in JavaScript, and all Suites and Specs are functions, you can freely define variables within any suite and share them with the contained Specs. I would suggest to do so for your outmost Suite for the instance of your custom widget. For me, it looks like this:

describe( "eclipsesource.CKEditor", function() {
 
  var editor;
 
  var createEditor = function() {
    editor = new eclipsesource.CKEditor( { "parent" : "w2" } );
  };
 
  beforeEach( function() {
    rap = new RapMock();
    editor = null;
  } );
 
  afterEach( function() {
    editor = null;
  } );
 
  ...
 
} );

I’m not creating an instance in the outer Suite because we will sometimes need to do some setup before calling the constructor. This is where spies come into play. Remember, our rap mock (and in this case CKEditor mock) does absolutely nothing itself (except preventing crashes). To write meaningful tests, we need to spy on it.

Spies replace methods with stubs, which can later be checked for invocations Mockito-style. They can also return any value, capture arguments, or execute arbitrary code. Read more about them here. Spies are automatically removed after each it.

Now we dive right into it, and test that the widget adds itself (specifically it’s element) to the parent:

  describe( "The Constructor", function() {
 
    it( "should get a Composite with the parent id", function() {
      spyOn( rap, "getObject" ).andCallThrough();
      createEditor();
      expect( rap.getObject ).toHaveBeenCalledWith( "w2" );
    } );
 
    it( "should add an element to the composite", function() {
      spyOn( rap.fakeComposite, "append" );
      createEditor();
      expect( rap.fakeComposite.append )
       .toHaveBeenCalledWith( editor.element );
    } );
 
  } );

It is a common pattern to prefix “private” fields of JavaScript objects with a “_”. For the CKEditor wrapper I completely abstained from creating private fields and made everything “public”, including the HTML element. If I hadn’t, I would either have to access a private field, or examine the contents of the element that was given to the fake composite. Since i’m not interested in testing the CKEditor itself, I chose this simpler solution.

Most other aspects of the constructor and the editor/wrapper are tested in similar ways, as you can read in the full Spec file. However, there are a few more special cases I like to discuss in detail.

Testing events

The CKEditor wrapper registers events listener on the CKEditor itself and on the “rap” object, e.g. to check for changes before a request is send to the server. There are various ways to test them. The “cleanest” one would likely be to obtain the listener with a spy and execute it:

describe( "The send listener", function() {
 
  var onSendListener;
 
  beforeEach( function() {
    spyOn( rap, "on" ).andCallFake( function( event, listener ) {
      if( event === "send" ) {
        onSendListener = listener;
      }
    } );
    createEditor();
  } );
 
  describe( "of an editor that has not changed", function() {
 
    it( "sends nothing", function() {
      spyOn( rap.fakeRemoteObject, "set" );
      onSendListener();
      expect( rap.fakeRemoteObject.set ).not.toHaveBeenCalled();
    } );
 
  } );

With the “beforeEach” function this does not bloat your code all that much, but it’s still a couple of lines. So instead I simply made the listener “public” (like with the HTML element) and called it after checking it was registered. This is part of the “contructor” Suite show above:

it( "should add a send listener", function() {
  spyOn( rap, "on" );
  createEditor();
  expect( rap.on ).toHaveBeenCalledWith( "send", editor.onSend );
} );

Now I can simply invoke editor.onSend whenever I want, since I now it has been registered with the RAP client, which I trust to work correctly. But, there is one important bit: You should not simply write editor.onSend(), because this would mean that editor will be the context (this) of the invokation. This is not automatically given when working with JavaScript callbacks, and I know it is not the case with rap.on. (To see how I solved that issue for the CKEditor, look at the bindAll function in the source code.) Instead, you can write editor.onSend.call();, which executes it without context.

The Clock makes “tick”

A common issue with JavaScript testing are asynchronously executed function. This custom widget has one of those for setting the editors font, which happens with a small delay using the JavaScript setTimeout function. This means I can not simply call editor.setFont and check the results right away. Jasmine includes two different solutions for this issue. If you want or need your test to emulate the actual runtime scenario, you need to wrap the code of your Spec in runs and waitsFor functions.

Since I use only a mock CKEditor I had no such requirement, and used the alternative: Simply mocking the JavaScript timer.

describe( "The setFont function", function() {
 
   var body;
 
   beforeEach( function() {
    jasmine.Clock.useMock();
    createEditor();
    body = editor.editor.document.getBody();
    spyOn( body, "setStyle" );
    editor.setFont( "13px Arial" );
  } );
 
  it( "calls body.setStyle on a ready event", function() {
    editor.onReady.call();
    jasmine.Clock.tick( 0 );
    expect( body.setStyle ).toHaveBeenCalledWith( "font", "13px Arial" );
  } );
 
} );

Feedback…

…would be welcome, especially if you have trouble writing tests for RAP custom widgets. I did not touch on some topics like sending events to the server (which the CKEditor doesn’t do), or how to test DOM changes, but that would have completely burst the scope of this article. (I sometimes have issus keeping things short…) Also, on testing the server side: RAP includes a Fixture (not official API) which allows testing the Remote API, but we might change it soon, so I didn’t want to write about it now. If you are curious, look at CKEditor_Test.java.

Final Words

Jasmine is awesome. Go use it for something.

The first part guides you through the setup of your Eclipse IDE and Virgo Jetty Server. The second part is a short walkthrough on how to create a Hello World Web Application Bundle (WAB) with RAP.

Feedback welcome.

[1] Developing Web Application Bundles with RAP and Virgo – http://eclipsesource.com/blogs/tutorials/developing-web-application-bundles-with-rap-and-virgo/
[2] RAP – Enabling modular business apps for desktop, browser and mobile – http://eclipse.org/rap
[3] Virgo from eclipseRT – http://eclipse.org/virgo/

What are Mnemonics?

Should you not know, Mnemonics are the characters that get underlined in some widgets (especially the menu bar) if you hold down the ALT key. Mac users may scratch their heads right now, because those aren’t supported in OS X. Their exact behavior differs a bit between the other platforms, but as long as you hold ALT and press of the underlined character on your keyboard, the widget gets selected. What I like about that is that, unlike normal shortcuts, you do not need to remember Mnemonics, and they can change all the time depending on what’s on screen.

Mnemonics in RAP 2.1M1

As of M2 (or the current nightly build), RAP will support Mnemonics on Menus, Buttons, ToolItems, TabItems, Labels and Groups. (Also CTabItem and CLabel.) To enable them, you first need to set the modifier that makes the Mnemonics visible. While you could use ALT, it’s strongly discouraged, because that would activate the actual Mnemonics of your browser with unpredictable results. I recommend using CTRL+ALT, and reserve CTRL and CTRL+SHIFT for global shortcuts/Key Bindings. The combo can be set with just one line:

display.setData( RWT.MNEMONIC_ACTIVATOR, "CTRL+ALT" );

Now all you need to do is to put a “&” before a character in a widgets text, and you already have a working Mnemonic. Example:

tabItem.setText( "Tab Item &1" );

Since this is a relatively complex new feature, I would love for developers to grab RAP 2.1M1 when it’s available next week and try it in their application so that we can get some feedback.

Coming soon: Full Accelerator support.

• Highly Interactive Mobile Apps with RAP (J. Böhme López, H. Staudacher): Smartphones and Tablets have become ubiquitous. The competitiveness of the market is a win for consumers but a nightmare for developers. To write an application targeted for multiple devices, developers will be faced with an array of platforms and programming languages. Reade more…
• Deploy and Manage RAP Applications on Equinox, Jetty, Virgo, Apache Karaf, and Tomcat (M. Knauer): You’ve written a RAP-based application, but now you want to make it available to the public? Deploying and managing Eclipse RAP applications is challenging because there are so many options to choose from. Read more…

• Eclipse/OSGi Puzzlers – Traps and Pitfalls (B. Muskalla from Tasktop, H. Staudacher): Every API has its quirks. Based on the popular ‘Java Puzzlers’ talks by Joshua Bloch we will present the first Eclipse/OSGi Puzzles talk. What to expect? Traps and Pitfalls from the Eclipse and OSGi universe for you to participate. Besides the common pitfalls we will dive into well known Eclipse APIs and their quirks. Together we will investigate the ramifications of using these APIs. Read more…

• EMF Dos and Don’ts (M. Koegel, E. Mueller): EMF is very powerful and most of the time fairly simple to use, but of course there are rocks and shallows: Why are there so many Adapters on my EObjects? After overriding some generated code the XML serialization stopped working? My subpackages are not recognized by framework X? EcoreUtil.delete is dead slow? Read more…

• What every Eclipse developer should know about EMF (M. Koegel, E. Mueller): Many talks about e4, modeling and other topics assume you have used the Eclipse Modeling Framework (EMF) before. But what if you haven’t? What is all this modeling stuff about? What is EMF anyway? And who is this Ed guy? Read more…

• Fuzzy Testing (M. Koegel, E. Mueller): Many of the test cases for an application involve data defined by the data model. To achieve good test coverage it is customary to run the test cases for a variety of different input data sets. This can be achieved by manually specifying different input data. However, this is a complex task and it is easy to miss important input data and thereby miss bugs. Read more…

• Modeling Symposium (J. Helming, Ed Merks from Itemis): The modeling community is among the most active and diverse in Eclipse’s ecosystem. The modeling symposium aims to provide a forum for community members to present a brief overview of their work. We will encourage minutes lightning talks to facilitate a broad range of speakers. The primary goal is to introduce interesting, new technological features. Read more…

• What every Eclipse developer should know about Eclipse 4 (e4) (J. Helming, E. Neufeld):  This tutorial will give you a jumpstart into the new concepts of the Eclipse 4 Application Platform. If you have previous experience developing with RCP 3.x, but limited or no experience with e4, this tutorial is designed for you. Based on a sample RCP application, we introduce the most important features of the new platform, such as the Application Model, Dependency Injection and the new Programming Model. Read more…

Quite a few of my EclipseSource colleagues are busy right now preparing talks and demos and we hope to meet you there. If you can’t make it to a talk don’t be shy and meet us at the bar (after the talks) .

A user interface written with RAP is executed on the server side. This requires you to abstract from the execution environment in your test code. RAP supports you with a so-called test fixture to do so. The test fixture thus enables your test code to run without any server infrastructure.

Disclaimer:
Although the test fixture comes with the official RAP 2.0 target it is not officially supported API. There is work underway to improve the mechanisms currently provided by the test fixture. This means that the test fixture’s API will change in the future. Please keep this in mind. Nevertheless this post explains the way in which to write unit test for RAP 2.0.

Create the UI

As a simple example the class MyComposite should create a new composite with two buttons on it.
Let’s take a look at a basic test that ensures your MyComposite is created as expected.

public class MyComposite_Test {
 
  private Display display;
 
  @Before
  protected void setUp() throws Exception {
    Fixture.setUp();
    display = new Display();
  }
 
  @After
  protected void tearDown() throws Exception {
    Fixture.tearDown();
  }
 
  @Test
  public void testCompositeHasTwoChildren() {
    MyComposite myComposite = new MyComposite( display );
 
    assertEquals(2, myComposite.getChildren().length);
  }
}

As you can see in the setUp() and tearDown() methods, the Fixture provides a convenient way to prepare the environment so your actual UI manipulation in testCompositeHasTwoChildren() will just work. It’s as simple as this to write you first test.

Event Handling

Next to the creation of your UI you most probably want to test that your event handling does the right thing. In RAP, event handling happens in a special phase. The test fixture allows you to set the phase so your test can correctly trigger events. Let’s assume you registered a ModifyListener on a Text widget. Now your test could ensure the correct listener is invoked and behaves as expected by writing a test like this:

// setUp and tearDown as in example above
 
@Test
public void testModifyingTextShouldTriggerXY() {
  Fixture.fakePhase(PhaseId.PROCESS_ACTION);
  // prepare Text widget
 
  text.setText(""); // triggers event
 
  // assert ModifyListener did the right thing
}

Conclusion

Writing unit tests for your RAP application’s UI code is easy with help of the test fixture. This post explained the fundamental steps to write such tests. If you have any questions regarding unit testing RAP applications or using one of the other features provided by the test fixture, please comment below.