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:

public class Configuration implements ApplicationConfiguration {
 
  @Override
  public void configure(Application application) {
    TabrisClientInstaller.install(application);
    application.addEntryPoint("/hello", new TabrisUIEntrypointFactory(createConfiguration()), null);
  }
 
  private UIConfiguration createConfiguration() {
    UIConfiguration uiConfiguration = new UIConfiguration();
    PageConfiguration startPageConfig = new PageConfiguration("root", StartPage.class);
    startPageConfig.setTopLevel(true);
    startPageConfig.setTitle("Hello World" );
    uiConfiguration.addPageConfiguration(startPageConfig);
    return uiConfiguration;
  }
 
}

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.

public class StartPage extends AbstractPage {
 
  @Override
  public void createContent(Composite parent, PageData data) {
    parent.setBackground(new Color(parent.getDisplay(), 255, 150, 255));
  }
 
}

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:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0">
  <context-param>
    <param-name>org.eclipse.rap.applicationConfiguration</param-name>
    <param-value>com.eclipsesource.hello.world.Configuration</param-value>
  </context-param>
 
  <listener>
    <listener-class>org.eclipse.rap.rwt.engine.RWTServletContextListener</listener-class>
  </listener>
 
  <servlet>
    <servlet-name>rwtServlet</servlet-name>
    <servlet-class>org.eclipse.rap.rwt.engine.RWTServlet</servlet-class>
  </servlet>
 
  <servlet-mapping>
    <servlet-name>rwtServlet</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>
</web-app>

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/

Who would not want to be part of such a movement? – So now we are a community of professionals who value well-crafted software (BINGO again). And the first time after reading Robert Martins books you’ll have some clear impressions that tests are the one thing that make the difference. Everything else follows – eventually even the understanding what kind of tests the dear uncle is talking about.

The manifestos are referred to often enough, and I’m sure you are at least somewhat familiar with them. Still I want to repeat them again, but to not get boring, let me combine them to make it clear that one Manifesto is the extension of the other.

• We find working software more important than comprehensive documentation. In pursuit of this, we also practice crafting software well and and help others in doing so.
• We find individuals and interactions more important than processes and tools. In pursuit of this, we form  a community of professionals and invite others joining in.
• We find customer collaboration more important than contract negotiation. In pursuit of this, we find productive partnerships indispensible.
• We find responding to change more important than following a plan. In pursuit of this, we strive for steadily adding value.

The Agile Manifesto and the Software Craftsmanship Manifesto are quite concise and carry a lot of values. Together they provide a high standard anyone involved in Software Development can adhere to. I find that many developers who follow the craftsmanship movement focus too tightly on the italic part.

It’s important to note that the Agile Manifesto gives priorities. It states that working software is valued higher than comprehensive documentation. However, the Software Craftsmanship manifesto is an addition. It reads “but also well-crafted software”. Where the Agile Manifesto used the word “over” to tie the right and the left side of the priorities together, the Software Craftsmanship Manifesto uses a “but also“. Well-crafted software means nothing if it is not the working software that the customer wants.

So remember, before you raise the bar, make sure you jumped over it at least once before.

The “New Build System”

Entering the “New Build System” based on Gradle. The new build system is supposed to become the official mechanism for building Android applications. The gradle-based build combines some of the strengths of ant and maven (flexible architecture with a lot of custom tweaking opportunities), whilst at the same time providing reasonable default configurations to keep the build scripts small. Maven dependencies can be consumed from maven central, while it is also easy to consume “local file” dependencies.

Okay, but how does the “New Build System” prevail in practice?

Using the Gradle Android Build

DISCLAIMER: We are only a few days away from Google IO 2013 so the points raised here might have already changed when you read this.

Basic build scripts can be really really small when you rely on the default folder structure for your project. Your basic gradle build script can look like this:

buildscript {
  repositories {
    mavenCentral()
  }
 
  dependencies {
    classpath 'com.android.tools.build:gradle:0.3'
  }
}
 
apply plugin: 'android'

In fact the buildscript{} element is only required to bootstrap the script itself. The actual content is the lonely apply plugin: 'android'. Running this script produces a fully runnable unsigned apk.

The basics are simple but what about dependencies? As I mentioned, you can easily add dependencies from maven central or a local file. In fact, the buildscript downloads its own android tasks from maven central.

repositories {
    mavenCentral()
}
 
dependencies {
    compile 'com.google.guava:guava:11.0.2'
    compile files ('libs/gcm.jar')
}

The compile directive is similar to mavens compile scope in that the dependency will be bundled into your packaged .apk.

Gradle also supports Android library projects. The “New Build System” compiles library projects into .aar packages, which can be consumed by the main project. The main advantage of the .aar format is its ability to handle dynamic Android resource ids. You will be able to ship an *.aar archive and consume it in your main project without having to create all of its ids during compile time of the main project.

Library projects have to be listed in a settings.gradle file and all projects taking part in the build can reference any other project listed in that file.

Where the gradle build has its real strength is in creating multiple versions of the same app. For example, a free and a paid version, or different versions for various cpu architectures. I won’t go into detail but you should read all about it here.

Shortcomings

Now that we have discussed some of the strengths of the gradle build system, lets discuss some of the pitfalls:

The gradle build is not yet able to deal with the most common dependency format for library projects: the maven apklib. Currently you can only consume maven artifacts that are packaged as jars. This rules out a lot of high profile dependencies such as the actionbarsherlock or the viewpagerindicator. If you want to depend on these resources you will have to keep a source reference in your project (or package them as an .aar).

The gradle build system offers good support for instrumentation tests you run on your device, but it is currently very hard to run standalone robolectric tests. The main problem is that robolectric does not understand the gradle dependencies so that it cannot gather sub-dependencies, and so on.

Support for the Android Development Tools (ADT) is currently non-existent although this is very likely to change with future releases. The ADT cannot deal with the default folder layout by gradle, nor can it deal with declared dependencies. Therefore, you have to maintain two build infrastructures: one for Eclipse (project.properties etc) and one for the gradle build.

Wrap Up

The “New Build System” build sounds awesome! As long as it can deliver on all its promises. At the moment, I can not recommend it for larger projects due to the lack of robolectric support and problems with maven dependencies.  I have discussed the issues raised here with +Xavier Ducrohet, the lead architect of the build system, and he assured me that most of the issues will be addressed. At the Droidcon Berlin I spoke to Hans Dockter, the CEO of Gradleware and co-architect of the “New Build System”, and once gradle becomes the driving engine for the ADT the entire toolchain should be covered. If the Android library ecosystem were to adapt gradle, it would have a very bright future.

For those of you who haven’t heard of the Raspberry Pi, it’s a low cost computer that includes HDMI (1080p) output, USB, Ethernet, an ARM processor (700Mhz) and 512Mb (or 256Mb) of RAM. The entire computer is the size of a credit card (or an Ontario Fishing License if you prefer), and can be purchased for as little as $25 ($35 for the 512Mb version). The board also includes 26 pins, allowing you to connect it to all sorts of crazy hardware — treating the little computer more like an embedded controller.

Backing up a decade, OSGi (the underlying modularity system used for Eclipse) was originally designed for embedded systems such as set-top boxes. The EclipseRT (Runtime Project) extended this work by bringing high quality runtime components to this programming model. EclipseRT includes components such as: a powerful webserver (Jetty), a provisioning platform (p2), persistence technology (EclipseLink), a rich widget toolkit for Ajax based applications (RAP), and more. The idea that you could create a full software stack based on Eclipse and deploy it on a stick has been on our minds for years, but a we lacked a low cost (and generally available) computing platform to deploy it too. With a Raspberry Pi in hand, I decided to revisit this vision.

The Setup

To get started, you need an OS and a JVM. There is a Debian based distribution for the Raspberry Pi (Raspbian) and Oracle has a JVM for the ARM processor. Unfortunately the most common setup doesn’t work. The Oracle JVM does not support the hard-float ABI used by Raspbian. Lucky for us, there is a Raspbain image that supports soft-float ABI. Download this image and write it to an SD card (there are several good tutorials out there on how to do this). Once the image is on the card, you can start your Pi and install the JVM.

 The RT Stack

The application I used was a simple web based mail client that leverages RAP (for the widgets) Jetty (for the webserver), Apache Felix Gogo shell, and Equinox. The entire application was designed as an  ’Eclipse Product’ and built with Tycho. Because Raspberry Pi is not a supported architecture, we targeted Linux/x86 (knowing full well that no native libraries would work). Once the build was completed, the product was copied to the Pi.

The Launch

The launchers that you get when you build a product are native, that is, binary executables for the particular platform. Because Raspberry Pi is not a support platform (yet), you cannot use the native launcher. Instead, you need to start your product by invoking Java and specifying the launcher jar.

 The Result

With the runtime stack and mail application running on the Raspberry Pi, testing the setup is as simple as navigating to the Pi with a web browser.

While this is just an example, it does show that you can get a non-trivial OSGi application (46 bundles) running on a Raspberry Pi without much work. It also opens the door to a large collection of Eclipse based runtimes (including the modelling technologies, ECF and more) running on the Pi. Having the EclipseRT projects running on a Pi is a great addition to the other M2M (Machine-to-Machine) work that is happening at Eclipse.org.

For more information on what I’m doing with Eclipse, Equinox, p2 and the Raspberry Pi, feel free to follow me on Twitter (@irbull).