Using JAX-RS 2 Client API in Liberty and Bluemix

Matti Tahvonen
Matti Tahvonen
On Mar 5, 2015 5:52:00 PM

I’m a big fan of JAX-RS 2.0 Client API, a part of Java EE 7 specification. They make writing stuff that depends on external REST services really easy on JVM. If you don’t know about the client API, you should definitely check out my recent tutorial for JAX-RS Client APIs.

I just started a project to create clean well typed Java APIs for Watson services) available via Bluemix. It’s a perfect task for the JAX-RS 2 Client API. Although the default web server in Bluemix, WebSphere Liberty, is not yet a certified Java EE 7 server, you can actually already use many of the goodies in Java EE 7, including JAX-RS 2.

Enable JAX-RS 2 in Liberty

To enable those for your application, you should get familiar with your Liberty server’s server.xml file. You can find it from your development server’s usr/servers/defaultServer/ directory or via IDE. There you need to add jax-rs-2.0 to the section. You should note that it also depends on some other newer API versions, so in case your feature manager contains other older features, there might appear conflicts. In my example application, I have the following dependencies enabled:


Add the API to your project

Now Liberty provides the newer version of JAX-RS API, but you still need to provide the API also for your application. I did this by brutally adding the whole Java EE 7 API to my project’s pom.xml:


Eclipse might now become a bit picky to deploy the application to Liberty, but in IntelliJ it works flawlessly. If you can’t make it work with Eclipse, try adding only the JAX-RS 2 API, instead the whole Java EE 7 specification.

Configure the object mapper

The default object mapper in Liberty uses a bit older version of Jackson. In case you are building a modern app with modern JAX-RS 2, you might want to use a newer version. Luckily, you can pretty easily configure the object mapper used by your Client instance. You can just manually instantiate a Jackson 2 JacksonJaxbJsonProvider and register that in your ClientBuilder. I’m using CDI in my example, so it was really handy to just create the following producer:

private JacksonJaxbJsonProvider provider = new JacksonJaxbJsonProvider();

public Client createJaxRsClient() {
    return ClientBuilder.newBuilder()

Deploying to Bluemix

The most tricky part is probably making the deployment work with Bluemix. Bluemix has a rather new version of Liberty Profile, but in case you want to use the beta features, you cannot just use the basic cf push my-app -p target/*.war. You’ll need to set IBM_LIBERTY_BETA environment variable to true and somehow provide the server.xml file that defines the feature set you wish to use.

To set the environment variable, you can simply issue the following cf command:

cf set-env <your-server> IBM_LIBERTY_BETA true

To package the server.xml I decided to save the server.xml “template” (with feature definitions and war file definition), to src/main/libertyserver. Then I created a small assembly trick (assembly.xml + plugin to pom.xml) that builds a deployable directory layout with the target/libertyserver/server.xml file and the war file in target/libertyserver/apps/myapp.war. The Bluemix buildpack will then merge the server.xml configs with those that it defines and deploy the war file. Then you can after mvn install just use the following command:

cf push <your-watson-demo-server> -p target/liberty-bluemix/liberty


The fluent JAX-RS 2 API is reality today and you can pretty easily use the version provided by the latest Liberty beta releases, also in the Bluemix. It is a really handy API to accessing REST services, such as Watson APIs in Bluemix. Once I got the setup right, implementing APIs is now really easy, in case something is missing from my project, I’m really happy to get pull requests for new features.

To get a simple example of such a setup, check out my recently started project for Watson Java APIs. That might also be a good basis for your Vaadin + Bluemix Challence!

Java API to Watson services

Matti Tahvonen
Matti Tahvonen
Matti Tahvonen has a long history in Vaadin R&D: developing the core framework from the dark ages of pure JS client side to the GWT era and creating number of official and unofficial Vaadin add-ons. His current responsibility is to keep you up to date with latest and greatest Vaadin related technologies. You can follow him on Twitter – @MattiTahvonen
Other posts by Matti Tahvonen