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.

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

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!

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

Background

Almost a year ago we released our first public milestone (back then Tabris was RAP mobile). Since then we have worked hard towards the Tabris 1.0 release. The basic idea behind Tabris was always to use the SWT Java API to create UIs for mobile devices. This idea hasn’t changed much. Since the first milestone Tabris has had many adopters and we’ve received a lot of good feedback. One topic that especially got us thinking was stated as follows: “Tabris is nice and SWT allows me to create a rich UI. But, it doesn’t allow me to use common navigation concepts”. Said another way, the problem for developers is that each platform has it’s own navigation concepts. For Android this is the ActionBar and for iOS it is the View Controllers as highlighted in the screenshot below.

With plain SWT it’s not possible to create a UI using those concepts and as result it was not possible with the early versions of Tabris either. Note here, that the operative word in the last sentence is “was” -  because, we have created a small UI framework on top of SWT that enables you to create UIs using native navigation concepts. This framework now forms the core of Tabris.

Abstraction

Tabris is a framework for cross-platform mobile apps. The basic concept of Tabris is that you write the UI in Java and it runs on the server. A device calls the server and renders your UI with native components. This means that when you create an SWT Button on iOS, an iOS button will be created and on Android, an Android button will be created. As a result, you can create applications with one code base that serves multiple platforms. This means that we can’t (and don’t want to) port the concepts of the different platforms to a server side API. We have to create an abstraction! That is, an encapsulation of the concepts of all platforms into a simple, understandable API.

This API is called “Tabris UI”. The key parts are two types, Page and Action. To make it clear what these types are we can take a look at another image.

The red shaded area of these images is the Page which basically contains your controls. In the green shaded boxes you can see two Actions. An Action is an element that a user can press (to activate) and which is located outside of the Page.

Concepts

Let’s look a little deeper into Pages and Actions. Pages can be chained together in any order. This means a user’s button click can be used to open a new page. When you do this multiple times a chain will be created. Within this chain you will be able to browse backward to the previous page . This concept is called page chaining. Every chain has a root element. This is what we call the “top level” page. One application can have multiple top level pages and all can mark the beginning of a chain. Let’s take a look at a diagram.

This diagram could represent almost any application. The usual flow of an application is that you start on a top level page and browse through several pages, going deeper into the application. As you can see on the image this is what we call chaining. But one top level page is not enough for most application. Think about a bookstore application. The possible top level pages are “All Books, Favorites, Popular Books”. Each top level page will contain another set of books you can browse through. So, when you have several top level pages you need to be able to browse from one top level page to another or to browse from a normal page to a top level page. This is shown with the red arrows on the diagram. What’s not possible is to navigate from one page in a chain to a page in another chain because only one chain can exist at any given time. The pages in a chain are created when they are visited and they will be destroyed when you navigate in reverse and leave them (e.g. when you jump back to the top level page or the previous page).

Actions have a lifecycle similar to Pages. Similar but not exactly the same. Two types of Actions exist. Global Actions and Page Actions. A Global Action is visible regardless of which page the user is on. Page-Actions exist only on a specific page. They are created when the page is created and will be destroyed when the page is destroyed. You can see the difference in the following screenshots. In these images the Global Action is shaded in green. It has application scope. The Page-Action is shaded red. It has page scope.

Programming Model

You will create Page and Action objects to enable the main functions of your applications. And, in most cases you will quickly reach a point where the components need to communicate. Of course, you can access a Page directly from within an Action but this is not good practice. We prefer a loosely coupled communication between components. This communication can be accomplished by using a context. In the Tabris UI it’s called a UI and you can use it for navigation and influencing the state of actions too. The key feature of the communication is that you can a data store from it. When I talk about a store think about a simple Map, encapsulated in the type PageData. A PageData object has the same lifecycle as a page. Each page has it’s own data, even top level pages. This is because you will need to pass data in your chain. You can navigate to a new page and pass in a PageData object which then marks the page store of the new page. Let’s take a look at another diagram.

As you might notice it shows the same page chain as above. What’s different is that it shows the new PageData objects that will be passed to a new page. In this data you can save page state information such as a selection.

Configuration

What we have not described in the preceding paragraphs is how the different components come together. This is all done via configuration. To be explicit the type that matters is called UIConfiguration. You will need to create an instance and add your Page configurations and Action configurations to it. What are Page and Action configurations? As the name says, they are the configurations of a Page or an Action. A Page doesn’t know anything about it’s title, if it’s a top level page or about it’s image. And this is the same for Actions. This information needs to be declared within a PageConfiguration or ActionConfiguration object. The diagram below shows how this works.

As you can see, the Tabris UI framework is responsible for creating Page and Action objects from the configuration. This also means that you will need to add Page or Action Class objects to it’s configuration. After you have created your configuration it can be passed in as a constructor argument into the TabrisUIEntryPointFactory object. As a result this needs to be added to an Application within your ApplicationConfiguration implementation.

Ready to use

Using everything described above, you can write powerful applications that will have a platform specific user experience. We have created an example for the Tabris UI. It’s the bookstore example mentioned earlier. You can see the flow of this app in the picture below.

You can look into this example on github. It’s licensed under the EPL 1.0, so feel free to use it as a starting point for your application.

Outlook

The current implementation is targeted for phones because only one page can be visible at a time. Of course it can be used on tablets too, but having only one page at a time on a tablet is not the way most Apps work. We are working on an enhancement on top of the Tabris UI to be able to define groups of pages that can be visible at the same time for tablet devices.

We hope you will enjoy using the Tabris UI as much as we do. For me, it’s a breakthrough feature for Tabris and for cross-platform development for mobile apps. As always, feel free to disagree .

SWT Menus

Menus were an often requested feature in Tabris. With this milestone we have implemented support for menus on phones and tablets. A common use case for menus is a long press on any item within the UI. We even support dynamic menu items, so you can add items while the menu is open and they will be rendered correctly on the client. Just a note that when creating a menu, the style flags will be ignored because menus on mobile devices don’t currently support styles.

ClientDevice

The ClientDevice type has existed for a while now to gather information on which platform is accessing the server. For this milestone we have enhanced this type to get even more information about the client. We also transformed it into a ClientService to make it accessible with RWT.getClient().getService( ClientDevice.class ). You can get the following information from the ClientDevice:

• Timezone Offset: An offset in minutes to UTC. This is inherited from the RWT type ClientInfo.
• Locales: The locale used on the accessing device. Also from ClientInfo
• Orientation: The orientation of the accessing device. Can be landscape or portrait.
• Capabilities: Information regarding the capabilities of the accessing device such as phone or location capabilities.
• ConnectionType: The connection type of the accessing device. Can be wifi or cellular.
• Platform: The platform of the accessing device. Can be Android, iOS or web.

Accessing this information is really easy. Check out the following snippet:

ClientDevice device = RWT.getClient().getService( ClientDevice.class );
Orientation orientation = device.getOrientation();

We have also created a demo showing the full feature set, hosted on github.

ClientStore

One of the biggest advantages of Tabris is that it doesn’t store any relevant data on the device. But, sometimes it would be good to have small amounts of data stored, such as the ID of a previously logged-in user. This is comparable to cookies for a web-browser. A website will never store big data in a cookie but small ID’s that associate it with a data set stored on the server-side. With the new ClientStore implementation you can do exactly this. A small amount of data is stored on the device and is transferred back to the server during the next session (but not with every request as with cookies). Using the store can look like this:

ClientStore store = RWT.getClient().getService( ClientStore.class );
store.add( "foo", "bar" );
String bar = store.get( "foo" );

Tabris UI

A huge issue for all cross-platform technologies for mobile devices is that you can’t build an app that uses the native navigation concepts. I mean you can try to emulate these concepts but you will end up with messy code because you need to differentiate for each of the platforms. From my point of view this is also the biggest drawback of HTML5. In Tabris 0.11.0 we have created an abstraction for these navigation concepts. This enables you to create your application once and our client implementations will render it in a way typical for the platform it runs on. To make this clear we have created a “Bookstore” example which can be found on github. The following screenshots show the concepts of the Tabris UI using this example. I will tell you more about the details of the Tabris UI in a separate post.

What’s Next for Tabris

Over the next month we will concentrate on topics like bug fixing, stability and clean-up to create an awesome 1.0 release. Of course, you can comment on all topics and contribute your ideas – it’s all publicly available on GitHub Issues.

• Updated to Jersey 2.0 m11 and correspondingly to JAX-RS 2.0. A large rework was required in order to use JAX-RS 2.0 because the Jersey implementation changed a lot under the hood.
• Added the JAX-RS Consumer Version 1.0. It uses the JAX-RS 2.0 Client API to send requests.

Please read the README for more details. As always the changes are available as a p2 repository or can be downloaded directly from the GitHub repository (gh-pages branch). I would love to read some feedback .

As you might know, a while ago I created the OSGI-JAX-RS connector. This connector gives you the opportunity to publish your @Path/@Provider resources by registering them as OSGi services. So, why not consume a REST service as an OSGi service? That’s exactly what the JAX-RS Consumer OSGi integration provides. It registers an OSGi service called ConsumerPublisher. Using this service you can publish your @Path interfaces. The ConsumerPublisher creates consumer objects out of them and registers them as OSGi services. Afterwards you will be able to consume them as you do with all other OSGi services.

This is best explained with a small example. Let’s say we are using Declarative Services. So, this gives us the option to register a component and inject the ConsumerPublisher as in the code below.

public class Publisher {
 
  public void addConsumerPublisher( ConsumerPublisher publisher ) {
    publisher.publishConsumers( "http://server:port/root", 
                                new Class<?>[] { MyResource.class }, 
                                new Object[] {new CustomProvider() } );
  }
}

When the JAX-RS consumer bundle is started, the ConsumerPublisher service will be registered and is injected into our component. What we have to do additionally, is to add a base url, our @Path interfaces and the custom @Providers we want to use. The ConsumerPublisher takes care of creating the consumer objects out of the interfaces and registers them as OSGi services. In this example we can afterwards get/call a service of the type MyResource.

If you would like to try this out yourself I have created a p2 repository containing the consumer and it’s dependencies. A working example can also be found on GitHub. Any feedback is very welcome .

1. I don’t want to mess around with a crappy API.
2. I want to encapsulate the consumption of the service in a plain Java object.
3. I just want to consume REST services, so the library should have a small footprint.
4. I would love to reuse the specification of REST service which I have already used for the server side.

I will skip expectation number 1 because I don’t want to point fingers . Coming to the second point, my thoughts are that encapsulating a service is not the problem. I have also decided to encapsulate it by myself, if there is no other way. My research has led me to only one library that does this job for me. This is CRest, an annotation based API that is pretty similar to the one from JAX-RS and partly compatible with JAX-RS 1.0. But “pretty similar”and “partly compatible” isn’t enough from my point of view because this leads to duplicated interface definitions and version conflicts when using a newer JAX-RS version. I have also looked at libraries like the well-known Apache HTTP Client, an URLConnection abstraction from Kevin Sawicki or the JAX-RS 2.0 Client API and so on. Every library I looked at didn’t meet my expectations on one or two points.

My optimal vision of consuming REST services with Java would be to reuse the interface I have defined for the server-side (the @Path resource) and to create a consumer out of it automatically. Having such a solution would also guarantee compile time safety when building the server and the client because you need to define your interface just once and reuse it on both sides. Last week I found almost exactly what I was looking for. Apache CXF provides a proxy based API that takes a @Path resource and creates a consumer out of it. But as it is with most libraries, this cool functionality is part of a monolith. I don’t want 200 lines of dependency definitions, I don’t want dependencies to JAX-WS when doing JAX-RS and I don’t want to use a communication framework when I just want to consume some REST services  .

In the end I found myself implementing the library I needed on my own. The result is a very small library that consists of only about 500 lines of code and has the very fancy name JAX-RS Consumer. It gives you the opportunity to transform your @Path interface into a consumer object. Under the hood the Jersey client is used which is taking over tasks like the wiring between @Path and @Providers, sending the actual request, and so on. The single plain Java API it provides is best explained with an example:

MyResource resource = ConsumerFactory.createConsumer( "http://server:port/root", 
                                                    MyResource.class, 
                                                    new CustomProvider() );
resource.doSomething();

As you can see there is a ConsumerFactory which takes several arguments.  The first one is the base url of the service provider. The second is the class object of your @Path interface. The third is an optional varargs array of @Providers. It returns an instance of your service interface which sends the defined requests when accessing the object’s methods. If you want to try this out I have written a simple example that consumes a little GitHub API.

There is one more thing. The JAX-RS Consumer also has an OSGi integration, but this is a topic for another post. If you want to get familiar with the consumer here are the resources you will probably be looking for . Don’t be shy to open issues for it, it’s in an early state .

• git repository at GitHub (also contains the OSGi-JAX-RS Connector)
• Example consuming GitHub API
• Download: JAX-RS Consumer, Jersey 2.0 m10 incl. dependencies

Most of the time I work on the server-side. As a result my toolbox is full of libraries that are good for servers but not limited to them. So, I split up the tools into categories. Let’s start with the screwdrivers . Nothing bigger than a birdhouse can be built without screws! Screwdrivers in software development are core libraries. In my toolbox there are two.

The first one is Google Guava. You may have read some previous posts about Guava or you may already know this little library. For those of you who don’t, Guava is a core Library developed by, and also used at Google. It’s a good example of “What helps me, may help you”. This library contains a lot of helpers that you will find useful in your day-to-day work with Java. This includes working with collections, hashing, I/O, primitive types and others. It also contains what I think is a rich, enhanced feature set. This includes concepts for caching, functional idioms or an event bus. While most of the time I use the basics of this framework, I found the enhanced features are also useful for those special occasions.

When I am working with code that has to deal with date and time, the second core library that comes in handy is Joda Time. This library exists because Java’s Date API prior to 1.7 is simply “not so good“. The Joda guys rethought the problem of handling dates, and as a result created a well-designed, small, API for handling dates. Convince yourself with this self-explanatory example:

public boolean isAfterPayDay(DateTime datetime) {
  if (datetime.getMonthOfYear() == 2) {   // February is month 2!!
    return datetime.getDayOfMonth() > 26;
  }
  return datetime.getDayOfMonth() > 28;
}

When it comes to implementing a WebService e.g. a REST API, the screwdrivers don’t help much anymore. A special tool is needed like a pipe box spanner . Two of the libraries I like most for the server-side are Jersey and Gson.

Jersey is an implementation of the JAX-RS specification. This specification defines an annotation-based API that makes it possible to publish plain Java objects as web resources. While Jersey is the reference implementation of JAX-RS it also influenced the JAX-RS 2.0 specification by providing a Client API that as far as I can tell, acted as a basis for the specification’s client API. Another cool thing about Jersey is its loose coupling. It ships as different jar files. The full bundle contains a server, the client and all the other stuff needed. But it can also be used as a plain JAX-RS implementation by bridging the specification API and the Servlet API. A nice side effect is that all jar files are packaged as OSGi bundles and a good OSGi integration exists . A simple service can look like this:

// The Java class will be hosted at the URI path "/helloworld"
@Path( "/helloworld" )
public class HelloWorldResource {
 
  // The Java method will process HTTP GET requests
  @GET 
  // The Java method will produce content identified by the MIME Media
  // type "text/plain";
  @Produces( "text/plain" )
  public String getClichedMessage() {
    // Return some cliched textual content
    return "Hello World";
  }
}

Gson is not dedicated to server-side deployment, but is widely used on servers. It’s a mapper between Java Objects and JSON. This is nothing new but the API provided by Gson is very useable. I don’t know the Gson developers but they seem to have committed themselves to this principle: “Make it easy to do the commonly correct thing. Make it possible to do the exotic things.” As a result it’s very, very easy to de/serialize objects with Gson and the standard de/serialization is good enough for 90% of the use cases I’ve encountered. But when it comes to special de/serialization it’s possible to hook in and define per type de/serializers. A simple serialization of an object looks like this:

class BagOfPrimitives {
  private int value1 = 1;
  private String value2 = "abc";
  private transient int value3 = 3;
  BagOfPrimitives() {
    // no-args constructor
  }
}
 
...
BagOfPrimitives obj = new BagOfPrimitives();
Gson gson = new Gson();
String json = gson.toJson(obj);

When we talk about servers we also need to talk about clients. So, when a client is implemented that uses any kind of HTTP connection one task comes up every time. This is sending requests. Honestly, I could never understand why this topic was so hard. I mean, it’s just sending some Strings over the ether. If you search for Java HTTP libraries you will find a whole bunch of them with all kinds of fancy features. But sorry – we’re talking about tools and adding a whole framework for just sending HTTP requests feels odd to me. Of course, there is the URLConnection API, but from my point of view, this is as suboptimal as the standard Date API. Recently I found one HTTP client wrapper that really fit my needs. This is the HttpRequest class from Kevin Sawicki. It’s just a single class called HttpRequest that provides static methods to send requests. That’s it! Ok, it makes testing a little more complicated, but this is a topic for another post . A simple HTTP request with this tool looks like this:

String response = HttpRequest.get( "http://google.com" ).body();
System.out.println( "Response was: " + response);

The libraries above are very useful but we haven’t talked about the tools that really form an application. These are tools for testing! In our carpenter’s world, these are the spirit levels (with the bubble) . I always go with Junit, so most of the tools I will list are for this framework.

If a core library for testing exists, for me, it’s definitely Mockito. The Mockito developers have done their job right! They have combined a kick-ass API with a rich feature set, and I really believe that the creators have brought mocking in Java to a new level. Mockito provides a well-designed, fluent, API to handle mocks. Probably the most valuable feature of Mockito is that it allows me to stick with the “build, operate, check” testing pattern. A simple mocked test looks like this in Mockito:

public class SecondPartTest { 
  @Test
  public void testSomething() {
    Strategy strategy = mock( Strategy.class );
    Something objectUnderTest = new Something( strategy );
 
    objectUnderTest.doSomething();
 
    verify( strategy ).doSomethingConcrete();
  } 
}

The second library that is pretty handy is Caliper. It’s not really for testing but for performance measurement. (I just added this to the testing category for lack of a better place.) With Caliper you can code micro benchmarks. To understand what a micro benchmark is, it’s best to read the Caliper Definition:

A microbenchmark attempts to measure the performance of a “small” bit of code. These tests are typically in the sub-millisecond range. The code being tested usually performs no I/O, or else is a test of some single, specific I/O task.

Microbenchmarking is very different from profiling! When profiling, you work with an entire application, either in production or in an environment very painstakingly contrived to resemble production. Because of this, you get performance data that is, for lack of a better term, real. When you microbenchmark, you get a result that is essentially fictional, and you must be very careful about what conclusions you draw from it.

The cool thing about Caliper is that they also provide an app to view the results in a meaningful way. They also store the different runs of your tests for comparison. It’s worthwhile to take a look at it. A simple micro benchmark can look like this:

public class MyBenchmark extends SimpleBenchmark {
  public void timeMyOperation( int reps ) {
    for( int i = 0; i < reps; i++ ) {
      MyClass.myOperation();
    }
  }
}

The last tool for testing I wrote myself. (So, yes, here comes a little self-marketing .) This library is called restfuse and it’s for testing REST APIs. I wrote it to solve the pain of spending half  my test code building up simple requests. Restfuse just sits on top of JUnit and uses the JUnit @Rule mechanism to accomplish its tasks. The thinking behind it is that the request is just a configuration topic and this can be executed outside of the test method’s body. The result is an annotation-based API that’s also capable of testing asynchronous REST API’s. A simple test can look like this:

public class RestfuseTest {
 
  @Rule
  public Destination destination = new Destination( "http://restfuse.com" ); 
 
  @Context
  private Response response; // will be injected after every request
 
  @HttpTest( method = Method.GET, path = "/" )
  public void checkRestfuseOnlineStatus() {
    assertOk( response );
  }  
}

Now you know what’s in my toolbox! Feel free to disagree or let me have a look inside your toolbox by writing a comment .

As a side note: A few days ago I was asked why I would like to register @Path or @Provider annotated objects as OSGi services. The answer is that it enables you to wire up your REST interface with the rest of your system loosely. For example, the serialization in my system is an OSGi service too. So, when registering an @Provider as a service I can use Declarative Services to hook my serialization object into the provider. This enables me to separate domain and framework code because I don’t have to get the service myself – which is a good thing, right?

If you would like to use the connector here are the resources to start with:

• Jersey, the library used by the connector.
• JAX-RS 2.0 API Documentation.
• GitHub repository
• p2 repository: http://hstaudacher.github.com/osgi-jax-rs-connector
• Example for the @Provider integration.
• Example for registering @Path resources. Also available using DS.