If you’re reading this article, it is likely that you’re having a bit of trouble using Jersey to create a RESTful API and running it on Apache Tomcat.
You might be thinking that I am a broken record: there must be millions of articles on this very same topic. However, in my own quest to get started using Jersey to create a REST API in Java, I was bombarded with article upon article that assumed too much knowledge on my behalf. Any programmer who’s getting started with a new technology doesn't want to read the textbook, they want to jump in and build something.
The motivation for creating this tutorial is for those who want to kick-start their REST API development using Jersey.
0. Preamble
Before we begin, I’d like to introduce a few technologies that we’ll be dealing with during this tutorial. If you’re familiar with these, feel free to skip this section.
For this tutorial I will be using IntelliJ IDEA 14 Ultimate edition, but the community edition should work just as well. This is my IDE of choice; I’m not a fan of Eclipse. No, I’m not going to explain what REST stands for or explain what a Unique Resource Identifier is.
JAX-RS
JAX-RS is a Java API developed by Oracle. There are multiple reference implementations of this API including Jersey, Apache CXF, RESTeasy, etc…
Jersey
Jersey, as previously stated, is a reference implementation of the JAX-RS 2.0 API. Jersey is extensible and provides additional functionality to the API.
Maven & The Central Repository
Maven is a tool used to model projects/modules: it keeps tracks of different aspects such as building or managing a Java based project. For this tutorial, it will be used mainly to manage our project dependencies.
The Central Repository is a glorious place where artifacts can be found for use in your project. An artifact is a file (usually a JAR) that is created by a Maven build.
Apache Tomcat
Apache Tomcat is a popular, open source implementation of the Java Servlet API. A servlet is “a Java class used to extend the capabilities of servers.”
1. Installing Apache Tomcat & Maven
Depending on your operating system, this step will vary. The goal is to install Apache Tomcat and Maven on your system.
I am using Fedora 21, so this was as painless as sudo yum install tomcat maven
2. Creating a New Project
Though it sounds trivial, I was actually having quite a difficult time starting a new project. As a first time Maven/Jersey user, I was not in a great position to figure out why I was encountering these issues.
To create a new project, open up the New Project dialog in IntelliJ. In the left menu, select Java Enterprise. To the right, select RESTful Web Service. Below, change the radio selection from Download to Set up library later. We will be using Maven to download and manage our libraries.
You can continue through the rest of the steps as per normal.
3. Adding Maven Support
In order to add Maven to your project, you can avoid the command line completely by right-clicking on your project’s name in the Project sidebar and selecting Add Framework Support.
In the Add Frameworks Support dialog, select Maven.
Once this is done, the pom.xml file will open in the editor. You will need to enter at least a groupId, usually your package name. For this tutorial, I will be using com.example.jersey. At this point, it is helpful to enable auto-importing for library dependencies.
4. Adding Web Support
Similarly to Maven, you’ll want to open the Add Frameworks Support dialog again. This time, select Web Application and ensure that Create web.xml is checked.
Once complete, your project structure should look similar to this.
5. Adding Jersey with Maven
Before we can use Jersey, we need to add the library to our project. We will do this with Maven by adding the following to our pom.xml file:
The jersey-bundle artifact can be found at http://search.maven.org/#artifactdetails%7Ccom.sun.jersey%7Cjersey-bundle%7C1.18.3%7Cjar
6. Creating a Resource
Inside of the src/main/java directory, create a new package matching your groupId.
Inside of this package, create a resource such as HelloWorld.java:
7. Setting up Tomcat
The next step is making IntelliJ aware of Tomcat so that it can deploy your applications seamlessly. This is accomplished by navigating through File > Build, Execution, Deployment > Application Servers > “+” > Tomcat Server.
In the Tomcat Server dialog, navigate to the installation directory of Tomcat.
After this is done, the correct version should be reported by the dialog. Exit both dialogs by selecting OK.
8. Creating a Run & Debug Configuration
Before Tomcat can serve your application, you’ll need to set it up. Do this by creating a new run configuration. This is done by navigating through Run > Edit Configurations… > “+” > Tomcat Server > Local. Name this whatever you like.
During this step, we need to select the artifact for Tomcat to deploy. Choose the Deployment tab, clicking “+”, and choosing Artifact…
Select the only artifact listed then choose Apply and finally OK.
9. Configuring your Servlet
Inside of your web/WEB-INF/web.xml file, you’ll need to add the following contents:
I will refrain from going into much detail about this configuration file, but it is wise to investigate additional configuration options for your REST service.
The last step is to let your application server (Tomcat) know about your configuration file. Navigate through File > Project Structure > Artifacts. After choosing all of the Available Elements listed, right-click and choose Put in Default Location.
10. Run your Application
That’s everything! From here, you can run your application through IntelliJ. If you get a permissions error when running, be sure that Tomcat’s conf directory is accessible from the system user that is running IntelliJ.
