RESTful web service using Jersey
--Mahesh Patil
The main goal of the JAX-RS specification is to make RESTful web service development easier
than it has been in the past. Jersey provides the connectors for web services through Java annotations.
The use of annotations allows us to create Jersey resources just as easily as we develop Plain Old Java Objects (POJOs).
In other words, we leave the intercepting of HTTP requests and representation negotiations to the
framework and we can then concentrate on the business rules necessary to solve our problem at hand.
I want to keep this blog very simple and that's why I'm going to cover only two (GET and POST)
of the four (GET, POST, PUT and DELETE) methods supported by HTTP.
Let's create web application project (select "Dynamic Web Project" in Eclipse) and name it as 'JerseyREST'. The jars required for our web service which are part of Jersey download are, jersey-core, jersey-server, jsr311-api and asm-3.1.jar. Make sure these files are present in lib directory of our web application folder; in our case it's "JerseyREST/WebContent/WEB-INF/lib" folder.
Jersey resource:
A Jersey resource is a plain Java class within the context of a web application that uses the
@Path annotation to define a URI. The value of the annotation is the URI relative to the web application context,
as deployed in the web server.
Now let's create new class which will be our service (resource) and specify Path annotation to this class as shown below.
What we are specifying here is that our service (resource) will be accessible using relative url "/helloworld".
@Path("/helloworld")
public class HelloWorldResource{
}
Now we need to handle various HTTP methods so let's add a method to handle GET request first. The
name of the method is not important. However, we should use descriptive names that are representative
of the problem we are solving.
@GET
@Produces("application/plain")
public String getMessage() {
// Forward request to service layer.
return "Hello World";
}
The @Produces annotation works with @GET, @POST, and @PUT. It lets the framework know what type of
representation to send back to the client. For the simplicity the MIME type specified for the get method
is "application/plain". You can specify any MIME type and can have number of get methods with different
MIME types. Lets say you can have another method with @Produces("application/json") for returning JSON object.
 |
|
 |
 |
If a client sends a request to a URI with a MIME type that is not supported by the resource, then an appropriate exception is thrown by Jersey. |  |
 |
 |
 |
We are now ready to use this web service. If you have downloaded the required library files (specified earlier) and created web project, deploy the application to your local web server or using 'run on server' option from Eclipse. To test the API, you can either use the Swing client (REST-Client specified in resources section) or can develop a client application using Jakarta Commons HTTP Client.
The GET method can be tested by just typing the URL in browser "http://localhost:8080/JerseyREST/helloworld" and you should see the message returned by our web service.
Now that you have seen our web service running and returning message to the GET method, let's implement POST method. As mentioned earlier, I'm keeping this blog as simple as possible without adding any complexities on either server or client side. An HTTP POST request is handled by an annotated method that looks like:
@POST
public String updateMessage(String payload){
}
The POST request has a payload that the framework intercepts and delivers to us in the parameter payload.
The value of the payload could be of any type, a simple String, an XML structure or could also be a
binary stream of, say, MIME type image/jpg, so our object type for the payload must change accordingly
RESTful web services exchange representations using URIs. However, because
we use web technologies and because of design decisions, we don't always use
representation such as XML structures. We sometimes need to provide other
means to transfer data such as plain HTML forms. This means that if a client sends
a request from an HTML form, we need to get access to the value/pair set that is
part of the request. To handle this there is an annotation @FormParam.
Lets say we wanted to support an HTML client having a form with two input parameters, name and city.
The Post method would look like shown below.
Add following method declaration to your service class.
@POST
@Consumes("application/x-www-form-urlencoded")
@Produces("application/plain")
public String updateMessage(@FormParam ("name") String name, @FormParam ("city") String city){
System.out.println("Name:" + name + " and City:" + city);
// Forward details to service layer.
return "Success";
}
|
|
|
|
The POST method doesn't have to Produce (return) anything back to the caller, but its good practice to return success/error message/code. | |
|
|
|
You can test this method by creating a form in HTML page and submitting it to "/helloworld" url or write client application. I'm going to show you another way of testing RESTFul application and that is using RESTClient.
The RESTClient looks like shown below:
You can specify the input parameters in Body tab as shown below. If you run the URL then you should see the success message in response body. Also you would see the input parameter printed out on the server log file.
Conclusion: As you can see using Jersey for implementing RESTful Web services is very easy. The learning curve is bare minimum as there are very few methods and corresponding annotations to learn.
| Resources: | |
| Jersey home page: | https://jersey.dev.java.net/ |
| Book: | RESTful Java Web Services by Jose Sandoval. This is a very good book if you want to get started with RESTful web services. |
| REST-Client: | RESTClient is a Java application to test RESTful webservices. It can be used to test variety of HTTP communications. |
| Other REST implementations: | RESTEasy(From JBoss) RESTlet |
