Exception handling in RESTful web services (JAX-RS) is a very important concept, in this article we are going to explain it step by step with an example. check this article for Creating Simple Maven RESTful Web Service Project in Eclipse.
As we are dealing with exception handling here, we are going to create a service which will throw an exception.
pom.xml
0 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 |
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>RESTExceptionHandlingExample</groupId> <artifactId>RESTExceptionHandlingExample</artifactId> <version>0.0.1-SNAPSHOT</version> <packaging>war</packaging> <name>WebServicesJAXRS</name> <description>Restfull Webservices</description> <dependencies> <dependency> <groupId>com.sun.jersey</groupId> <artifactId>jersey-server</artifactId> <version>1.19</version> </dependency> <dependency> <groupId>com.sun.jersey</groupId> <artifactId>jersey-servlet</artifactId> <version>1.19</version> </dependency> </dependencies> <build> <sourceDirectory>RESTExceptionHandlingExample</sourceDirectory> <plugins> <plugin> <artifactId>maven-war-plugin</artifactId> <version>2.3</version> <configuration> <warSourceDirectory>WebContent</warSourceDirectory> <failOnMissingWebXml>false</failOnMissingWebXml> </configuration> </plugin> </plugins> </build> </project> |
web.xml
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<?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"> <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.codenuclear</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> </web-app> |
RESTResource.java
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
package com.codenuclear; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.core.Response; @Path("/users") public class RESTResource { @GET @Path("/checkProfile/{id}") public Response getAdminDetails(@PathParam("id") String id) { String msg = RESTService.checkCustomerStatus(id); return Response.status(200).entity(msg).build(); } } |
RESTService.java
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
package com.codenuclear; public class RESTService { static CallDB cdb = new CallDB(); public static String checkCustomerStatus(String custId){ MyData da = cdb.getStatus(custId); return da.getStatus().trim(); } } |
CallDB.java
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
package com.codenuclear; public class CallDB { public MyData getStatus(String custId) { // Lets say, database logic will go here and setting the output in MyData bean MyData da = new MyData(); // da.setStatus("Valid"); return da; } } |
MyData.java
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
package com.codenuclear; public class MyData { String status; public String getStatus() { return status; } public void setStatus(String status) { this.status = status; } } |
Explanation
In this Example we have created 4 java classes to understand Exception Handling in Web Services.
- RESTResource.java
- RESTService.java
- CallDB.java
- MyData.java
The application will start by hitting the following URL
http://localhost:8080/WebServices_JAX_RS/rest/users/checkProfile/100- If you hit the above URL, the flow will come to RESTResource.java, in that at line number 15, we are calling checkCustomerStatus() function of RESTService class, by passing the id.
- Consider, CallDB is a class which handle all database related stuff, so in RESTService.java at line number 11, we are calling getStatus() of CallDB.
- In CallDB.java consider we had a database call at line number 7, after that creating MyData class object and setting all the data that We have retrieved from the database and returning it at line number 13, if you observe line number 11, We have commented the setter method, means We are not setting status, so by default it contains NULL value. ( if we call its getter method, it will return NULL)
- Now the flow will come to RESTService.java at line number 11, We are calling getStatus(), as this gives null value [as we have not set anything in CallDB at line 11], on that null We are calling .trim() again, which will give NullPointerException.
So successfully we are able to create a service, which will throw a NullPointerException. If you hit the URL, you will see.

Custom (user defined) run time exception
Now,We are going to create a custom (user defined) run time exception, lets say my custom exception class name is CustomerDataNotFoundException.
Here We have just created an exception class with constructor which takes String as an argument.
CustomerDataNotFoundException.java
0 1 2 3 4 5 6 7 8 9 10 11 |
package com.codenuclear.ExceptionHandlingRelated; public class CustomerDataNotFoundException extends RuntimeException { private static final long serialVersionUID = 1L; public CustomerDataNotFoundException(String exceptionMsg) { super(exceptionMsg); } } |
Now let me change RESTService.java as:
RESTService.java
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
package com.codenuclear; import com.codenuclear.ExceptionHandlingRelated.CustomerDataNotFoundException; public class RESTService { static CallDB cdb = new CallDB(); public static String checkCustomerStatus(String custId){ MyData da = cdb.getStatus(custId); if(da.getStatus() == null) { throw new CustomerDataNotFoundException("Customer status not found with id "+custId); } return da.getStatus().trim(); } } |
We are checking the status with if condition. If status is NULL, throwing out the custom exception by passing some meaningful message. Lets run the application and see.

Its throwing our exception with the message we have sent.That’s all for Exception Handling in Web Services, Hope you liked it. Keep Learning and Sharing 🙂 !!