Jersey RESTful Webservices Tutorial with examples

REST is an architectural style which was brought in by Roy Fielding in 2000 in his doctoral thesis. In the web services terms, REpresentational State Transfer (REST) is a stateless client-server architecture in which the web services are viewed as resources and can be identified by their URIs. Web service clients that want to use these resources access via globally defined set of remote methods that describe the action to be performed on the resource.

It consists of two components REST server which provides access to the resources and a REST client which accesses and modify the REST resources.

REST fundamentals

• Everything in REST is considered as a resource.
• Every resource is identified by an URI.
• Uses uniform interfaces. Resources are handled uing POST, GET, PUT, DELETE operations which are similar to Create, Read, update and Delete(CRUD) operations.
• Be stateless. Every request is an independent request. Each request from client to server must contain all the information necessary to understand the request.
• Communications are done via representations. E.g. XML, JSON RESTful Web Services
  A RESTFul web services are based on HTTP methods and the concept of REST. A RESTFul web service typically defines the base URI for the services, the supported MIME-types (XML, text, JSON, user-defined, ...) and the set of operations (POST, GET, PUT, DELETE) which are supported.

HTTP methods
The PUT, GET, POST and DELETE methods are typical used in REST based architectures.
The following table gives an explanation of these operations.

• GET defines a reading access of the resource without side-effects. The resource is never changed via a GET request, e.g., the request has no side effects (idempotent).
• PUT creates a new resource. It must also be idempotent.
• DELETE removes the resources. The operations are idempotent. They can get repeated without leading to different results.
• POST updates an existing resource or creates a new resource.

JAX-RS
JAX-RS is an annotation-based API for implementing RESTful web services, based on HTTP, in Java. Essentially, classes and methods are annotated with information that enables a runtime to expose them as resources. A runtime that implements JAX-RS mediates between the HTTP protocol and the Java classes, taking into account URIs, requested and accepted content types, and HTTP methods.
Jersey framework implemented JSR-RS(JSR-311) reference APIs. In addition to Jersey various other implementation are available such as Retlet, JBOSS RESTeasy, Apache CXF etc.
Download the Jersey distribution as zip file from the Jersey download site.

Jersey
Jersey contains having following major parts:

• Core Server: To build RESTful web services based on annotation include key libraries such as : jersey-core.jar, jersey-server.jar, jsr311-api.jar, asm.jar
• Core Client: The Jersey client API helps you to easily communicate with REST services include libabry ersey-client.jar
• JAXB support: (Used in the advanced example) jaxb-impl.jar, jaxb-api.jar, activation.jar, stax-api.jar, wstx-asl.jar
• JSON support: (Used in the advanced example) jersey-json.jar
• Integration: Jersey also provides libraries that can easily integrate with Spring, Guice, Apache Abdera, and so on.

Create your first Hello World RESTful Webservice
We have used jersey jaxrs-ri-2.12 and apache-tomcat-7.0.55 to run below example.
STEP 1 : Create a new Dynamic Web Project called TutorialsDesk.RestHelloWorld.

STEP 2 : Copy all JARs from your Jersey download into the WEB-INF/lib folder.

aopalliance-repackaged-2.3.0-b10.jar
asm-debug-all-5.0.2.jar
hk2-api-2.3.0-b10.jar
hk2-locator-2.3.0-b10.jar
hk2-utils-2.3.0-b10.jar
javassist-3.18.1-GA.jar
javax.annotation-api-1.2.jar
javax.inject-2.3.0-b10.jar
javax.servlet-api-3.0.1.jar
javax.ws.rs-api-2.0.1.jar
jaxb-api-2.2.7.jar
jersey-client.jar
jersey-common.jar
jersey-container-servlet.jar
jersey-container-servlet-core.jar
jersey-guava-2.12.jar
jersey-server.jar
org.osgi.core-4.2.0.jar
osgi-resource-locator-1.0.1.jar
persistence-api-1.0.jar
validation-api-1.1.0.Final.jar

STEP 3 : Create the following HelloWorld.java class.

package com.tutorialsdesk.rest.helloworld;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

// Plain old Java Object it does not extend as class or implements 
// an interface

// The class registers its methods for the HTTP GET request using the @GET annotation. 
// Using the @Produces annotation, it defines that it can deliver several MIME types,
// text, XML and HTML. 

// The browser requests per default the HTML MIME type.

//Sets the path to base URL + /hello
@Path("/helloworld")
public class HelloWorld {

  // This method is called if TEXT_PLAIN is request
  @GET
  @Produces(MediaType.TEXT_PLAIN)
  public String sayPlainTextHello() {
    return "Hello World REST Web Services !";
  }

  // This method is called if XML is request
  @GET
  @Produces(MediaType.TEXT_XML)
  public String sayXMLHello() {
    return "<?xml version=\"1.0\"?>" + "<hello> Hello World REST Web Services !" + "</hello>";
  }

  // This method is called if HTML is request
  @GET
  @Produces(MediaType.TEXT_HTML)
  public String sayHtmlHello() {
    return "<html> " + "<title>" + "Hello World REST Web Services !" + "</title>"
        + "<body><h1>" + "Hello World REST Web Services !" + "</body></h1>" + "</html> ";
  }

} 

This class register itself as a get resource via the @GET annotation. Via the @Produces annotation it defines that it delivers the text and the HTML MIME types. It also defines via the @Path annotation that its service is available under the hello URL.

The browser will always request the HTML MIME type. To see the text version, you can use tool like curl.
Define Jersey Servlet dispatcher

STEP 4 : You need to register Jersey as the servlet dispatcher for REST requests. Open the file web.xml and modify it to the following.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">
  <display-name>TutorialsDesk.RestHelloWorld</display-name>
 <servlet>
    <servlet-name>REST Web Services Hello World</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
     <!-- Register resources and providers under com.tutorialsdesk.rest.helloworld package. -->
    <init-param>
        <param-name>jersey.config.server.provider.packages</param-name>
        <param-value>com.tutorialsdesk.rest.helloworld</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>REST Web Services Hello World</servlet-name>
    <url-pattern>/rest/*</url-pattern>
  </servlet-mapping>
</web-app> 

The parameter jersey.config.server.provider.packages defines in which package Jersey will look for the web service classes. This property must point to your resources classes. The URL pattern defines the part of the base URL your application will be placed.

Run your rest service
You should be able to access your resources under the following URL: http://localhost:8080/TutorialsDesk.RestHelloWorld/rest/helloworld

This name is derived from the "display-name" defined in the web.xml file, augmented with the servlet-mapping URL-pattern and the helloworld @Path annotation from your class file. You should get the message "Hello World REST Web Services !".

This is a basic Hello World example of RESTful Web Services, Keep visiting TutorialsDesk for more tutorials and practical programming examples on Web Services in java.

Hope we are able to explain you RESTful Web Services Hello World Example, if you have any questions or suggestions please write to us using contact us form.(Second Menu from top left).

Please share us on social media if you like the tutorial.

SHARE