RESTful WebServices Tutorial with Maven+Tomcat+Failsafe

Technology credits:

Apache Maven & Failsafe

Apache Tomcat

Jersey

Disclosure

Before you start reading further: Keep in mind that this is a work in progress, and although i'm a "Systems&Informatics Engineer" i consider myself a novice programmer. If you have any question you don't see answered here, please leave your comment on the section below to help me improve this article.
Also, you should be aware that this post was a result of a lot of work. If you like it, please feel free to show your appreciation by offering me a cup of coffee through paypal and/or add value to this article by sharing your knowledge.

Objectives of this tutorial:

• To establish a standard "archetype" for RESTful JAX-WS WebServices development
• To demonstrate how a Maven project can build-deploy-test a RESTful WebService

Pre-requisites:

• You have knowledge on Plain Old Java Objects (POJO's) development.
• You understand the concept of WebService, it's benefits and are able to decide when and how it should be used.
• You understand the diference between a RESTful WebService and a SOAP WebService
• You understand the concept of "server side container" and it's purpose.
• You have downloaded and installed the Maven build software, or you are using Maven through the m2e Eclipse plug-in

The sources for this project are available here. Just unzip it and build it using 'mvn clean verify' (on the cmd line or 'clean verify' targets using the m2e Eclipse plugin)

Conventions over Configuration

First of all, as we will be using the Maven WAR plugin we should be aware of the project's file structure that is required by this plugin (as well as other conventions required by Maven which i won't discuss here)

As you can see from the picture above, all you need to build and deploy a RESTful WebService to Tomcat are this 4 files (the ones above with the SVN icon). Be aware that the Maven WAR plugin requires you to have the web.xml at that specific location so that they can be included in the deployment to Tomcat. We will talk about each file in the following sections.

What should the pom.xml contain?

The pom.xml is the Maven build file and contains all the required configurations to build, deploy and test the project. In this tutorial, it only contains the configurations that are absolutely essential for this project to pass the tests. I will talk here about the essentials of the configuration that prepare the WAR for proper Tomcat deployment and the Failsafe plug-in.

Get ready for WAR

So... What do we need to get started? First of all let's start by calling some friends to the WAR :P We will need some "dependencies" to resolve our classpath needs:
This is the Jersey Servlet that will use our classes to generate URLs and forward the REST requests to the appropriate classes. This will be more clear when we configure the web.xml

Other than this, we just need to create the POJO files and annotate them with the appropriate declarations to be processed by Jersey

The WebService

In here i use a JSONObject return instead of a plain String so that this can be more than just the simple 'Hello World!' example. JSONObjects allow us to transfer complex datatypes over a standard data type language similar to XML but with a smaller footprint. This is great when you want to improve communications throughput or when working with constrained devices such as mobile phones or others. This also allows you to see that if you develop your own datatypes by extending from JSONObject you can return them like this and Jersey will take care of the serialization for you :)
Also: We can also receive JSONObjects as a parameter they work the same as a String, it's just a matter of URL encoding them on the request

That (aside from the web.xml configuration) will be all we need to run our first RESTful WebService
But don't trust me, let's test it using the Maven Failsafe&Tomcat plugins! :)

Integration test programmatically

To ensure the code above, and the integration of all technologies work as expected, lets develop a simple set of tests to ensure basic communication is as expected.

We will create tests started with IT*.java or ended in *IT.java or *ITCase.java. This classes are just like standard JUnit tests, only the filename pattern is different. The configuration is in the Maven POM but this time i wont go into details. You can see other tutorials that talk about this here

The WebService configuration files

I acknowledge that it takes quite a configuration effort to put the WebService "up and running" but this is the last step. Take it easy :)

The web.xml: What are we saying here?
First of all, a WebService is not a Servlet. A servlet is the basic "entrance point" for any J2EE application. It's like a Main class for J2SE. Because of that, we must tell Tomcat which Servlet do we want him to invoke at what address. As we didn't develop any, we must use one from another provider :) This is were the com.sun.jersey.spi.container.servlet.ServletContainer comes along to save our back. Next, we configure it to inspect all classes in ext.domain.pkg and gather information from the annotations we provided earlier.
That's it! Just run your 'mvn clean verify' and you should be able to "succed your build" with 0 failures.

Happy Coding!