RESTful Java Web Services with NetBeans 8 , Jersey 2.5 and Tomcat 8

java-jersey-2-x-225x225Recently one of my readers commented on my RESTful Web Services with NetBeans, Jersey, and Tomcat blog that the Github project I set up does not work out of the box for NetBeans 8.x. That is indeed the case so I decided to update the article and project to handle a new Jersey environment.

For a general introduction to RESTful web services, you can consult my previous blog. In this one I’ll focus on using Netbeans 8, Jersey 2.5 and Tomcat 8 to build a basic RESTful web service framework.



If you don’t already have Tomcat and NetBeans configured to work together, read these sections to learn how to test your web services with a Tomcat server.


  1. Download and install Apache Tomcat version 8.x.  Note the version used for this article is 8.0.26.
  2. Now you need to set up a Tomcat admin user that will have all the privileges to run the Tomcat management system. You will add a user named tomcat with password tomcat to do this. Open the apache-tomcat-8.0.26/conf/tomcat-users.xml file.
  3. Comment out all the lines in the file and replace them the following lines:
<xml version="1.0" encoding="UTF-8">
  <role rolename="tomcat"/>
  <user username="tomcat" password="tomcat" roles="manager-script,manager-gui"/>
  1. You can start and stop your Tomcat server with these commands
  1. Test your Tomcat server by opening http://localhost:8080 in your browser. You should get a screen that looks like this:



  1. Download and install the Java EE version of NetBeans. The version used for this blog was 8.0.2 Note that for the Mac you’ll get a DMG package and for Linux you’ll get an installation script.
  2. For web application testing, NetBeans uses the Glassfish web server by default. To use Tomcat instead, click on the Services tab.  If you don’t see this tab, select Window > Services to get the tab to appear.
  3. Right click on the Servers item and select Add Server.

Add Server

  1. Select Apache Tomcat in the list of servers.
  2. Set the name of the server to Apache Tomcat then click Next.

Add Server Instance

  1. Click on Browse in the Add Server Instance screen to set the server location.

Installation and Login Details blank

  1. Select the folder where you installed Apache Tomcat then click Open. In my case I installed Tomcat in the /Applications/NetBeans directory on my Mac. You may wish to install your Tomcat environment somewhere else.

Server Open

  1. Set the Tomcat user name to tomcat and the password to tomcat then click on FinishApache Tomcat will now be one of the servers you can select when you test your web service later.  Your Apache Tomcat server settings should looks like this:

Add Server Credentials

Create a NetBeans Web Application Project

After configuring the development environment, you first need to build a base web application to which you will add a RESTful services class and methods later.

  1. Select File > Open > New Project…
  2. Select the Java Web category and Web Application project, then click Next.

New Project

  1. Enter the project name as getsomerest and set the directory location of the project, then click Next. This action sets the top level REST path variable in the context.xml file.

New Web Application

  1. In the Server and Settings screen, select  Apache Tomcat in the Server field, then click Next.

New Web Application

  1. We will not add any additional application frameworks, so click Finish in the Frameworks screen (not shown).
  2. You now have a simple web application that will load the index.html page. To run the application, click on the green triangle under the NetBeans menu bar, select Run > Project from the menu bar or press F6.

Create RESTful Web Services

GET Service Handler

Now that we have a basic web application, we will add a RESTful service that responds to an HTTP GET request.

  1. Right click on getsomerest in the Projects.
  2. Select New… then select RESTful Web Services from Patterns…
  3. Select the Simple Root Resource in the Select Pattern screen, then click Next.

New RESTful Web Service

  1. Next you will specify the service method and service resource class. In the Specify Resource screen set the name of the Java package that will contain your service class. The name can be anything, but it is usually a domain name in reverse order. In this example we’ll use com.vichargrave.
  2. Set the service Path to service and the service Class name to ServiceResource.
  3. The MIME type refers to the format of the messages that will be sent to and returned by our web service.  Set this to text/html for the simple GET service. In the next section I’ll explain how to set other MIME types with Jersey annotations.
  4. Click on Finish.

Specify Resource Classes

  1. You will now see a section in your project called RESTful Web Services. If you open this section you can see the service class with GET and PUT handler methods that have been created.  Replace the contents of the getHtml() with the return statement as shown below.  Note that the content type of the return string is specified by the @Produces(“text/html”) Jersey annotation.
package com.vichargrave;
public class ServiceResource {
    private UriInfo context;
    public ServiceResource() {
    public String getHtml() {
        return "<h1>Get some REST!</h1>";
    public void putHtml(String content) {
  1. Now we need to set the path to the web service so it will be automatically invoked when we test it with the default browser. Right click on the getsomerest project then select Properties.
  2. Select Run.
  3. When we test the web service the URL to the GET service will be http://localhost:8080/getsomerest/webresources/service. Recall that the getsomerest part of the URL is defined in the path attribute in the context.xml file which you can find in the configuration files of the project. The webresources part of the path is set in the"webresources") annotation in the file that NetBeans created. The service part is defined by the @Path annotation in the file. Enter /webresources/service in the Relative URL field then click OK. Project Properties
  4. The webresources part of the path is defined in the file. You can set it to “/” if you want to simply the URL path to your web service methods. If you do that then replace /webresources in the Relative URL with /service.

POST Service Handler

Most web services have a POST handler so let’s add one now.  The handler will accept urlencoded text from a REST client which is specified with the @Consumes(“application/x-www-form-urlencoded”) Jersey annotation.  In this case the POST handler will simply return the decoded plain text to the client which is specified with the @Produces(“text/plain”) Jersey annotation.

  1. Add the following import statement to the list of imports.
  1. Add the following code to the ServiceResource class. The @Consumes annotation specifies that the POST handler accepts requests containing URL encoded data. The Content-Type of the POST request much match the @Consumes type or else the POST handler will not get called. The @Produces annotation specifies that the POST handler will return ordinary text.
public String postHandler(String content) {
    return content;
  1. If your server is still running from previous testing, NetBeans will automatically deploy the service in your test environment and restart Tomcat.  Otherwise run the project again.
  2. You can test the web service by sending it a file from your system with the curl command as follows.
curl http://localhost:8080/getsomerest/webresources/service --data "Hello World!"
  1. The POST handler should return Hello World! to curl.

Web Service Deployment

Now that you have a working RESTful web service with GET and POST handlers, you’ll want to deploy the service to your target Tomcat server. NetBeans packages all the web service code into a WAR package.  In the case of this project the package will be called GetSomeRest.war. You can deploy this package to the target Tomcat server as follows:

  1. Open the Tomcat main page in your browser,
  2. Click on the Manager button.  You will most likely have to login with the administrator credentials.
  3. Scroll down to the WAR file to deploy.
  4. Click on the Choose file button.
  5. Navigate to your NetBeansProjects/GetSomeRest/dist directory and select GetSomeRest.war.
  6. Click on Deploy. In the Path column under Applications you should see /GetSomeRest.
  7. Run the curl command from the previous section with the host/IP and port for your target Tomcat to make sure the service is working.

Jersey Web Service Annotations

Jersey provides a set of Java annotations that can be used to define the web service structure. So far we have already used these annotations in the example GET service:

  • @Path – Defines the URL relative path to the given resource. We saw in the previous section that the complete URL to our service was defined by fields in the context.xml and web.xml files plus the @Path field. You can change the relative path of any service by modifying these three fields. For example if you wanted to simplify the GET service URL to be http://localhost:8080/GetSomeRest/service you would set the <url-pattern> field in web.xml to “/*”.
  • @Context – Defines parameters that can be extracted from the request.
  • @GET – Identifes the method in the service class that will handle GET requests.
  • @Produces – Specifies the MIME type of the response that is returned to the client.
  • @Consumes – Specifies the content type that the service will accept as input.

Some other important annotations that you’ll want to know about include:

  • @PUT – Identifies the method that will handle PUT requests.
  • @DELETE – Identifies the method that will handle DELETE requests.
  • @Consumes – Specifies the MIME type that the method immediately following the annotation will accept from the client. It is possible to define multiple MIME types that will each be handled by a separate method. The GET service example does not have any arguments so the @Consumes annotation was not needed. If we wanted to add a string parameter to the GET service the code for the getHTML() method would look something like this:
public String getHtml(String message) {
    return "<h1>The browser sent this message "+message+"</h1>";
  • @QueryParam – Denotes a field that will be extracted from the URL in a GET request after the ? character. Here is an example taken from the Jersey documentation website. For a URL request of this form:

          The handler method would look like this:

public Response smooth(
@DefaultValue("2") @QueryParam("step") int step,
@DefaultValue("true") @QueryParam("min-m") boolean hasMin,
@DefaultValue("true") @QueryParam("max-m") boolean hasMax,
@DefaultValue("true") @QueryParam("last-m") boolean hasLast,           
@DefaultValue("blue") @QueryParam("min-color") ColorParam minColor,
@DefaultValue("green") @QueryParam("max-color") ColorParam maxColor,
@DefaultValue("red") @QueryParam("last-color") ColorParam lastColor
) { ... }
  • @DefaultValue – Denotes the value that will be used to fill a variable in a @QueryParam list that is missing.
  • @PathParam – Denotes a field that will be extracted from a field in the URL path. Here is an example taken from the Jersey documentation website:
public Response getImage(@PathParam("image") String image) {
  if (!isSafeToOpenFile(image)) {
    throw new IllegalArgumentException("Cannot open the image file.");
  File f = new File(image);
  if (!f.exists()) {
    throw new WebApplicationException(404);
  String mt = new MimetypesFileTypeMap().getContentType(f);
  return Response.ok(f, mt).build();

Test the Web Service

You can get the source code for the GetSomeRest project from GitHub – The master branch contains the project described in this blog. Open the project in Netbeans and run it with Tomcat according to the directions in this blog.

Additional Information

The intent of this blog is to get you started with RESTful web services in NetBeans. To keep things simple I’ve left out some important aspects of web service development not the least of which includes processing POST and PUT request bodies. For more information on writing more complex RESTful web services you can check out these resources:


Article by Vic Hargrave

Software developer, blogger and family man enjoying life one cup of coffee at a time. I like programming and writing articles on tech topics. And yeah, I like coffee.


  1. Hi, Just a question : I don’t see any web.xml file when i follow your tutorial but everything works fine. So here I am : is the web.xml file is usefull ? Why is it not here ? Is it because of netbean ?

    Thanks in advance.
    and very good tutorial ! Thanks a lot.

    1. With NetBeans 8 the web.xml file is not used for building RESTful services. The file can be used, but the ApplicationConfig class handles sets the attributes that were formally set in the web.xml. However, I have downloaded other RESTful projects that use web.xml instead of the ApplicationConfig class, all of which seem to work.

Leave a Reply

Your email address will not be published. Required fields are marked *