Create a Jersey web project using Maven, Tomcat, and Eclipse


Jersey is an open source, RESTful web service framework built in Java. For information on REST APIs, see REpresentational State Transfer.

Install the prerequisites

  1. Install and configure Eclipse for Java EE development
  2. Install and Configure Tomcat
  3. Install and Configure Maven for Eclipse
  4. Don’t install Jersey.  Maven will do that for you eventually.

Create your Maven Eclipse Web Project

Each time you create a new workspace, you’ll need to redo parts of the Maven setup.  See the notes in the Maven install instructions above.

  1. In Eclipse,
  2. If you like, create or switch to a new, empty workspace (which is just an empty folder): Choose File / Switch Workspace / Other…
  3. If Eclipse shows you Icons for Overview, Samples, etc., click the Workbench arrow icon in the upper-right of the screen.
  4. Select File / New / Maven Project
  5. Click Next
  6. In the Filter field, type maven-archetype-webapp
  7. Wait for results to appear
  8. In Results, click on maven-archetype-webapp. There should be only one.
  9. Click Next
  10. Choose a Group Id, Artifact Id, and Package name for your project.
    1. Group Id is a URI style domain of your organization. For example, com.mycompany
    2. Artifact Id is a unique name for this project. For example, my-first-jersey-service
    3. Package Id is the name of the main Java package for this project. For example, com.mycompany.myjerseyservice
  11. Fill in the Group Id, Artifact Id, and Package Id that you’ve chosen.
  12. Click Finish
  13. As Eclipse compiles the result, some errors will appear.  Don’t worry about that right now.
  14. in  Eclipse’s Project Explorer pane (on the left), right-click on your project’s name and select Maven / Update Project…
  15. Click OK
  16. Wait for the update to complete
  17. In the Project Explorer, expand your project so that the src/main folder is visible and expanded.
  18. Create the src/main/java folder:
    1. Right-click on src/main and select New / Folder
    2. For Folder Name, type java
    3. Click Finish
  19. Create src/test and src/test/java in the same way

Add Jersey Dependencies

  1. In Eclipse,
  2. In the Project Explorer pane, expand your project tree
  3. Double-click on pom.xml
  4. In the pom.xml window, note the tabs at the bottom of that window.
  5. Click the pom.xml tab. That will show the raw XML text of the file.
  6. Add the following to the dependencies section of pom.xml:
  7. Save the pom.xml
  8. Maven will download Jersey automatically.  This is what Maven is good at.  When the project has compiled, the one error you saw earlier should disappear.  A warning about the JRE version will likely still remain. You can ignore that warning.

Create your first Jersey Java Class

Each Jersey Class is a POJO (Plain Old Java Object) containing Jersey annotations that enable it to respond to a particular set of URLs.

  1. In Eclipse,
  2. In the Project Explorer, expand your project so that the src/main/java folder is visible
  3. Right-click on src/main/java and select New / Other… / Class
  4. Click Next
  5. For the package name, type the Package Id you chose earlier
  6. For the Class Name, type MyJerseyPage (or whatever classname you like)
  7. Click Finish
  8. In the resultant file, add these imports:

  9. Edit your MyJerseyPage class definition to look like this: TODO learn how to indent code in WordPress.
    public class MyJerseyPage {
    public String sayHtmlHello() {
    return "Hello from Jersey";
  10. Save that file
  11. Notice that this class uses Jersey annotations, prefixed by the at-sign: Path, GET, and Produces
    1. Path tells Jersey what URL subtree this class responds to
    2. GET tells Jersey to call this method to service a GET HTTP request on the class’s URL
    3. Produces says what HTTP media type this method returns.  Combined with GET, you can write multiple methods that service the same GET request, depending on what media type the web client requests.

Create a Tomcat test server for your project

When Eclipse runs a project, it starts a new instance of Tomcat configured for just your project.  The Runtime path to your installed Tomcat is used by Eclipse to create that Tomcat test server.

  1. In Eclipse,
  2. In the Project Explorer, right-click on your project name and select Properties
  3. In the resultant window, select Targeted Runtimes
  4. Click New
  5. Select Apache Tomcat v8.0
  6. Check the box labeled Create a new local server
  7. Click Next
  8. In the Tomcat Installation directory field, type the value of your CATALINA_HOME environment variable. For example, mine is C:\Program Files\Apache Software Foundation\Tomcat 8.0
  9. Click Finish
  10. In the Targeted Runtimes dialog, click (mark the checkbox) the newly-created Apache Tomcat v8.0 entry.
  11. Click OK
  12. Now the Project Explorer pane should show two entries: one is your project; the other is the test server for your project.
  13. Select Window / Show View / Servers. That should show your Tomcat test server, whether it needs to be updated (“republish”) and whether it’s running or stopped.

Configure your project for Tomcat and Jersey

  1. In Eclipse, in the Project Explorer, expand your project tree so that src/main/webapp/WEB-INF/web.xml is visible
  2. Double-click on web.xml
  3. Notice the tabs at the bottom of the new view.
  4. Click on the Source tab
  5. Add the following to web.xml: TODO fix the formatting

    <servlet >
    <servlet-name >HelloWorld Jersey Service </servlet-name >
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer </servlet-class >
    <init-param >
    <param-name ></param-name >
    <param-value >com.mycorp.myjerseyserver</param-value >
    </init-param >
    <load-on-startup >1 </load-on-startup >
    </servlet >
    <servlet-mapping >
    <servlet-name >HelloWorld Jersey Service </servlet-name >
    <url-pattern >/thisthat/* </url-pattern >
    </servlet-mapping >
  6. Save that file
  7.  Notice:
    1. The servlet-class node tells Tomcat that Jersey is the main servlet.
    2. The url-pattern node tells Tomcat what URLs Jersey will handle.
    3. The value tells Jersey which Java package contains your Jersey-annotated code.

Set up Eclipse’s Tomcat to deploy your project

  1. Right-click on your project and select Properties
  2. Click on Web Project Settings
  3. For Context root, type the root URL you’ve chosen for your project.  For example, if you set Context Root to /rest all of the Jersey URLs will start with http://localhost:8080/rest
  4. Click OK
  5. In the confirmation dialog, click OK
  6. In the Servers view, double-click on your tomcat server (Tomcat v8.0 Server at localhost)
  7. In the resultant window, notice the tabs at the bottom of the window
  8. Click the Modules tab
  9. Click Add Web module…
  10. In the resultant list, click on the name of your project
  11. Notice that the path field matches the Context Root you just set. If you need to change your Context Root, don’t do it here.  This is just a copy of the value in your project Context Root setting.
  12. Save that Modules file
  13. In the Servers pane, right-click on your tomcat server and select Clean. I think you need to do this because you changed the module list.

at long last…

Test your web page

  1. Start the server in Debug mode: in the Servers view, right-click on the tomcat server and select Debug
  2. Wait a few seconds for the server instance to start.  You can see progress/errors in the Console view
  3. Your Jersey page url is composed of:
    1. http://localhost:8080 = your PC and the port that Tomcat is listening on.  That port is set in the Tomcat configuration file.
    2. /rest = the Context Root of your project
    3. /thisthat = your web.xml url-pattern node
    4. hello = the Path annotation in
  4. Browse to the url of your hello page, for example: http://localhost:8080/rest/thisthat/hello
  5. The browser should show the response from your class: “Hello from Jersey”

Add an HTML page at the root of your project

Suppose you want to add a regular HTML page, titled login.html, to your Jersey project.

  1. In Eclipse, in the Project Explorer, expand your project tree until src/main/webapp is visible
  2. Right-click on src/main/webapp and select New / HTML file
  3. For File name, type login.html, or whatever you wish this page ot be called (ending in .html)
  4. Click Next
  5. Click Finish
  6. Edit the resulting file in any way you like. In particular, add an HTML body
  7. Save the file.  You might notice that you can do this while the test server is running; the server automatically updates
  8. The new file’s URL is composed of:
    1. http://localhost:8080 and /rest as above
    2. login.html = the filename in the tree rooted in your webapp folder
  9. Browse to the Url of your new page. For example http://localhost:8080/rest/login.html
  10. The browser should present your new HTML page’s content.

Add more Java classes that respond to more urls, and add more HTML pages

Each new class you create will respond to an URL (or set of URLs) under http://localhost:8080/rest/thisthat/

Each HTML page you add in the tree under webapp will appear at the corresponding URL. For example, webapp/statistics/counts.html would appear as http://localhost:L8080/rest/statistics/counts.html

Jersey supports a wide variety of URLs, HTTP session variables, and HTTP query parameters. See the Jersey documentation for what you can do in a Jersey class.

Deploy to a production Tomcat server

Tomcat projects are deployed in a Web ARchive, aka a .war file.

To create a .war file from your project:

  1. In Eclipse, in the Project Explorer, right-click on your project name and select Export / WAR file
  2. For Destination, click the Browse button
  3. Navigate to the folder you wish to save the .war file to, choose what to name it, and click Save
  4. Click (check) Export Source Files. Without this option, your html files would not be included in the .war file.
  5. TODO see what we need to do to fix the problem we see when the .war file is deployed.
  6. Click Finish
  7. Follow the section labeled To Add a Project .war file to your server near the bottom of Install and Configure Tomcat


Many Thanks to: