Java SE 8: Creating a JSON REST Web Service with Grizzly and Jersey

Purpose

This tutorial explains how to develop a RESTful web service in Java with the JAX-RS reference implementation Jersey in a Grizzly container. The implemented operations are the basic REST operations: put, get, post and delete. Json and XML format are used for data interchange. No database is used to persist the data to keep the tutorial simple.

Time to Complete

Approximately 45 minutes.

Background

This section explains the basic concepts of REST, JAX-RS, JSON, Jersey and Grizzly.

RESTful services are easy to develop and deploy, lightweight, inexpensive to host and maintain, and ideal for typical online applications. They are completely stateless and particularly useful for restricted-profile devices such as mobile and PDAs because they don't have native support for SOAP services but they do for HTTP, XML and JSON.

What Do You Need?

• Java Development Kit 8 (JDK8)
• Maven 3.0+
• cURL 7.0+ cURL is installed by default on most Unix and Linux distributions. For the steps to install cURL on a Windows 64-bit machine, click here.
• A favorite text editor or IDE.

In this section, you create a Jersey Maven project from an archetype project.

1. Open a command line window (or Terminal in Linux).
2. Navigate to the directory where the new project should reside.

3. Execute the following Maven command:

   mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2 -DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false -DgroupId=com.example.rest -DartifactId=jersey-service -Dpackage=com.example.rest -DarchetypeVersion=2.17

   Note: You can change the groupId, package and/or artifactId of this command for your particular project.

   This command creates a standard Maven structure, once it is finished, you should see the new jersey-service project directory created in your current location.

   

You can open the project in Netbeans (File -> Open project) or in Eclipse (File -> Import -> Maven-> Existing Maven Project) but Maven must be configured in your IDE.

The directory created contains the following structure:

1. Project sources: Located under src/main/java. Contains 2 classes in the com.example.rest package:
• The Main class responsible for configuring and deploying the project's JAX-RS application to the Grizzly container. This class configures:
  • The URI the Grizzly HTTP Server listens on.
  • The packages the Grizzly HTTP Server scans for JAX-RS resources.
  • And starts a new instance of Grizzly HTTP server.

  
              public class Main {
                  // Base URI the Grizzly HTTP server will listen on
                  public static final String BASE_URI = "http://localhost:8080/myapp/";
              
                  /**
                   * Starts Grizzly HTTP server exposing JAX-RS resources defined in this application.
                   * @return Grizzly HTTP server.
                   */
                  public static HttpServer startServer() {
                      // create a resource config that scans for JAX-RS resources and providers
                      // in com.example.rest package
                      final ResourceConfig rc = new ResourceConfig().packages("com.example.rest");
              
                      // create and start a new instance of grizzly http server
                      // exposing the Jersey application at BASE_URI
                      return GrizzlyHttpServerFactory.createHttpServer(URI.create(BASE_URI), rc);
                  }
              
                  /**
                   * Main method.
                   * @param args
                   * @throws IOException
                   */
                  public static void main(String[] args) throws IOException {
                      final HttpServer server = startServer();
                      System.out.println(String.format("Jersey app started with WADL available at "
                              + "%sapplication.wadl\nHit enter to stop it...", BASE_URI));
                      System.in.read();
                      server.stop();
                  }
              }                                

• The MyResource class, contains an implementation of a simple JAX-RS resource with one resource method. For the purpose of this tutorial this class is not used.
2. Project test sources: Located under src/test/java. Contains a unit test class MyResourceTest in the com.example.rest package responsible for testing myresource.
3. A pom.xml located in the project root directory. Contains all dependencies needed for a Jersey project that runs on a Grizzly container. In the pom.xml also is specified the class that contains the main method, in this case is the Main class, that is called when mvn exec:java command is executed (this command is covered in Running the service section).

This section explains how to make changes to pom.xml in order to get JSON and java 1.8 support.

Jersey provides four different ways to integrate JSON support:

• Jackson
• Jettison
• Java API for JSON Processing (JSON-P)
• MOXy

MOXy is the default and preferred way of supporting JSON binding in Jersey applications, and it requires the entity setters methods. Since this tutorial uses the Builder Pattern, where setters are not allowed, Jackson is used to add support for JSON instead.

To model the Customer representation, you create a plain old java class with fields, constructors, and accessors for the fields. The Builder pattern is used in order to make the Customer class inmmutable.

1. Create a new class called Customer in the com.example.rest package.

2. Copy and paste the following code that creates a model of customer using the builder pattern.

   package com.example.rest;
   
   import java.util.concurrent.atomic.AtomicLong;
   
   public class Customer {
     private final long id;
     private final String firstName;
     private final String lastName;
     private final String email;
     private final String city;
     private final String state;
     private final String birthday;
     private static final AtomicLong counter = new AtomicLong(100);
    
     private Customer(CustomerBuilder builder){
       this.id = builder.id;
       this.firstName = builder.firstName;
       this.lastName = builder.lastName;
       this.email = builder.email;
       this.city = builder.city;
       this.state = builder.state;
       this.birthday = builder.birthday;
     }
     
     public Customer(){
       Customer cust = new Customer.CustomerBuilder().id().build();
         this.id = cust.getId();
         this.firstName = cust.getFirstName();
         this.lastName = cust.getLastName();
         this.email = cust.getEmail();
         this.city = cust.getCity();
         this.state = cust.getState();
         this.birthday = cust.getBirthday();
     }
     
     public Customer(long id, String firstName, String lastName,
         String email, String city, String state, String birthday){
         Customer cust = new Customer.CustomerBuilder().id()
              .firstName(firstName)
              .lastName(lastName)
              .email(email)
              .city(city)
              .state(state)
              .birthday(birthday)
              .build();
         this.id = cust.getId();
         this.firstName = cust.getFirstName();
         this.lastName = cust.getLastName();
         this.email = cust.getEmail();
         this.city = cust.getCity();
         this.state = cust.getState();
         this.birthday = cust.getBirthday();
     }
     
     public long getId(){
       return this.id;
     }
   
     public String getFirstName() {
       return this.firstName;
     }
   
     public String getLastName() {
       return this.lastName;
     }
     
     public String getEmail(){
       return this.email;
     }
   
     public String getCity() {
       return this.city;
     }
   
     public String getState() {
       return this.state;
     } 
     
     public String getBirthday(){
       return this.birthday;
     }
     
     @Override
     public String toString(){
       return "ID: " + id 
           + " First: " + firstName
           + " Last: " + lastName + "\n"
           + "EMail: " + email + "\n"
           + "City: " + city
           + " State: " + state
           + " Birthday " + birthday;
     }  
     
     public static class CustomerBuilder{
       private long id;
       private String firstName = "";
       private String lastName = "";
       private String email = "";
       private String city = "";
       private String state = "";
       private String birthday = "";
       
       public CustomerBuilder id(){
         this.id = Customer.counter.getAndIncrement();
         return this;
       }
       
       public CustomerBuilder firstName(String firstName){
         this.firstName = firstName;
         return this;
       }
   
       public CustomerBuilder lastName(String lastName){
         this.lastName = lastName;
         return this;
       }
       
       public CustomerBuilder email(String email){
         this.email = email;
         return this;
       }
       
       public CustomerBuilder city(String city){
         this.city = city;
         return this;
       }
       
       public CustomerBuilder state(String state){
         this.state = state;
         return this;
       }
       
       public CustomerBuilder birthday(String birthday){
         this.birthday = birthday;
         return this;
       }
       
       public Customer build(){
         return new Customer(this);
       }
       
     }    
   }
   

In this section, you learn how to create a Rest Service that implements the resource method get using the annotations introduced in Java SE 5 (@GET, @Path, @PathParam, @Produces).

1. Create a new class called CustomerService in the com.example.rest package.

2. Annotate the class with @Path ("customers").

   The @Path annotation provides a value attribute that indicates the path at which the resource is available to receive HTTP requests. The value attribute may be literal characters, variables, or variables plus a customized regular expression.It can be placed upon a class or on one or more Java methods. Java classes annotated with @Path are called JAX-RS root resources.

    @Path("/customers")
    public class CustomerService {                                  

3. Create a CopyOnWriteArrayList of Customer using MockCustomerList class. This array will used to apply the REST operations (get, put, post and delete).

    private final CopyOnWriteArrayList<Customer> cList = MockCustomerList.getInstance();                               

4. Create a GET resource method called getAllCustomers that returns an array with all the Customers in JSON format.

   The @GET annotation enables the method to process HTTP GET requests. HTTP GET methods are used to retrieve (or read) a representation of a resource, in this case the list of Customers.

   The @Produces annotation is used to specify the MIME media types a resource can produce and send back to the client. In this example, the Java method will produce representations identified by the MIME media type "JSON".

   @GET
   @Path("/all")
   @Produces(MediaType.APPLICATION_JSON)
   public Customer[] getAllCustomers() {
   return cList.toArray(new Customer[0]);
   }                                     

5. Create a GET resource method called getCustomer that receives an id and returns the Customer.

   This method gets the id from the URI and using a Lambda expression looks for the Customer that matches, if there is none an exception is thrown and a message in json format is send to the client. NotFoundException and JsonError classes are covered in the next sections.

   URI path templates are URIs with variables embedded within the URI syntax. These variables are substituted at runtime in order for a resource to respond to a request based on the substituted URI. Variables are denoted by braces ({ }).

   The @PathParam annotation is used to extract parameters from the URI. The @Path expression "{id}" must matches with the value of the @PathParam "id".

   This method returns 200 (OK) and in this case a single Customer or 404 (Not found) if the id is not found or is invalid.

     @GET
     @Path("{id}")
     @Produces(MediaType.APPLICATION_JSON)
     public Customer getCustomer(@PathParam("id") long id){
       Optional<Customer> match
           = cList.stream()
           .filter(c -> c.getId() == id)
           .findFirst();
       if (match.isPresent()) {
         return match.get();
       } else {
         throw new NotFoundException(new JsonError("Error", "Customer " + id + " not found"));
       }
     }                                  

6. Add the missing imports.

   import java.util.Optional;
   import java.util.concurrent.CopyOnWriteArrayList;
   import javax.ws.rs.Consumes;
   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.MediaType;
   import javax.ws.rs.core.Response;                                                   

Download CustomerService.java

1. Open a command line window (or Terminal in Linux).
2. Navigate to the root directory of the project (jersey-service), where the pom.xml resides.

3. Execute the following Maven command to compile the code.

   mvn clean compile

   Note: If you get a compile error, review your source code for errors, then save it and run the command again.

   c:\examples\jersey-service>mvn clean compile
   [INFO] Scanning for projects...
   [INFO]
   [INFO] ------------------------------------------------------------------------
   [INFO] Building jersey-service 1.0-SNAPSHOT
   [INFO] ------------------------------------------------------------------------
   [INFO]
   [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ jersey-service ---
   [INFO] Deleting c:\examples\jersey-service\target
   [INFO]
   [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ jersey-service ---
   [INFO] Using 'UTF-8' encoding to copy filtered resources.
   [INFO] skip non existing resourceDirectory c:\examples\jersey-service\src\main\resources
   [INFO]
   [INFO] --- maven-compiler-plugin:2.5.1:compile (default-compile) @ jersey-service ---
   [INFO] Compiling 7 source files to c:\examples\jersey-service\target\classes
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 4.284 s
   [INFO] Finished at: 2015-07-29T16:07:34-05:00
   [INFO] Final Memory: 14M/135M
   [INFO] ------------------------------------------------------------------------ 

4. Execute the following Maven command to run the main method in the Main class.

   mvn exec:java

   c:\examples\jersey-service>mvn exec:java
   [INFO] Scanning for projects...
   [INFO]
   [INFO] ------------------------------------------------------------------------
   [INFO] Building jersey-service 1.0-SNAPSHOT
   [INFO] ------------------------------------------------------------------------
   [INFO]
   [INFO] >>> exec-maven-plugin:1.2.1:java (default-cli) > validate @ jersey-service >>>
   [INFO]
   [INFO] <<< exec-maven-plugin:1.2.1:java (default-cli) < validate @ jersey-service <<<
   [INFO]
   [INFO] --- exec-maven-plugin:1.2.1:java (default-cli) @ jersey-service ---
   jul 29, 2015 4:09:45 PM org.glassfish.grizzly.http.server.NetworkListener start
   INFO: Started listener bound to [localhost:8080]
   jul 29, 2015 4:09:45 PM org.glassfish.grizzly.http.server.HttpServer start
   INFO: [HttpServer] Started.
   Jersey app started with WADL available at http://localhost:8080/myapp/application.wadl
   Hit enter to stop it... 

cURL is a command line tool and library for transferring data with URL syntax.

curl -X GET http://localhost:8080/myapp/customers/all 

C:\Program Files\curl>curl -X GET -i http://localhost:8080/myapp/customers/all
HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 29 Jul 2015 21:49:42 GMT
Content-Length: 684

[{"firstName":"George","lastName":"Washington","email":"gwash@example.com","city":"Mt Vernon","state":"VA","id":100,"
birthday":"1732-02-23"},{"firstName":"John","lastName":"Adams","email":"jadams@example.com","city":"Braintree","state
":"MA","id":101,"birthday":"1735-10-30"},{"firstName":"Thomas","lastName":"Jefferson","email":"tjeff@example.com","ci
ty":"CharlottesVille","state":"VA","id":102,"birthday":"1743-04-13"},{"firstName":"James","lastName":"Madison","email
":"jmad@example.com","city":"Orange","state":"VA","id":103,"birthday":"1751-03-16"},{"firstName":"James","lastName":"
Monroe","email":"jmo@example.com","city":"New York","state":"NY","id":104,"birthday":"1758-04-28"}]

curl -X GET -i http://localhost:8080/myapp/customers/101

C:\Program Files\curl>curl -X GET -i http://localhost:8080/myapp/customers/101
HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 29 Jul 2015 21:25:49 GMT
Content-Length: 133

{"firstName":"John","lastName":"Adams","email":"jadams@example.com","city":"Braintree","state":"MA","id":101,"birthday":
"1735-10-30"}

curl -X GET -i http://localhost:8080/myapp/customers/110 

C:\Program Files\curl>curl -X GET -i http://localhost:8080/myapp/customers/110
HTTP/1.1 404 Not Found
Content-Type: application/json
Date: Wed, 29 Jul 2015 21:27:36 GMT
Content-Length: 51

{"type":"Error","message":"Customer 110 not found"}

• To learn more about Java and related topics check out the Oracle Learning Library

• Curriculum Developer: Luz Elena Peralta Ayala
• QA: Veerabhadra Rao Putrevu