Tutorial

Jersey Java Tutorial

Published on August 3, 2022
author

Pankaj

Jersey Java Tutorial

Welcome to Java Jersey Tutorial. Recently I started working on a Restful web service project using the JAX-RS Jersey framework.

What is Java Jersey Framework?

Java Jersey project tracks the JAX-RS API, which is used to create Restful web services in Java. jersey java, jersey tutorial, JAX-RS tutorial

1. Who should use this tutorial?

This tutorial is intended for Java programmers who are interested in developing and deploying Restful Web Services using JAX-RS API and JAXB.

2. Prerequisites

The scope of this tutorial is to use Jersey API for creating Restful web services and invoking the web service using a Java client program and testing web service using the tool. Basic understanding of Java, Web Services, XML, Maven, and any application server (JBoss/Tomcat) is required to understand the tutorial with ease.

3. Softwares and Tools

  • JDK version 1.8.0_131
  • Apache Maven 3.5.3
  • Mac OS X 10.13.4
  • Tomcat 8.5.16
  • Eclipse Java EE IDE Oxygen 4.7.3

Creating Jersey Eclipse Maven Project

Create a “Dynamic Web Project” in Eclipse and then convert it to the maven project. This will provide us a maven based web application basic project. I have given GroupId as com.journaldev.jersey and artifactID as my-jersey-project but you can specify anything you like. Once we complete the development of our project, the project structure will look like the below image. jersey java tutorial eclipse project

Java Jersey Restful Web Service Project Explanation

1. pom.xml: Project configuration details, note the jersey dependencies provided, other details are common for any similar maven project.

<project xmlns="https://maven.apache.org/POM/4.0.0"
	xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.journaldev.jersey</groupId>
	<artifactId>my-jersey-project</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>war</packaging>

	<dependencies>
		<dependency>
			<groupId>com.sun.jersey</groupId>
			<artifactId>jersey-server</artifactId>
			<version>1.14</version>
		</dependency>
		<dependency>
			<groupId>com.sun.jersey</groupId>
			<artifactId>jersey-servlet</artifactId>
			<version>1.14</version>
		</dependency>
		<dependency>
			<groupId>com.sun.jersey</groupId>
			<artifactId>jersey-client</artifactId>
			<version>1.14</version>
		</dependency>
	</dependencies>

	<build>
		<finalName>My-Jersey-Project</finalName>
		<plugins>
			<plugin>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.7.0</version>
				<configuration>
					<source>1.8</source>
					<target>1.8</target>
				</configuration>
			</plugin>
			<plugin>
				<artifactId>maven-war-plugin</artifactId>
				<version>3.0.0</version>
				<configuration>
					<warSourceDirectory>WebContent</warSourceDirectory>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

2. EmpRequest.java: Java Bean for the request object. The important thing to note here is the @XmlRootElement annotation to map the class to an XML element.

package com.journaldev.model;

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "empRequest")
public class EmpRequest {
	private int id;
	private String name;

	public int getId() {
		return id;
	}

	public void setId(int id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}
}

3. EmpResponse.java: Java bean for the response object.

package com.journaldev.model;

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "empResponse")
public class EmpResponse {
	private int id;
	private String name;

	public int getId() {
		return id;
	}

	public void setId(int id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

}

4. ErrorResponse.java: Java Bean that will be sent as the response in case of an exception.

package com.journaldev.model;

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "errorResponse")
public class ErrorResponse {

	private String errorCode;
	private int errorId;

	public String getErrorCode() {
		return errorCode;
	}

	public void setErrorCode(String errorCode) {
		this.errorCode = errorCode;
	}

	public int getErrorId() {
		return errorId;
	}

	public void setErrorId(int errorId) {
		this.errorId = errorId;
	}

}

5. EmpNotFoundException.java: A normal exception class thrown in the web service.

package com.journaldev.exception;

public class EmpNotFoundException extends Exception {

	private static final long serialVersionUID = 4351720088030656859L;
	private int errorId;

	public int getErrorId() {
		return errorId;
	}

	public EmpNotFoundException(String msg, int errorId) {
		super(msg);
		this.errorId = errorId;
	}

	public EmpNotFoundException(String msg, Throwable cause) {
		super(msg, cause);
	}
}

6. web.xml: Deployment descriptor for the web service. So any request with URI https://<HOST>:<PORT>/My-Jersey-Project/rest/* will be processed by Jersey ServletContainer servlet. The init-param value passed for “com.sun.jersey.config.property.packages” defines the package jersey will look for the web service classes. This property must point to your resources classes. It also looks for the resource classes into the sub-packages.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
	xmlns="https://java.sun.com/xml/ns/javaee"
	xsi:schemaLocation="https://java.sun.com/xml/ns/javaee https://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
	id="WebApp_ID" version="3.0">
	<display-name>My Jersey Project</display-name>

	<!-- Jersey Servlet configurations -->
	<servlet>
		<servlet-name>Jersey REST Service</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>com.journaldev</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>
	<servlet-mapping>
		<servlet-name>Jersey REST Service</servlet-name>
		<url-pattern>/rest/*</url-pattern>
	</servlet-mapping>
	<!-- Jersey Servlet configurations -->

</web-app>

7. EmpRouter.java: Resource class handling different kinds of request.

  • @Path(“/emp”) - All the requests with URI https://<HOST>:<PORT>/My-Jersey-Project/rest/emp/ will be processed by this resource class.
  • @Path(“/getEmp”) - All the requests with URI https://<HOST>:<PORT>/My-Jersey-Project/rest/emp/getEmp will be processed by this method.
  • @POST - This annotation defines that the HTTP method used should be POST. Some other possible values are @GET, @PUT, @DELETE
  • @Consumes(MediaType.APPLICATION_XML) - The method accepts XML element
  • @Produces(MediaType.APPLICATION_XML) - The method returns XML element
package com.journaldev.router;

import com.journaldev.exception.EmpNotFoundException;
import com.journaldev.model.*;

import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.xml.bind.JAXBElement;

@Path("/emp")
public class EmpRouter {

	@POST
	@Path("/getEmp")
	@Consumes(MediaType.APPLICATION_XML)
	@Produces(MediaType.APPLICATION_XML)
	public Response getEmp(JAXBElement<EmpRequest> empRequest)
			throws EmpNotFoundException {
		EmpResponse empResponse = new EmpResponse();
		if (empRequest.getValue().getId() == 1) {
			empResponse.setId(empRequest.getValue().getId());
			empResponse.setName(empRequest.getValue().getName());
		} else {
			throw new EmpNotFoundException("Wrong ID", empRequest.getValue()
					.getId());
		}
		return Response.ok(empResponse).build();
	}
}

8. EmpNotFoundExceptionMapper.java: Exception Mapper class that maps EmpNotFoundException to Response object. The class should have @Provider annotation. This class should be in the package provided for resource classes in web.xml. Implementation of toResponse() method generates the ErrorResponse object and set it as Entity in Response object with status as INTERNAL_SERVER_ERROR.

package com.journaldev.exceptionmapper;

import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.ext.ExceptionMapper;
import javax.ws.rs.ext.Provider;

import com.journaldev.exception.EmpNotFoundException;
import com.journaldev.model.ErrorResponse;

@Provider
public class EmpNotFoundExceptionMapper implements
		ExceptionMapper<EmpNotFoundException> {

	public EmpNotFoundExceptionMapper() {
	}
	
	public Response toResponse(
			EmpNotFoundException empNotFoundException) {
		ErrorResponse errorResponse = new ErrorResponse();
		errorResponse.setErrorId(empNotFoundException.getErrorId());
		errorResponse.setErrorCode(empNotFoundException.getMessage());
		return Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(
				errorResponse).type(
				MediaType.APPLICATION_XML).build();

	}

}

Our web service is ready, just build it to create the WAR file and deploy it to the application server.

Jersey Client Example

We can use the Jersey Client to call our web service and get a response programmatically. EmpClient.java: This is a sample java program through which are invoking our web service. We are using Jersey Client API to invoke the service and based on response status we are parsing response entity to EmpResponse or ErrorResponse class.

package com.journaldev.client;

import javax.ws.rs.core.MediaType;

import com.journaldev.model.EmpRequest;
import com.journaldev.model.EmpResponse;
import com.journaldev.model.ErrorResponse;
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;

public class EmpClient {

	/**
	 * @param args
	 */
	public static void main(String[] args) {
		String uri = "https://localhost:8080/My-Jersey-Project/rest/emp/getEmp";
		EmpRequest request = new EmpRequest();
		// set id as 1 for OK response
		request.setId(2);
		request.setName("PK");
		try {
			Client client = Client.create();
			WebResource r = client.resource(uri);
			ClientResponse response = r.type(MediaType.APPLICATION_XML).post(ClientResponse.class, request);
			System.out.println(response.getStatus());
			if (response.getStatus() == 200) {
				EmpResponse empResponse = response.getEntity(EmpResponse.class);
				System.out.println(empResponse.getId() + "::" + empResponse.getName());
			} else {
				ErrorResponse exc = response.getEntity(ErrorResponse.class);
				System.out.println(exc.getErrorCode());
				System.out.println(exc.getErrorId());
			}
		} catch (Exception e) {
			System.out.println(e.getMessage());
		}
	}

}

Success Response Jersey Client Example Error Response Jersey Client Exception Example

Summary

In this post, we learned how to create a REST web service using Jersey API. We also looked into the Jersey Client to invoke our REST APIs through java program.

You can checkout complete project code from our GitHub Repository.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar
Pankaj

author

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
JournalDev
DigitalOcean Employee
DigitalOcean Employee badge
May 8, 2020

If I want to use content type JSON instead of XML, what changes do I have to make?

- Venkat

    JournalDev
    DigitalOcean Employee
    DigitalOcean Employee badge
    October 21, 2018

    for a complete example with Java 11, jersey and a vue-JS frontend checkout this project on github. https://github.com/mrin9/Angular-SpringBoot-REST-JWT

    - Mrin

      JournalDev
      DigitalOcean Employee
      DigitalOcean Employee badge
      September 17, 2016

      after writing this program how to run this program means how to call Client class , After deploying the project on tomcat server I am getting following message; Unsupported Media Type description The server refused this request because the request entity is in a format not supported by the requested resource for the requested method. Can u plz help me…

      - shobha

        JournalDev
        DigitalOcean Employee
        DigitalOcean Employee badge
        June 3, 2016

        Hello Pankaj, The sample program given above giving me following error. “A message body reader for Java class com.genericjersey.pojo.ErrorResponse, and Java type class com.genericjersey.pojo.ErrorResponse, and MIME media type text/html;charset=utf-8 was not found” So could you please help me out to find where i am lacking at my code.

        - Riya

          JournalDev
          DigitalOcean Employee
          DigitalOcean Employee badge
          January 28, 2016

          Hi pankaj, Tomacat is not an application server. correct it .

          - Sreekanth Gude

            JournalDev
            DigitalOcean Employee
            DigitalOcean Employee badge
            August 5, 2015

            Hi Pankaj, Good write up. My question was about EmployeeRequest &EmployeeResponse classes. Do we need them if we could return an instance of Employee itself?

            - Naveen

              JournalDev
              DigitalOcean Employee
              DigitalOcean Employee badge
              March 24, 2015

              package nee; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.MultivaluedMap; import com.sun.jersey.api.client.Client; import com.sun.jersey.api.client.ClientResponse; import com.sun.jersey.api.client.WebResource; import com.sun.jersey.core.util.MultivaluedMapImpl; /* * excerpt of the maven dependencies com.sun.jersey jersey-client 1.19 com.sun.jersey jersey-core 1.19 */ public class ClientTest { public static void main(String[] args) { if(args.length != 4) { System.out.println(“Incorrect parameters, usage:”); System.out.println(“java -jar neelclienttest.jar run_id tweet_id tweet_to_annotate rest_api”); System.exit(1); } String runID = args[0]; String tweetID = args[1]; String tweet = args[2]; String uri = args[3]; try { String annotations = annotate(uri, runID, tweetID, tweet); System.out.println(annotations); } catch (Exception e) { e.printStackTrace(); } } public static String annotate(String uri, String runID, String tweetID, String tweet) throws Exception { Client client = Client.create(); WebResource webResource = client.resource(uri); MultivaluedMap params = new MultivaluedMapImpl(); params.add(“RunID”, runID); params.add(“TweetID”, tweetID); params.add(“Tweet”, tweet); ClientResponse response = webResource. accept(MediaType.TEXT_PLAIN_TYPE). post(ClientResponse.class, params); // check if status code != 200 OK if ( response.getStatus() != 200 ) throw new Exception (“The REST interface has answered with an unexpected status code” + response.getStatus()); return response.getEntity(String.class); } } Would you please explain us what exactaly this program will do it>

              - vinayakumar

                JournalDev
                DigitalOcean Employee
                DigitalOcean Employee badge
                November 24, 2014

                sir can u plzz give a example of how to write the client pgm using jersey 2.x

                - partha

                  JournalDev
                  DigitalOcean Employee
                  DigitalOcean Employee badge
                  October 15, 2014

                  Pankaj, Excellent and brief content about REST webservices. Can you please explain about SOAP, WSDL also. Thanks, Sowmya

                  - Sowmya

                    JournalDev
                    DigitalOcean Employee
                    DigitalOcean Employee badge
                    July 2, 2014

                    The content and the collection of questions on your website is amazing. Please provide some interview questions on SOAP and REST webservices.

                    - Kavya Jindal

                      Try DigitalOcean for free

                      Click below to sign up and get $200 of credit to try our products over 60 days!

                      Sign up

                      Join the Tech Talk
                      Success! Thank you! Please check your email for further details.

                      Please complete your information!

                      Become a contributor for community

                      Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

                      DigitalOcean Documentation

                      Full documentation for every DigitalOcean product.

                      Resources for startups and SMBs

                      The Wave has everything you need to know about building a business, from raising funding to marketing your product.

                      Get our newsletter

                      Stay up to date by signing up for DigitalOcean’s Infrastructure as a Newsletter.

                      New accounts only. By submitting your email you agree to our Privacy Policy

                      The developer cloud

                      Scale up as you grow — whether you're running one virtual machine or ten thousand.

                      Get started for free

                      Sign up and get $200 in credit for your first 60 days with DigitalOcean.*

                      *This promotional offer applies to new accounts only.