In a recent blog post Peter Kriens commented that the OSGi service model is as important as object-orientation. I feel the same – I don’t want to write software without this concept anymore. But for me, the service model only makes sense when it’s used together with the modularity OSGi provides. I think the modularisation layer is the greatest advantage of the OSGi platform and the services are really only there to simplify the communication between modules.
When it comes to developing a REST API with Java, this advantage is missing in most of today’s libraries (e.g. Restlet or Jersey), because the Java language still lacks modularity. But especially for the design of a REST API this concept can be a great benefit, because it overcomes the limitation of only being able to separate REST services by url and Java packages. With modularity the service implementations can be separated into modules which improves the maintainability and the beauty of the whole system a lot.
A few months ago I discovered JAX-RS for developing REST services. (Before that I used Restlet.) I have to say that the JAX-RS API makes it really easy to develop REST services. See this article for a how-to. A reference implementation of this API is Jersey. The cool thing about this implementation is that it plays really well together with the OSGi HttpService and it ships as bundles. In this way we have the option to actively deploy REST services into the HttpService. But is this how we want to publish REST services? To me, it’s not!
In my ideal world I would write my @Path annotated Pojos and publish them as OSGi services. That’s it. The runtime should take care of publishing and service wiring. Sadly, Jersey has no built-in feature for that. This is the reason I wrote a little OSGi-JAX-RS connector. The only thing the connector does is that it publishes OSGi services as REST services using JAX-RS. Of course, there are OSGi remote services, but using them does not allow the use of JAX-RS the way I’d prefer, namely as a lightweight additional bundle.
You can find the connector in GitHub. To make it work simply install it into your OSGi instance by using this jar. (You’ll also find a p2 repository there). That’s it. The only thing you have to take care of is writing the REST services like the one in this example.
@Path( "/osgi-jax-rs" )
public class ExampleService {
@GET
public String seyHello() {
return "JAX-RS and OSGi are a lovely couple.";
}
}The activator can then look like this:
public class Activator implements BundleActivator {
private ServiceRegistration<?> registration;
@Override
public void start( BundleContext context ) throws Exception {
ExampleService exampleService = new ExampleService();
registration = context.registerService( ExampleService.class.getName(), exampleService, null );
}
@Override
public void stop( BundleContext context ) throws Exception {
registration.unregister();
}
}Further instructions can be found in the README of the git repository. It also contains two examples for using this connector with and without declarative services. In the second part of this blog series I will show you how to configure the services using the OSGi Configuration Admin Service and publish services on different ports within the same OSGi instance. I hope you enjoy this connector as much as I do.
Tags: jax-rs, jersey, OSGi, rest, restlet
As you might know from previous posts, most of my work time has something to do with the development of REST based systems. The systems we develop are mostly written in Java. To ensure that a system works, we have a step in our continuous integration process that executes integration tests before automated deployment is launched. With this short post I’d like to show you our setup for these integration tests because when I searched a few months ago the results were rare.
We write integration tests for REST systems with JUnit and restfuse. Check this post for a how-to on restfuse. Thanks to the Maven surefire plugin we can simply execute these tests in our maven build. Here is the build and dependency section of the test module’s pom.
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>test</id>
<phase>test</phase>
<configuration>
<testClassesDirectory>${project.build.outputDirectory}</testClassesDirectory>
</configuration>
<goals>
<goal>test</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.8.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.restfuse</groupId>
<artifactId>com.eclipsesource.restfuse</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>Most of our Java-REST applications ship as war files. So, at this stage the question becomes, “How can I test the war file I just built?” One answer is to hot deploy the war file and run the tests against it. But, for a hot deployment we need a server running tomcat (or another servlet container), right? Actually, we don’t 
. We can simply embed a Jetty plugin into our maven build, start it and deploy our war file using the Maven Jetty plugin. The related section in the pom looks like this:
<build>
<plugins>
...
<plugin>
<groupId>org.mortbay.jetty</groupId>
<artifactId>maven-jetty-plugin</artifactId>
<version>${jetty-version}</version>
<configuration>
<scanIntervalSeconds>10</scanIntervalSeconds>
<stopKey>foo</stopKey>
<stopPort>9090</stopPort>
<contextPath>/</contextPath>
<tmpDirectory>/tmp/work/</tmpDirectory>
<webApp>/tmp/test.war</webApp>
<daemon>true</daemon>
<reload>manual</reload>
</configuration>
<executions>
<execution>
<id>start-jetty</id>
<phase>test-compile</phase>
<goals>
<goal>deploy-war</goal>
</goals>
</execution>
<execution>
<id>stop-jetty</id>
<phase>verify</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>It is important that we deploy the war file before the actual test phase, in our example, during test-compile. To make this work we need to copy the new war file into the configured directory before we run the maven build. This can be accomplished with a simple shell script. The following snippet shows how it looked for our jenkins job:
rm -rf /tmp/work
mkdir /tmp/work
cp $WORKSPACE/../job/**/*.war /tmp/test.war
A few last points. In our setup we split the integration test build from the main build but you can merge them together as well. And, when using restfuse an important thing to keep in mind is that you need to configure the port to be the same as the one jetty uses to run the tests.
That’s it – short but efficient. Maybe you have a similar approach to share in a comment with us?
Tags: continuous integration, jetty, maven, rest, restfuse
For several projects at EclipseSource we are creating REST APIs. I’m involved in most of them and there is one thing that bothers me with every project. That is, testing. I mean, of course we are writing our unit tests first and we mock our services to get fast unit tests, but at some point you also have to make sure that the whole system works with integration tests. And, when writing integration tests for REST APIs in Java, as far as I know, there are currently only two solutions.
The first one is to write plain JUnit tests and do all the requests yourself within the test methods (maybe with the help of utilities). The other option is to use a library called rest-assured. This library provides a kind of DSL for testing REST APIs. You can write your tests with JUnit and use mockito-like syntax to send a request and test the response. But this doesn’t feel like the right solution, because you always have to configure your request with real Java code within your test method. I would prefer a solution where I can simply configure the request using something like annotations and just execute the test after the request is sent.
Another thing that bugs me are asynchronous services. When it comes to handling asynchronous services you always have two options: callbacks or polling. How can I test those services? For polling it’s easier – you can loop the request code – but does this sound right to you? For callbacks you have to open a server, again within your test method or before. It seems there are no cool solutions for this right now – even rest-assured can’t handle these services very well. That’s why I took a little time and tried to solve these problems. The result is a small library called restfuse.
Restfuse is a JUnit extension. It introduces an annotation called @HttpTest which can be used to configure a request. The request is sent before the annotated method is executed as a test method. The response is then injected into the test object and can be used within the test method. It also provides some new asserts like assertNotFound or assertOk to test response codes. A simple @HttpTest looks like this:
@RunWith( HttpJUnitRunner.class )
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 );
}
}And of course, it also solves the problem with asynchronous services by introducing two annotations called @Callback and @Poll which can be used together with the @HttpTest annotation. For more information on these tests for asynchronous services take a look at the restfuse site.
Restfuse is open source, licensed under the EPL v – 1.0 and is hosted at github. The 1.0 version is also in the Maven Central and online as a p2 repository (yes, it’s an OSGi bundle). I hope this small library will help you as much as it helped me. I would appreciate feedback on how to make restfuse even better.
Tags: junit, OSGi, rest, restfuse, testing
A few months ago I introduced you to REST. Since then my Google Summer of Code project, REST abstraction for ECF, has been accepted and a lot of work has been done. Scott Lewis and I wanted to make the use of any REST services as simple as possible and whats simpler for a bundle developer than an OSGi service?
First I want to give you a little code snippet to see how we access a REST based web services:
IConnectContext context =
ConnectContextFactory.createUsernamePasswordConnectContext("user", "password");
container.setConnectContextForAuthentication(context);
remoteService = container.getRemoteService(RestService.class.getName());
try {
remoteService.callSync(new RestRemoteCall("getUserTimeline"));
TwitterService service = (TwitterService) remoteService.getProxy();
IUserTimeline timeline = service.getTimeline();
IUserStatus[] userStatuses = timeline.getUserStatuses();
// do something with the userStatuses
} catch (ECFException e) {
// handle exception
}What have we done? We use an ECF container to get an IRemoteService object which we use to call an IRemoteCall with the method getUserTimeline. After this we access the service’s proxy object which is an instance of TwitterService.
As you surely imagine this snippet has something to do with twitter
Twitter provides its services over a REST based API. The messages you post to twitter are stored in a timeline because every message has its unique timestamp. To access your own timeline you can use the URL: http://twitter.com/statuses/user_timeline.json. But this URL is not defined in the above code snippet. So where do we define this kind of resource? Therefore we can use our own ECF container. So let us define a TwitterContainer which extends RestContainer.
public class TwitterContainer extends RestContainer {
public TwitterContainer(ID restId) {
super(restId);
Map twitterMethods = new HashMap();
try {
twitterMethods.put("getUserTimeline",
new GetRestCall(new URI("/statuses/user_timeline.json"),
"ecf.rest.resource.json.org",
new Object[]{"count=2"}, null, 10000));
registerRestService(new String[] { ITwitter.class.getName() },
new TwitterService(), twitterMethods, null);
} catch (URISyntaxException e) {
// handle exception
} catch (ECFException e) {
// handle exception
}
}
}As you see, we register a REST service with the timeline URL and a String called “getUserTimeline”. This String acts as a key for a specific REST service and will be associated with an IRemoteCall instance. These values are stored in a Map and registered in the container with an instance of TwitterService. TwitterService is a simple POJO which just needs to implement one interface called IRestResponseProcessor. This is needed because the parsed response has to be passed to an service object. With the parsed response, the service object can almost do everything. For example, bringing up an object model for Twitter’s timeline. If we look back to the first snippet, we see that the service is accessed via the key registered in this container. So we can register as many services we want and simply access them with a container instance at any point.
To put it all in a nutshell, we have to register our REST service as a POJO in an ECF container and just call it. This sounds almost like ordinary OSGi Services doesn’t it?
I have pre implemented two scenarios (twitter and google search) which you can check out at the project page.
I would love to hear your feedback so feel free to post comments or post on the ecf-dev mailing list.
Tags: ecf, eclipse, OSGi, rest
