JAVA EE 7 RESTful API JAX-RS + Jersey 2 on Tomcat 9.

Introduction

I have written this post as I had spent way too much time trying to run a Java EE 7 RESTful API using the newest possible libraries and publish it on a Tomcat server. First thing you need to know is that JAX RS API can't just run on a Tomcat server naively. It is just a specification to which you need to add a proper implementation of this technology. At this point Jersey RESTful Web Services framework comes into play. If you go trough the official Java EE tutorial (by Oracle) you don't see it clearly stated (however, there are some references to Jersey), because during the tutorial you are suppose to use Glassfish server, which per default contains Jersey libraries. If you still don't like the fact (as I did) you need to use some third party libraries in order to get the pure Java EE 7, please bear in mind that Oracle officially puts Jersey into its products, like for previously mentioned GlassFish or Weblogic.

Versioning

• apache-tomcat-9.0.0.M26
• Eclipse Version: Neon.3 Release (4.6.3)
• Java 1.8.0_131
• javax.ws.rs: 2.1
• jersey: 2.26

Setting up the project

1. From the File menu → New → Dynamic Web Project
2. Project Name: RestApiExample 
3. Target runtime: Apache Tomcat v9.0 (create one if needed)
4. Next... Next...
5. Tick „Generate web.xml deployment descriptor” 
6. Finish

Converting to maven

From the Project Explorer view right click on the Project → configure → Convert to Maven Project →  Finish

Adding dependencies

  <dependency>
   <groupid>javax.ws.rs</groupid>
   <artifactid>javax.ws.rs-api</artifactid>
   <version>2.1</version>
  </dependency>
  <dependency>
   <groupid>org.glassfish.jersey.containers</groupid>
   <artifactid>jersey-container-servlet</artifactid>
   <version>2.26</version>
  </dependency>
  <dependency>
   <groupid>org.glassfish.jersey.core</groupid>
   <artifactid>jersey-server</artifactid>
   <version>2.26</version>
  </dependency>
  <dependency>
   <groupid>org.glassfish.jersey.inject</groupid>
   <artifactid>jersey-hk2</artifactid>
   <version>2.26</version>
  </dependency>

jersey-hk2 dependency might not be necesary for newer versions. At least is not needed for versions prior to 2.26, it's just look like a feature of this release.

Create RestApiServlet class

1. Create new class Name: RestApiServlet 
2. Package: com.blogspot.itsystemengineer 
3. Paste its content

package com.blogspot.itsystemengineer;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("/check/{var1}/{var2}")
public class RestApiServlet {

 @GET
 @Produces("text/plain")
 public Response printFeedback(@PathParam("var1") String var1, @PathParam("var2") String var2) {
  String result = "var1: " + var1 + " var2: " + var2;
  System.out.println(result);
  return Response.status(200).entity(result).build();
 }
}

Please refer for more here: https://docs.oracle.com/javaee/7/tutorial/jaxrs002.htm

Configure web.xml deployment descriptor

Add the following lines:

 <servlet>
  <servlet-name>javax.ws.rs.core.Application</servlet-name>
 </servlet>
 <servlet-mapping>
  <servlet-name>javax.ws.rs.core.Application</servlet-name>
  <url-pattern>/rest/*</url-pattern>
 </servlet-mapping>

This configuration automatically scans for any classes with recognize annotations (like @Path). Please refer for more here: https://jersey.github.io/documentation/latest/deployment.html#deployment.servlet.3

Run the project

Now run the project on the server and open the URL: http://localhost:8080/RestApiExample/rest/check/aaa/bbb/

Troubleshooting

As Eclipse/Tomcat/Maven sometimes don't like to cooperate, the first thing I would do is to restart Eclipse, if this doesn't help then repeat the above steps by recreating the project. Please ensure you use exact the same packages' versions as mine, otherwise things might go terribly horribly wrong. I had some problems with my packages from Maven, so I had to delete them manually and download them again. If you see errors like: java.util.zip.ZipException: invalid LOC header (bad signature) please do the same. Other problem I spotted, Eclipse didn't add Maven dependencies into the Deployment Assembly (errors about missing class which are visible in the built path).