Developing RESTful Services with JAX-RS 2.0, WebSockets, and JSON

JAX-RS provides very rich client and server APIs that work on any Java EE application server. Using JAX-RS API, any POJO can be annotated to build the RESTful resources. Begin with a simple POJO BookResource and annotate it with the JAX-RS APIs.

@Path("books")
public class BooksResource {
}

This is a root resource class, which is annotated with @Path annotation. The value "books" will indicate that the resource will be available at a location similar to the following URI http://host:port/appname/books.

Later on we add the methods to this resource so that, when a request with GET, PUT, and so on hits this resource, a particular method in the class is invoked to produce the response.

To add a method to this resource, we annotate the method with @GET, @PUT, @DELETE, or @HEAD. In the following example, we chose to annotate using a @GET annotation:

@GET
public String getGreeting() {
  return "Hello from Book resource"
}

The @GET annotation specifies that the getGreeting() method handles the HTTP GET requests.

To specify the MIME type that can be handled by the resource, we should annotate the resource method with @Produces and @Consumes:

@Produces("text/plain")
@GET
public String getGreeting() {
  return "Hello from Book resource"
}

The @Produces specifies that the media type this method will produce is "text/plain". Support for other media types, and how to map from Java to a specific format and vice versa, is covered in detail in the entity provider's section. Thus, this is the initial introduction to having a first JAX-RS resource ready. The next section covers the details of the Application subclass.

The Application class is a portable way to configure application-level details such as specifying the name, and registering various components of a JAX-RS application. This includes the different JAX-RS resources and the JAX-RS providers in the application.

Similarly, application-wide properties can be set using a subclass of Application. The Application subclass should to be placed in either in WEB-INF/classes or WEB-INF/lib in a WAR file. Application class has the following methods that can be overridden:

public Set<Class<?>> getClasses() ;
public Map<String, Object> getProperties();
public Set<Object> getSingletons();

Here is an example of a subclass of Application for our case:

@ApplicationPath("/library/")
public class HelloWorldApplication extends Application {
@Override
  public Set<Class<?>> getClasses() {
    Set<Class<?>> classes = new HashSet<Class<?>>();
    classes.add(BooksResource.class);
    return classes;
  }
}

In this code we create a HelloWorldApplication, which is a subclass of javax.ws.rs.core.Application. With Servlet 3.0 there is no need of a web.xml file and the servlet container uses the value specified in the @ApplicationPath as the servlet mapping. The getClasses() method of the Application class is overridden to add BooksResource.class.

A basic JAX-RS resource is now ready to use. When the sample is deployed to an application server such as GlassFish, you can use curl to send a request.

Here is an example on how to send a curl -X GET request:

curl -X GET http://localhost:8080/helloworld/books

The output in the terminal window should be:

Hello from book resource

Chapter 5, RESTful Web Services by Example, will show how to use the Application class in a web.xml file.

Resource classes can partially process some part of the request and provide another subresource to process the remaining part of the request.

For example, here is a snippet of a root resource Library and another resource Book.

@Path("/")
public class Library {

  @Path("/books/{isbn}")
  public Book getBook(@PathParam("isbn") String isbn){
    //return book
  }
}

public class Book {
  @Path("/author")
  public String getAuthor(){
  }
}

Subresource locators are resource methods that have @Path annotation but no HTTP methods.

In the preceding example, Library is a root resource as it is annotated with @Path. The method getBook() is a subresource locator whose job is to provide an object that can process the request.

The @PathParam is an annotation that allows you to map URI path fragments in the method call. In this example, the isbn URI parameter is passed to provide information about the book.

If a client sends a request using the URI:

GET /books/123456789

The Library.getBook() method will be invoked.

If a client sends a request using the URI:

GET /books/123456789/author

The Library.getBook() method will be invoked first. A Book object is returned and then the getAuthor() method is invoked.

An application can provide an implementation of the MessageBodyReader interface by implementing the isReadable() method and the readFrom() method to map the entity to the desired Java type.

The following figure shows how the MessageBodyReader reads an InputStream object and converts it to a user-defined Java object.

The following code shows how to provide an implementation of MessageBodyReader and uses Java Architecture for XML Binding (JAXB) with JAX-RS. JAXB provides a fast and convenient way to bind XML schemas and Java representations, making it easy for Java developers to incorporate the XML data and processing functions in Java applications. As a part of this process, JAXB provides methods for unmarshalling (reading) XML instance documents into Java content trees, and then marshalling (writing) Java content trees back into XML instance documents.

Here is a JAXB root element called Book. Book has properties such as name and ISBN.

@XmlRootElement
public class Book {
  public String name;
  public String isbn;
  public String getName() {
    return name;
  }
  public String getIsbn() {
    return isbn;
  }
  public Book(String name, String isbn) {
    this.name=name;
    this.isbn=isbn;
  }
  //JAXB requires this
  public Book() {
    
  }
}

The MessageBodyReader implementation class can provide support to read from an inputStream object and convert to the Book object. The following table shows the methods that need to be implemented:

Here is the code for SampleMessageBodyReader class that is the implementation of the MessageBodyReader interface:

@Provider
public class SampleMessageBodyReader implements 
MessageBodyReader<Book> {
}

The @Provider annotation indicates that this is a provider and the implementing class can also use @Produces and @Consumes annotations to restrict the media types they support.

Here is the implementation of isReadable() method:

public boolean isReadable(Class<?> aClass, Type type, Annotation[] annotations, MediaType mediaType) {
  return true;
}

The isReadable() method returns true to indicate that this SampleMessageBodyReader class can process the mediaType parameter.

This is an implementation of the readFrom() method of the SampleMessageBodyReader class. The mediaType parameter can be checked here and different actions can be taken based on the media type.

public Book readFrom(Class<Book> bookClass, Type type, Annotation[] annotations,
MediaType mediaType,
MultivaluedMap<String, String> stringStringMultivaluedMap,
InputStream inputStream) throws IOException, WebApplicationException {
  try {
    
    Book book = (Book)unmarshaller.unmarshal(inputStream) ;
    return book;
  } catch (JAXBException e) {
    e.printStackTrace();
  }
  return null;
  }
}

The book object, which is the method's return value, is then unmarshalled using JAXB Unmarshaller using the provided inputStream object as the parameter.

The MessageBodyWriter interface represents a contract for a provider that supports the conversion from a Java type to a stream.

The following figure shows how MessageBodyWriter can take a user-defined class, Book, and marshal it to an outputStream object.

The following table shows the methods of MessageBodyWriter that must be implemented along with a short description of each of its method.

Here are the methods of the MessageBodyWriter interface that need to be implemented:

public boolean isWriteable(Class<?> aClass, Type type, Annotation[] annotations, MediaType mediaType) {
    return true;
}

The isWritable()method of the MessageBodyWriter interface can be customized to check if this implementation of MessageBodyWriter supports the type or not.

    public long getSize(Book book, Class<?> aClass, Type type, Annotation[] annotations, MediaType mediaType) {
        return -1;
    }

The getSize() method is called before the writeTo() method to ascertain the length of bytes in the response.

public void writeTo(Book book, 
Class<?> aClass, 
Type type, Annotation[] annotations, 
MediaType mediaType,
MultivaluedMap<String, Object> map,
OutputStream outputStream) throws 
IOException, WebApplicationException {
  try {
    
    Marshaller marshaller = jaxbContext.createMarshaller();
    marshaller.marshal(book, outputStream);
  } catch (Exception e) {
    e.printStackTrace();
  }
}

The writeTo() method marshals the Book to the Outputstream.

This is how the client looks:

Client client = ClientBuilder.newClient();
client.register(MessageBodyReaderWriter.class).register(BooksResource.class);
Response response = target
.request()
.post(Entity.entity(new Book("Getting Started with RESTful Web Services","13332233"), MediaType.APPLICATION_XML_TYPE));

Book  = response.readEntity(Book.class);

The client.register() method is used to register the MessageBodyReaderWriter.class and BooksResource.class.

The application class, Book is extracted from the response using response.readEntity(Book.class).

Getting validation errors from the response is not enabled by default. The sample included in the book will demonstrate how to get the validation errors from the response. The user needs to set BV_SEND_ERROR_IN_RESPONSE property to Boolean value true using Application class by overriding the getProperties() method.

Here is the getProperties() method of the Application subclass.

@override
public Map<String,Object> getProperties() {
  Map<String,Object> properties = new HashMap<String,Object>() ;
  properties.put(ServerProperties.BV_SEND_ERROR_IN_RESPONSE, true);
  return properties;
}

The getProperties() method returns the Map<String,Object> object with the String property ServerProperties.BV_SEND_ERROR_IN_RESPONSE set to the Boolean value true.

After the application class is configured to set the String property ServerProperties.BV_SEND_ERROR_IN_RESPONSE to the Boolean value true, the following code in the servlet class will read the validation errors from the response.

This is how the code looks on the client side:

List<ValidationError> errors = response.readEntity(new GenericType<List<ValidationError>>() {});

The response.readEntity() method takes a list of GenericType<ValidationError> parameters. From the List<ValidationError> errors, returned by the response.readEntity() method, we can extract the validation error and get the validation message. On running the sample, the following message will be shown:

"There was 1 error when validating the request

Book does not exist for the ISBN requested"