Suppose middle earth wants to keep track of the dragons that were slain over the centuries. The dragons are tracked in one list, and reports come in from different dwarfs, humans or elves. Sometimes, a dragon was reported slain falsely, so it needs to be removed.

A test for this list could look like this:

public class SlainDragonsTest {
 
    private final SlainDragons uut = new SlainDragons(); 
 
    @Test
    public void shouldSafelyAddAndRemove() throws Exception {
        uut.addSlain("Scatha");
        uut.addSlain("Smaug");
        uut.addSlain("Glaurung");
        uut.removeSlain("Smaug");
        assertThat(uut.getSlainDragons(), hasItem("Glaurung"));
        assertThat(uut.getSlainDragons(), not(hasItem("Smaug")));
    }
}

After a battle, lots of reports tend to come in at the same time, so the list has to work under stressful conditions without errors. So, we want the test to be executed simultaneously by a large number of threads. Each of the threads has to pass and the collective result decides on the JUnit report. For this purpose I wrote a “Manifold” class that converts the test to a load test.

  @Rule public Manifold simultanousReports = new Manifold(200);

Internally, Manifold opens 200 threads and runs the test method simultaneously inside the thread. It waits for all of the threads to finish and fails with the first error it found. No further adjustment of the test methods is necessary. If you are interested, you can download the class Manifold here.

Happy dragon hunting!

Most of the out-of-the-box p2 tools are related to provisioning OSGi bundles (or Eclipse plug-ins, if you prefer), but there is nothing in the core that limits us to Eclipse or OSGi. In fact, you can extend p2 to install whatever you want. In this example I’ll show you how to create a custom Install Action (touchpoint) that executes an arbitrary binary during installation.

Background

When you use p2 to install software it goes through a number of steps.

1. A provisioning plan is computed. Based on what you already have installed and the install action you’re taking, p2 computes a plan. The plan includes operands such as: remove foo, upgrade bar, install baz, etc..
2. Artifacts are fetched and checked. Once a plan is constructed, the plan is executed on the p2 engine. The first step is fetching all the artifacts and the trust checking (checksum validation)
3. Unconfigure / Uninstall. If there are any units being removed, they are given a chance to ‘unconfigure’ themsevles. Once this is done, they are uninstalled.
4. Install / Configure. If there are any units being added, they are first installed and then they are given a chance to configure themselves.

For installable units being upgraded, this is essentially an unconfigure / uninstall followed by an instal / configure.

The Problem

p2 has a number of actions you can invoke when an installable unit (IU) is installed, configured, unconfigured or uninstalled. For example, artifacts can be unzipped, copied or the permissions can be set. These actions are called touchpoint actions. Eclipse has two sets of touchpoint actions, native and OSGi. Native ones are general (such as move, copy, mkdir) while the OSGi ones are Eclipse or OSGi specific (install bundle, set VM Args, etc…).

While these are a good start (and enough to provision an Eclipse system), often you need custom actions if you are provisioning a highly specific system. Also, not only do you need custom actions, you need them to be installed before they can be used.

Let’s consider the case where we want to ship and run an arbitrary executable during the installation of a plugin.

Touchpoint Actions

Custom touchpoint actions can be specified using the org.eclipse.equinox.p2.engine.action extension point. Touchpoint Actions are tied to a touchpoint, the controller responsible for executing the action. You can either write your own custom touchpoint, or simply tie your action to an existing one. In our case, we will tie our touchpoint action to the OSGi touchpoint.

All touchpoint actions extend ProvisioningAction and provide two methods execute and undo. Execute is used whenever the provisioning action is invoked. Undo is used if the action needs to be rolled back. In our case we will implement execute to read a parameter and call Runtime#exec on the value of that parameter.

public IStatus execute(Map<String, Object> parameters) {
  String artifact = null;
  if ( parameters.containsKey(ARTIFACT) ) {
    // If an artifact is specified, look it up
  }
  String program = (String)parameters.get(PROGRAM);
  String fullPath = computeProgramPath(artifact, program);
  try {
    Runtime.getRuntime().exec(fullPath);
  } catch (IOException e) {
    e.printStackTrace();
    return new Status(IStatus.ERROR, Activator.PLUGIN_ID, "Cannot execute " + fullPath);
  }
  return Status.OK_STATUS;
}

The undo method (that is, the inverse of Runtime#exec) has been left as an exercise to the reader .

MetaRequirements

In order to ensure that  your touchpoints get installed before the components that need them, you can either invoke two updates (update the installer and then update the application) or you can use MetaRequirements. MetaRequirements invoke a two stage plan, ensuring that the touchpoints are fetched and installed before they are invoked.

MetaRequirements can be declared in a p2.inf file as follows.

metaRequirements.0.namespace=org.eclipse.equinox.p2.iu
metaRequirements.0.name=com.ianbull.p2.touchpoint.exec
metaRequirements.0.range=[1,2)

In this case we’ve specified a metaRequirement on the Installable Unit com.ianbull.p2.touchpoint.exec version [1.0,2.0). This Installable Unit must exist before our IU can be installed. For OSGi bundles, the p2.inf file should be placed next to the MANIFEST.MF file. In our case, it’s placed in a bundle called com.ianbull.p2.touchpoint.payload.

To summarize, before ‘payload’ can be installed, the touchpoint ‘exec’ must be installed and available. Since it’s declared as a metaRequirement, p2 will handle this by using a two-stage plan.

Invoking the Touchpoint

Now that we’ve created the touchpoint, all we need to do is invoke it. This is done by the Installable Unit which declares the metaRequirement. In our case, we will ship the executable as part of our ‘payload’ plugin.

We will use two touchpoints, one to set the permission (755) and then our custom touchpoint to launch the application.

instructions.install = \
chmod(targetDir:@artifact,targetFile:payload/someProgram,permissions:755);

instructions.install.import= \
org.eclipse.equinox.p2.touchpoint.eclipse.chmod

instructions.configure = com.ianbull.p2.touchpoint.exec.Execute(artifact:@artifact, program:payload/someProgram);

Putting it all Together

Once we have these two plugins (the ‘exec’ touchpoint and the ‘payload’) we create a repository that contains them both.

With the repository in place, we simply invoke the director, or better yet, the p2 Install Software Dialog to install the payload.

The payload doesn’t actually have any dependency on the ‘exec’ touchpoint, except for the MetaRequirement. This MetaRequirement will cause the ‘exec’ touchpoint to first be installed, and then the touchpoint can be invoked.

And now during installation, our custom application is started. While this particular application doesn’t do anything useful, it could be an installer for another tool, or it may simply invoke an existing service such as Apache HTTPD.

If you’re interested in the code examples I’ve used here, I’ve pushed them all to GitHub.

Firefox Peak – First impressions

The Firefox OS phones were advertised with “daily updates”, but there hasn’t been a single update since the end of April. That’s why I started my hunt for information.
Searching for Firefox OS roadmap quickly brings you to this page:

https://wiki.mozilla.org/B2G/Schedule_Roadmap

Too bad, this roadmap is from 2012. At least that is what it’s saying. Maybe just a typo? No, it says: “Detailed Milestone tracking was here” for Milestone 3, Target Date 6/1/2012. To my knowledge the verb form “was” indicates the past.

So I started to look for builds. Hooray, Firefox OS nightly builds gain a top ranking in the search results. However, it is only a directory listing of builds. There are instructions on how to install the OS into a simulator and onto an Android phone, but no info about getting it on the Peak device. I am sure spending a few additional hours will get me there, but why do I and likely hundreds or even thousands of developers need to waste this time? Being able to choose between a milestone and a nightly update channel seems a straightforward solution for this issue – and would enable the feedback the Firefox OS developers are looking for.

As I couldn’t believe that there is no roadmap, I went back to looking for one and landed on the Schedule_Roadmap page again. Following the link to the past detailed milestone tracking revealed two surprises: The development of the milestone is under full steam (so it is current) and the tracking is done in a couple of google spreadsheets. While it is great to see that there is a lot of stuff going on, I find the choice of tools inadequate.

From my point of view, running an open source project the way that Firefox OS is run is problematic. I agree that writing code has the highest priority, but if you fail to create an “architecture of participation” you severely limit your chances of success.

The Mozilla Foundation has proven that they can run projects in a way that enables early feedback. Please, Firefox OS team, let a few features slip for the next milestone and allow us to participate more.

EMF Dos #10: Use EMF ComposedAdapterFactory

In my previous blog post, I discussed AdapterFactoryLabelProvider and AdapterFactoryContentProvider, which can be used to provide labels and children for your entities in viewers. Both require an AdapterFactory in their constructors that will be used to retrieve the actual ItemProviders and their entity-specific implementation.

If you pass in the AdapterFactory of a specific model, the provider will only be able to provide labels for entities of the given model. However, viewers often need to display entities of multiple models. Of course, there is a solution to this with EMF: ComposedAdapterFactory.

A ComposedAdapterFactory is a composition of AdapterFactories, as the name implies. You can construct it with a collection of AdapterFactories, and it will delegate calls to adapt() to the resepective AdapterFactory based on the entity type. If you want to display multiple models in one viewer, you just combine all the models’ AdapterFactories into one ComposedAdapterFactory and pass it to the AdapterFactoryLabelProvider and AdapterFactoryContentProvider.

If you do not want to restrict your viewer to specific models but want to use all models available in your current target platform, you can pass in ComposedAdapterFactory.Descriptor.Registry.INSTANCE, which is the registry of all available AdapterFactories. By default, the  AdapterFactory of a generated Edit-Plugin is registered via the org.eclipse.emf.edit.itemProviderAdapterFactories extension point and thereby added to the aforementioned registry.

If the AdapterFactoryLabelProvider/AdapterFactoryContentProvider and the ComposedAdapterFactory are based on the registry, your viewers can be fully decoupled from the actual models they display while still providing customized icons, labels and content.

Stay tuned for more Dos and Don´ts in my next blog!

EMF Dos #9: Use EMF ItemProviders

To display entities in a tree view or in other views, you need a label provider and a content provider. The label provider provides an icon and a text to display each entity type. The content provider defines the children of an entity. Additionally, the label and content providers need to notify their viewers if the label or content changes due to data changes. The viewers will update only if there are data changes. You could implement the label and content providers manually, which is a lot of work, or you can rely on EMF-generated infrastructure.

For every entity defined in your Ecore, EMF will generate an ItemProvider in the Edit-Plugin. The ItemProvider implements methods to get an icon and a text for the entity (getText() and getImage()). Since you want to display all kinds of entities in a tree view, you need to create a label provider that will know the type of your entity and use the matching ItemProvider to retrieve a text and an icon. This label provider needs to implement  the ILabelProvider interface. Similarly, a content provider would have to implement the ITreeContentProvider interface and define the children for all the different kinds of entities. For this purpose, EMF provides a fully functional label and content providers: AdapterFactoryLabelProvider and AdapterFactoryContentProvider. They both work in the same way,  so I will focus on the AdapterFactoryLabelProvider.

Conceptually, an AdapterFactoryLabelProvider is able to provide labels for all supported entities by delegating to the appropriate generated ItemProviders. Technically, the AdapterFactoryLabelProvider requires an AdapterFactory to do this (see the constructor). An AdapterFactory creates adapters (wrappers) for a given entity. For each EMF model, EMF generates an AdapterFactory for the ItemProviders of its entities. Basically, the adapt() method of the AdapterFactory returns the appropriate ItemProvider for a specific  entity.

To construct an AdapterFactoryLabelProvider,  you can pass in the AdapterFactory of your model, and the label provider will be able to display your entities based on their ItemProviders.

If you want to display entities from multiple models you can use a ComposedAdapterFactory, which I will describe in my next blog.

The AdapterFactoryLabelProvider will —  with the help of the ItemProviders — update its viewers if any of the entities it provided a label for change. Furthermore, the AdapterFactoryLabelProvider is very loosely coupled to the ItemProviders that implement entity-specific display behaviour.

Since the ItemProviders are generated (but can be adapted if necessary), the AdapterFactoryLabelProvider and AdapterFactoryContentProvider really are a big productivity boost in displaying EMF-based entities in your viewers.

Stay tuned for more Dos and Don´ts in my next blog!

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.

EMF Dos #8: Use EContentAdapters Carefully

In my previous blog post,I talked about the EMF notification mechanism and the need to dispose of Adapters correctly. Instead of a simple AdapterImpl receiving notifications from only one EObject, you might want to receive notifications from multiple EObjects. For example, you might want to receive notifications for all EObjects in a ResourceSet, a Resource or a containment tree of a specific EObject. While you could implement this manually quite easily by walking the containment tree and attaching an Adapter to every EObject in the tree, it would be more complicated to update your registered Adapter when the containment tree changes. Imagine that EObjects are disconnected from or added to the containment tree. Every time, you would have to add or remove your Adapter as appropriate. To make this task very simple for you, there is a more powerful adapter in EMF: EContentAdapter.

An EContentAdapter can be attached to a ResourseSet, a Resource or an EObject. If attached to ResourceSet, it will behave as if it is attached to all its Resources and attach to newly added Resources as appropriate. If attached to a Resource, it will behave as if it is attached to all EObjects at the root of the Resource (including newly added EObjects). If it is attached to an EObject, EContentAdapter will attach to it and to all its contained EObjects following the containment tree. Furthermore, it will remove and add itself if EObjects are removed from or added to the containment tree. If any of the EObjects the EContentAdapter is attached to changes it will receive a notification in its notify() method.

In conclusion, adding an EContentAdapter to an EObject with a huge containment tree is an expensive operation in terms of time. Maintaining multiple EContentAdapters is even more time-consuming. If you add a slow operation to the notify method of the EContentAdapter (e.g., refreshing views on each notification), your application might slow down considerably. Of course, there are good use-cases for EContentAdapter but, in general, you should try to limit yourself to adding Adapters to only the EObjects that are of interest for a specific update operation to avoid overhead.

Stay tuned for more Dos and Don´ts in my next blog!

I will share my experience with the phone in a couple of blog entries, from first impressions to user experience topics, to trying Eclipse RAP and various mobile frameworks on the peak phone. Obviously I am also interested if Firefox OS should be a target for our Tabris framework. However, that will have to wait, lets get started with the first impressions:

Packaging
The packaging is made of recycled cardboard – good. Geeks care about the environment.

Contents
Phone, earphones (including microphone), USB-cable and USB-charger. For my taste they could have saved both the earphones and the charger, or do you know any developers that don’t have at least a couple of these items anyway?

The Phone: Peak
Case
Makes a good impression at first sight, although it does not look “expensive”. The haptic perception is slick, with a tendency to slippery. I find it annoying that the back of the phone is uneven – the camera lens sticks out on one side of the upper half of the case. This makes it hard to type when you lay down the phone on its back, not  really ideal for a development phone.

Display
The display is ok, but the viewing angle is very narrow and the reflexions can be quite disturbing. Good that geeks love dimmed rooms …

Firefox OS
Unlocking and browsing the main screens is easy, swiping between multiple panes with Apps is the established standard that Firefox OS is sticking to.
Setting up accounts for mail and calendar worked well (Google Apps), only data entry is annoying. The on-screen keyboard is far from the responsiveness I am used to from my iOS / Android devices. Because the keyboard did not accept some of my strokes I had to try and put the cursor at a specific position in the text field, which is really a pain. Especially if the text is longer than the space available it is almost impossible to get to the position at the end of the entry. Not that I am very fond of the iOS magnifying glass or Android Cursor / Range Selection mechanism, but this is close to completely unusable.

When testing the mobile browser I almost gave up on entering a somewhat longer URL. Beside the problems described above, the browser started to load the URL while I was still typing, so I had to go and try to add something at the end of the URL multiple times.
Calendar and Mail that are coming with Firefox OS show that there is potential for a browser-based operating system, but Palm OS has been there as well, with even sleeker apps and did not quite make it.

I am going to use the phone over the next couple of days – I will write about the browser in the next post as it is at the core of the entire system.

Milestone 7 is the last Kepler milestone before we start rolling out release candidates — with a scheduled release on June 26th 2013.  There are a number of new and noteworthy things from the Eclipse and Equinox teams in this milestone, including:

A p2 Remediation Wizard to help you move past p2 errors. If an install fails, p2 will look for other solutions such as upgrading or removing blocking components. The results of the remediation will be presented and you can choose the path that makes sense for you.

Open Resource improvements:

and you can now use Content-Assist without a prefix

Also, the first set of Eclipse 4.x API has also been released.

If you are planning on building on, or even just using Eclipse Kepler, now would be a great time to download this milestone and help out with the testing. Less than 2 months to go!

Checkout the entire New and Noteworthy, or download milestone and try it out yourself.

http://download.eclipse.org/eclipse/downloads/drops4/S-4.3M7-201305020800/