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:
1 2 3 4 5 6 7 8 9 | <dependencies>
...
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-servlet</artifactId>
<version>1.19.3</version>
</dependency>
...
</dependencies>
|
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | @Path("/MyService")
public class MyService {
@javax.ws.rs.GET
@javax.ws.rs.Path(value="/myMethod")
@javax.ws.rs.Produces(value={"application/json"})
public JSONObject myMethod(
@javax.ws.rs.QueryParam(value="name") String name) {
JSONObject ret = new JSONObject();
try {
ret.put("greeting", "Hello " + name + "!");
} catch (JSONException e) {
e.printStackTrace();
}
return ret;
}
}
|
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | private String getResponseString(HttpURLConnection c) throws IOException {
BufferedReader in = new BufferedReader( new InputStreamReader(c.getInputStream()) );
String inputLine;
StringBuffer responseString = new StringBuffer();
while ((inputLine = in.readLine()) != null)
responseString.append(inputLine);
in.close();
return responseString.toString();
}
@Test
public void testMyService_notNull() throws Exception {
String myMethodArg0_Name = "rochajoel";
+ "/MyService"
+ "/myMethod";
String parameters = "name=" + myMethodArg0_Name;
HttpURLConnection c = (HttpURLConnection) new URL(endpoint + "?" + parameters).openConnection();
final JSONObject response = new JSONObject(getResponseString(c));
assertNotNull(response.get("greeting"));
assertEquals("unexpected myMethod greeting",
"Hello " + myMethodArg0_Name + "!",
response.getString("greeting"));
}
@Test
public void testMyService_null() throws Exception {
String myMethodArg0_Name = null;
+ "/MyService"
+ "/myMethod";
HttpURLConnection c = (HttpURLConnection) new URL(endpoint).openConnection();
final JSONObject response = new JSONObject(getResponseString(c));
assertNotNull(response.get("greeting"));
assertEquals("unexpected myMethod greeting",
"Hello " + myMethodArg0_Name + "!",
response.getString("greeting"));
}
|
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | <?xml version="1.0" encoding="UTF-8"?>
<web-app>
<display-name>MyService</display-name>
<servlet>
<servlet-name>restServlet</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer
</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>ext.domain.pkg</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>restServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>120</session-timeout>
</session-config>
</web-app>
|
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!
