In this article, we will learn and implement a JAX-RS Restful web service using JAXB. Although there are various types of input/output formats can be used for request/response for web service interaction, but in this particular example we will use XML
Jersey is the most popular amongst Restful web service development. Latest Jersey 2.x version has been developed by Oracle/Glassfish team in accordance with JAX-RS 2.0 specification. Earlier Jersey 1.x version was developed and supported by Oracle/Sun team
Latest Jersey release version is 2.12 see here and look documentation and API for details. We will implement Jersey examples in the following articles based on latest 2.x version
JAX-RS specification supports the conversion of Java objects to XML and vice-versa on the fly with the help of JAXB i.e.; marshalling/un-marshalling
When it is finalized to use XML then start designing your XML Schema Definition (XSD) for your service and call the help of JAXB Maven plugin to generate java-sources, as it is considered standard. So, before starting to develop a web service it is important to spend good amount of time in writing XSD for your service
In this example, we will implement a service covering all CURD operations using annotations such as @GET, @POST, @PUT and @DELETE. Also, we will use @Consumes, @Produces and MediaType annotations to send & receive XML for the web service request/response
Annotation Used
- @Path (ws.rs.Path)
- @GET (ws.rs.GET)
- @POST (ws.rs.POST)
- @PUT (ws.rs.PUT)
- @DELETE (ws.rs.DELETE)
- @PathParam (ws.rs.PathParam)
- @Consumes (ws.rs.Consumes)
- @Produces (ws.rs.Produces)
- MediaType (ws.rs.core.MediaType)
Technology Used
- Java 1.7
- Eclipse Luna IDE
- Jersey-2.12
- Apache Maven 3.2.1
- Apache Tomcat 8.0.54
- Glassfish-4.1
Mavenize or download required jars
Add Jersey-2.12 dependencies to pom.xml
<properties> <jersey.version>2.12</jersey.version> <jersey.scope>compile</jersey.scope> <compileSource>1.7</compileSource> <maven.compiler.target>1.7</maven.compiler.target> <maven.compiler.source>1.7</maven.compiler.source> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <dependencies> <!-- Jersey core Servlet 2.x implementation --> <dependency> <groupId>org.glassfish.jersey.containers</groupId> <artifactId>jersey-container-servlet-core</artifactId> <version>${jersey.version}</version> <scope>${jersey.scope}</scope> </dependency> </dependencies>
Folks who aren’t familiar with Maven concepts or don’t require maven for their project, can download the below jars individually from the central repository or maven repository and include them in the classpath
- jersey-container-servlet-core
- javax.ws.rs-api-2.0.1
- jersey-server-2.12
- jersey-common-2.12
- jersey-client-2.12
- jersey-guava-2.12
- javax-annotation-api-1.2
- javax.inject-2.3.0-b10
- hk2-api-2.3.0-b10
- hk2-utils-2.3.0-b10
- aop-alliance-repackaged-2.3.0-b10
- hk2-locator
- javassist-3.18.1-GA
- validation-api-1.1.0.Final
- osgi-resource-locator-1.0.1
JAXB – Generating java source files from XSD
Steps to generate java-sources from XML Schema Definition (XSD)
- configure JAXB Maven plugin in pom.xml
- write well-defined XSD for your service
- use maven command “mvn generate-sources” to generate java source files
Configure JAXB Maven plugin
<!-- JAXB plugin to generate-sources from XSD --> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>jaxb2-maven-plugin</artifactId> <version>1.6</version> <executions> <execution> <goals> <goal>xjc</goal><!-- xjc/generate --> </goals> <configuration> <outputDirectory>${basedir}/generated/java/source</outputDirectory> <schemaDirectory>${basedir}/src/main/resources/com/jersey/series/xml/service/entities </schemaDirectory> <schemaFiles>*.xsd</schemaFiles> <schemaLanguage>XMLSCHEMA</schemaLanguage> <extension>true</extension> <args> <arg>-XtoString</arg> </args> <plugins> <plugin> <groupId>org.jvnet.jaxb2_commons</groupId> <artifactId>jaxb2-basics</artifactId> <version>0.6.4</version> </plugin> </plugins> </configuration> </execution> </executions> </plugin>
Book.xsd
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://benchresources.in/cdm/Book" xmlns:tns="http://benchresources.in/cdm/Book" elementFormDefault="qualified"> <!-- book object with four attributes --> <xsd:element name="BookType"> <xsd:complexType> <xsd:sequence> <xsd:element name="bookId" type="xsd:int" /> <xsd:element name="bookName" type="xsd:string" /> <xsd:element name="author" type="xsd:string" /> <xsd:element name="category" type="xsd:string" /> </xsd:sequence> </xsd:complexType> </xsd:element> <!-- an object to contain lists of books referencing above Book object --> <xsd:element name="BookListType"> <xsd:complexType> <xsd:sequence> <xsd:element ref="tns:BookType" minOccurs="0" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>
Below XSD contains two elements with name “BookType” and “BookListType”
- BookType contains four attributes namely bookId, bookName, author, category
- BookListType which returns list of BookType
Run mvn generate-sources
Look at the generated java source files in the generated folder
BookType.java
package in.benchresources.cdm.book; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; import javax.xml.bind.annotation.XmlType; @XmlAccessorType(XmlAccessType.FIELD) @XmlType(name = "", propOrder = { "bookId", "bookName", "author", "category" }) @XmlRootElement(name = "BookType") public class BookType { protected int bookId; @XmlElement(required = true) protected String bookName; @XmlElement(required = true) protected String author; @XmlElement(required = true) protected String category; public int getBookId() { return bookId; } public void setBookId(int value) { this.bookId = value; } public String getBookName() { return bookName; } public void setBookName(String value) { this.bookName = value; } public String getAuthor() { return author; } public void setAuthor(String value) { this.author = value; } public String getCategory() { return category; } public void setCategory(String value) { this.category = value; } }
BookListType.java
package in.benchresources.cdm.book; import java.util.ArrayList; import java.util.List; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; import javax.xml.bind.annotation.XmlType; @XmlAccessorType(XmlAccessType.FIELD) @XmlType(name = "", propOrder = { "bookType" }) @XmlRootElement(name = "BookListType") public class BookListType { @XmlElement(name = "BookType") protected List<BookType> bookType; public List<BookType> getBookType() { if (bookType == null) { bookType = new ArrayList<BookType>(); } return this.bookType; } }
Directory Structure
Before moving on, let us understand the directory/package structure once you create project in Eclipse IDE
Maven has to follow certain directory structure
- src/test/java –> test related files, mostly JUnit test cases
- src/main/java –> create java source files under this folder
- src/main/resources –> all configuration files placed here
- src/test/resources –> all test related configuration files placed here
- Maven Dependencies or Referenced Libraries –> includes jars in the classpath
- WEB-INF under webapp –> stores web.xml & other configuration files related to web application
Project Structure (Package Explorer view in Eclipse)
Jars Libraries Used in the Project (Maven Dependencies)
Web application
For any web application, entry point is web.xml which describes how the incoming http requests are served / processed. Further, it describes about the global-context and local-context param (i.e.; <context-param> & <init-param>) for loading files particular to project requirements & contains respective listener
With this introduction, we will understand how we configured web.xml for Jersey JAX-RS Restful web service
web.xml (the entry point –> under WEB-INF)
This web.xml file describes,
- Like any JEE web framework register “org.glassfish.jersey.servlet.ServletContainer” with servlet container
- http requests with URL pattern “/rest/*” will be sent to the registered servlet called “jersey-servlet” i.e.; (org.glassfish.jersey.servlet.ServletContainer)
- Set <init-param> with <param-name> as “jersey.config.server.provider.packages” and <param-value> describing the qualified package name of the JAX-RS annotated Resource/Provider classes. In this example, “com.jersey.series.xml.service”
- <welcome-file-list> files under this tag is the start-up page
web.xml
<?xml version="1.0" encoding="UTF-8"?> <web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"> <display-name>Jersey-XML-IO</display-name> <!-- Jersey Servlet --> <servlet> <servlet-name>jersey-servlet</servlet-name> <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> <!-- Register resources and providers --> <init-param> <param-name>jersey.config.server.provider.packages</param-name> <param-value>com.jersey.series.xml.service</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>jersey-servlet</servlet-name> <url-pattern>/rest/*</url-pattern> </servlet-mapping> <!-- welcome file --> <welcome-file-list> <welcome-file>index.html</welcome-file> </welcome-file-list> </web-app>
Let’s see coding in action
URL Pattern
Http url for any common web application is http://<server>:<port>/<root-context>/<from_here_application_specific_path>
In our example, we are going to deploy the war into Tomcat 8.0 server so our server and port are localhost and 8080 respectively. Context root is the project name i.e.; Jersey-XML-IO. Initial path for this application is http://localhost:8080/Jersey-XML-IO
We have configured “/rest/*” as url-pattern for the “jersey-servlet” servlet in web.xml and at class-level path configured is “/bookservice” using @Path annotation. Next respective path for each method annotated with @Path (method-level)
Book Service interface
Defines basic CRUD operations for Book Service
NOTE: It’s always a good programming practice to do code-to-interface and have its implementation separately
IBookService.java
package com.jersey.series.xml.service; import in.benchresources.cdm.book.BookListType; import in.benchresources.cdm.book.BookType; public interface IBookService { // Basic CRUD operations for Book Service public String createOrSaveBookInfo(BookType bookType); public BookType getBookInfo(int bookId); public String updateBookInfo(BookType bookType); public String deleteBookInfo(int bookId); public BookListType getAllBookInfo(); }
Book Service implementation
Implements above interface
Defines simple CURD operations
- @POST – create/inserts a new resource (adds new book information)
- @GET – read/selects internal resource representation based on the bookId
- @PUT – update/modifies an internal resource representation (modify book)
- @DELETE – delete/removes a resource (delete book)
- @GET – retrieves all books (get all books information)
Let’s discuss @Produces, @Consumes and MediaType
@Consumes
Defines which MIME type is consumed by this method. For this example, exposed methods are restricted to consume only XML data and it is annotated with @Consumes(MediaType.APPLICATION_XML)
@Produces
Defines which MIME type it will produce. For this example, exposed methods are restricted to produce only XML data and it is annotated with @Produces(MediaType.APPLICATION_XML)
Most widely used Media Types are
- APPLICATION_XML,
- APPLICATION_JSON,
- TEXT_PLAIN,
- TEXT_XML,
- APPLICATION_FORM_URLENCODED,
- etc
Note: Jersey doesn’t inherit JAX-RS annotations. So we are annotating Resource/Provider classes and then defining qualified package name in web.xml
BookServiceImpl.java
package com.jersey.series.xml.service; import in.benchresources.cdm.book.BookListType; import in.benchresources.cdm.book.BookType; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.PUT; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; @Path("/bookservice") public class BookServiceImpl implements IBookService { // Basic CRUD operations for Book Service // http://localhost:8080/Jersey-XML-IO/rest/bookservice/addbook @POST @Path("addbook") @Consumes(MediaType.APPLICATION_XML) @Produces(MediaType.APPLICATION_FORM_URLENCODED) public String createOrSaveBookInfo(BookType bookType) { // get book information from formal arguments and inserts into database & return bookId (primary_key) return "New Book information saved successfully with Book_ID " + bookType.getBookId(); } // http://localhost:8080/Jersey-XML-IO/rest/bookservice/getbook/10001 @GET @Path("getbook/{id}") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces(MediaType.APPLICATION_XML) public BookType getBookInfo(@PathParam("id") int bookId) { // retrieve book information based on the id supplied in the formal argument BookType bookType = new BookType(); bookType.setBookId(bookId); bookType.setBookName("Molecular Biology of The Gene"); bookType.setAuthor("James D Watson"); bookType.setCategory("Microbiology"); return bookType; } // http://localhost:8080/Jersey-XML-IO/rest/bookservice/updatebook @PUT @Path("updatebook") @Consumes(MediaType.APPLICATION_XML) @Produces(MediaType.APPLICATION_FORM_URLENCODED) public String updateBookInfo(BookType bookType) { // update book info & return SUCCESS message return "Book information updated successfully"; } // http://localhost:8080/Jersey-XML-IO/rest/bookservice/deletebook/10002 @DELETE @Path("deletebook/{id}") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces(MediaType.APPLICATION_FORM_URLENCODED) public String deleteBookInfo(@PathParam("id") int bookId) { // delete book info & return SUCCESS message return "Book information with Book_ID " + bookId + " deleted successfully"; } // http://localhost:8080/Jersey-XML-IO/rest/bookservice/getallbook @GET @Path("getallbook") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces(MediaType.APPLICATION_XML) public BookListType getAllBookInfo() { // create a object of type BookListType which takes book objects in its list BookListType bookListType = new BookListType(); BookType bookOne = new BookType(); bookOne.setBookId(10002); bookOne.setBookName("Cellular and Molecular Immunology"); bookOne.setAuthor("Abul K. Abbas"); bookOne.setCategory("Immunology"); bookListType.getBookType().add(bookOne); // add to bookListType BookType bookTwo = new BookType(); bookTwo.setBookId(10003); bookTwo.setBookName("Medical Physiology"); bookTwo.setAuthor("Walter F. Boron"); bookTwo.setCategory("Physiology"); bookListType.getBookType().add(bookTwo); // add to bookListType return bookListType; } }
Tomcat-8.0.12 Deployment
- Run maven command to build the war: mvn clean install (use command prompt or integrated maven in eclipse IDE
- Copy(ctrl+c) the war file from the target folder
- Paste(ctrl+v) it into apache tomcat (webapps folder)
- Start the tomcat server
Glassfish-4.1 Deployment
- Run maven command to build the war: mvn clean install (use command prompt or integrated maven in eclipse IDE
- Once you see “BUILD SUCCESS” after running maven command, keep the war file ready to be deployed
- There are two ways to deploy war file into Glassfish-4.1
- Online
- Offline
- Click here to understand above deployments process in detail
Test the service !!
Testing
There are many ways to do testing
- Access html page from web browser
- Copy the URL of GET service into web browser
- Advanced REST client from Google Chrome
- Rest client in Mozilla Firefox Add On
- Write your own client for example, Java client using improved CloseableHttpClient from Apache
- JDK’s in-built classes like HttpURLConnection
- Using Client, WebTarget from core JAX-RS classes javax.ws.rs.client
1. Using RestClient from Mozilla Firefox Add-On
First service: @POST (createOrSaveBookInfo())
URL: http://localhost:8080/Jersey-XML-IO/rest/bookservice/addbook
Request:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <BookType xmlns="http://benchresources.in/cdm/Book"> <bookId>10001</bookId> <bookName>Molecular Biology of The Gene</bookName> <author>James D Watson</author> <category>Microbiology</category> </BookType>
Content-Type: application/xml
Accept: application/x-www-form-urlencoded
Response: New Book information saved successfully with Book_ID 10001
Second service: @GET (getBookInfo())
URL: http://localhost:8080/Jersey-XML-IO/rest/bookservice/getbook/10001
Request: None
Content-Type: application/x-www-form-urlencoded
Accept: application/xml
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <BookType xmlns="http://benchresources.in/cdm/Book"> <bookId>10001</bookId> <bookName>Molecular Biology of The Gene</bookName> <author>James D Watson</author> <category>Microbiology</category> </BookType>
Third service: @PUT (updateBookInfo())
URL: http://localhost:8080/Jersey-XML-IO/rest/bookservice/updatebook
Request:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <BookType xmlns="http://benchresources.in/cdm/Book"> <bookId>10001</bookId> <bookName>Molecular Biology of The Gene</bookName> <author>James D Watson</author> <category>Microbiology</category> </BookType>
Content-Type: application/xml
Accept: application/x-www-form-urlencoded
Response: Book information updated successfully
Fourth service: @DELETE (deleteBookInfo())
URL: http://localhost:8080/Jersey-XML-IO/rest/bookservice/deletebook/10002
Request: None
Content-Type: application/x-www-form-urlencoded
Accept: application/x-www-form-urlencoded
Response: Book information with Book_ID 10002 deleted successfully
Fifth service: @GET (getAllBookInfo())
URL: http://localhost:8080/Jersey-XML-IO/rest/bookservice/getallbook
Request: None
Content-Type: application/x-www-form-urlencoded
Accept: application/xml
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <BookListType xmlns="http://benchresources.in/cdm/Book"> <BookType> <bookId>10002</bookId> <bookName>Cellular and Molecular Immunology</bookName> <author>Abul K. Abbas</author> <category>Immunology</category> </BookType> <BookType> <bookId>10003</bookId> <bookName>Medical Physiology</bookName> <author>Walter F. Boron</author> <category>Physiology</category> </BookType> </BookListType>
2. Java client
Uses Client, ClientBuilder, WebTarget and Response classes from core JAX-RS package javax.ws.rs.client for invoking Restful web service
Note: Commented lines will help out us to try (set) various http request header parameters
TestBookService.java
package test.jersey.series.xml.service; import javax.ws.rs.client.Client; import javax.ws.rs.client.ClientBuilder; import javax.ws.rs.client.Entity; import javax.ws.rs.client.Invocation; import javax.ws.rs.client.Invocation.Builder; import javax.ws.rs.client.WebTarget; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.Response; import org.glassfish.jersey.client.ClientConfig; public class TestBookService { public static void main(String[] args) { // setting & invoking first service getBook/10001 System.out.println("Invoking and executing getBook service for book id 10001"); String httpGetURL = "http://localhost:8080/Jersey-XML-IO/rest/bookservice/getbook/10001"; String responseStringGet = testBookServiceForGetRequest(httpGetURL); System.out.println("GET >> Response String : " + responseStringGet); // setting & invoking second service addBook with XML request System.out.println("\n\nInvoking and executing addBook service with request XML"); String httpPostURL = "http://localhost:8080/Jersey-XML-IO/rest/bookservice/addbook"; String requestString = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>" + "<BookType xmlns=\"http://benchresources.in/cdm/Book\">" + "<bookId>10001</bookId>" + "<bookName>Molecular Biology of The Gene</bookName>" + "<author>James D Watson</author>" + "<category>Microbiology</category>" + "</BookType>"; String responseStringPost = testBookServiceForPostRequest(httpPostURL, requestString); System.out.println("POST >> Response String : " + responseStringPost); } /** * * @param httpURL * @return */ public static String testBookServiceForGetRequest(String httpURL){ // local variables ClientConfig clientConfig = null; Client client = null; WebTarget webTarget = null; Invocation.Builder invocationBuilder = null; Response response = null; int responseCode; String responseMessageFromServer = null; String responseString = null; try{ // invoke service after setting necessary parameters clientConfig = new ClientConfig(); client = ClientBuilder.newClient(clientConfig); // client.property("Content-Type", MediaType.APPLICATION_FORM_URLENCODED); // client.property("accept", MediaType.APPLICATION_XML); webTarget = client.target(httpURL); // invoke service invocationBuilder = webTarget.request(MediaType.APPLICATION_FORM_URLENCODED).accept(MediaType.APPLICATION_XML); // invocationBuilder.header("some-header", "header-value"); response = invocationBuilder.get(); // get response code responseCode = response.getStatus(); System.out.println("Response code: " + responseCode); if (response.getStatus() != 200) { throw new RuntimeException("Failed with HTTP error code : " + responseCode); } // get response message responseMessageFromServer = response.getStatusInfo().getReasonPhrase(); System.out.println("ResponseMessageFromServer: " + responseMessageFromServer); // get response string responseString = response.readEntity(String.class); } catch(Exception ex) { ex.printStackTrace(); } finally{ // release resources, if any response.close(); client.close(); } return responseString; } /** * * @param httpURL * @param requestString * @return */ public static String testBookServiceForPostRequest(String httpURL, String requestString) { // local variables ClientConfig clientConfig = null; Client client = null; WebTarget webTarget = null; Builder builder = null; Response response = null; int responseCode; String responseMessageFromServer = null; String responseString = null; try{ // invoke service after setting necessary parameters clientConfig = new ClientConfig(); client = ClientBuilder.newClient(clientConfig); // client.property("Content-Type", MediaType.APPLICATION_FORM_URLENCODED); // client.property("accept", MediaType.APPLICATION_XML); webTarget = client.target(httpURL); // invoke service builder = webTarget.request(MediaType.APPLICATION_FORM_URLENCODED).accept(MediaType.APPLICATION_XML); response = builder.post(Entity.entity(requestString, MediaType.APPLICATION_XML)); // get response code responseCode = response.getStatus(); System.out.println("Response code: " + responseCode); if (response.getStatus() != 200) { throw new RuntimeException("Failed with HTTP error code : " + responseCode); } // get response message responseMessageFromServer = response.getStatusInfo().getReasonPhrase(); System.out.println("ResponseMessageFromServer: " + responseMessageFromServer); // get response string responseString = response.readEntity(String.class); } catch(Exception ex) { ex.printStackTrace(); } finally{ // release resources, if any response.close(); client.close(); } return responseString; } }
Output in console
Invoking and executing getBook service for book id 10001 Response code: 200 ResponseMessageFromServer: OK GET >> Response String : <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <BookType xmlns="http://benchresources.in/cdm/Book"> <bookId>10001</bookId> <bookName>Molecular Biology of The Gene</bookName> <author>James D Watson</author> <category>Microbiology</category> </BookType> Invoking and executing addBook service with request XML Response code: 200 ResponseMessageFromServer: OK POST >> Response String : New Book information saved successfully with Book_ID 10001
Conclusion: With the help of JAXB, XML can be used to exchange the request/response in Restful web service
In the next article, we will see how we can use JSON to exchange the request/response in Restful web service
Download project
Jersey-2x-XML-IO (7kB)
Happy Coding !!
Happy Learning !!