A Web-Browsing Experience

Because REST is derived from the Web, to better understand it, I’ll start with a real-life web-browsing experience. How would you proceed to reach the list of Java technology books at Apress? You point your browser to the Apress web site: http://www.apress.com. Although it is likely that this page will not contain the exact information you’re seeking, you’re expecting it to give you access in one way or another to the Java book list. The home page offers a search engine on all Apress books, but there is also a book directory sorted by technologies. Click the Java node, and the hypermedia magic happens: here is the full list of Apress Java books at http://www.apress.com/java. You get a page showing you 20 books out of 191. If you want to have all of the books displayed on the page in a list format, click on http://www.apress.com/java?limit=all&mode=list.

Say you save the link in your favorite bookmark manager and, as you go through the book list, The Definitive Guide to Grails 2 by Graeme Rocher and Jeff Brown captures your attention. The hyperlink on the book title takes you to the book page (http://www.apress.com/9781430243779) where you can read the abstract, author biography, and so on, and you notice one of the books listed in the Related Titles section might be as valuable for your current project. You would like to compare Graeme Rocher’s book with Practical JRuby on Rails Web 2.0 Projects: Bringing Ruby on Rails to Java by Ola Bini (http://www.apress.com/9781590598818). Apress book pages give you access to a more concrete representation of its books in the form of online previews: open a preview, go through the table of contents, and make your choice.

Here is what we do on a day-to-day basis with our browsers. REST applies the same principles to your services where books, search results, table of contents, or book’s covers can be defined as resources.

Resources and URIs

Resources are given a central role in RESTful architectures. In the Web-Browsing Experience above you’ve noticed that a resource is anything the client might want to reference or interact with, any piece of information that might be worthwhile referencing in a hyperlink (a book, a search result, a table of contents . . .). A resource can be stored in a database, a file . . . anywhere it can be addressed. Avoid as much as possible exposing abstract concepts as resources; instead opt for simple objects. Some resources used in the CD-BookStore application could be:

• A list of Java books
• The book The Definitive Guide to Grails 2
• Ola Bini’s résumé

Resources on the Web are identified by a URI (Uniform Resource Identifier). A URI is a unique identifier for a resource, made of a name and a structured address indicating where to find this resource. Various types of URIs exist: WWW addresses, Universal Document Identifiers, Universal Resource Identifiers, and finally the combination of Uniform Resource Locators (URLs) and Uniform Resource Names (URNs). Examples of resources and URIs are listed in Table 15-1.

URIs should be as descriptive as possible and should target a unique resource. Note that different URIs identifying different resources may lead to the same data. Actually, at some point in time, the list of the interesting photos uploaded to Flickr on 01/01/2013 was the same as the list of the uploaded photos in the last 24 hours, but the information conveyed by the two corresponding URIs is not the same. The standard format of a URI is as follow:

http://host:port/path?queryString#fragment

HTTP is the protocol, host is a DNS name or IP address and the port is optional. The path is a set of text segment delimited by the “/” character. Following this there is an optional query string (list of parameters represented as a name/value pair, each pair delimited with the “&” character. The last part delimited by “#” is the fragment that is used to point to a certain place in the document. The following URI points to the weather in Lisbon (Portugal) on the morning of the 1^st January 2013:

http://www.weather.com:8080/weather/2013/01/01?location=Lisbon,Portugal&time=morning

Representations

So far I’ve explained what a resource is and where you can find it. But what is the representation of the resource the URI is pointing to? Are there several representations for a single resource? Actually you might want to get the representation of a resource as text, JSON, XML, PDF document, JPG image, or another data format. When the client deals with a resource, it is always through its representation; the resource itself remains on the server. Representation is any useful information about the state of a resource. For example, the list of Java books mentioned previously has at least two representations:

• The HTML page rendered by your browser: http://www.apress.com/java
• The comma-separated value (CSV) file of books: http://www.apress.com/resource/csv/bookcategory?cat=32

How do you choose between the different representations of a given resource? Two solutions are possible. The service could expose one URI per representation as shown above. However, the two URIs are really different and do not seem directly related. Following is a neater set of URIs:

• http://www.apress.com/java
• http://www.apress.com/java/csv
• http://www.apress.com/java/xml

The first URI is the default representation of the resource, and additional representations append their format extension to it: /csv (for text/csv), /xml, /pdf, and so on.

Another solution is to expose one single URI for all representations (e.g., http://www.apress.com/java) and to rely on the mechanism called content negotiation, which I’ll discuss in more detail a little later in this chapter. For instance, a URI could have a human-readable and a machine-processable representation.

Addressability

An important tenet to follow when designing RESTful web services is addressability. Your web service should make your application as addressable as possible, which means that every valuable piece of information in your application should be a resource and have a URI, making that resource easily accessible. The URI is the only piece of data you need to publish to make the resource accessible, so your business partner won’t have guesswork to do in order to reach the resource.

For example, you’re dealing with a bug in your application, and your investigations lead you to line 42 of the class CreditCardValidator.java as the place where the bug occurs. Because you’re not responsible for this domain of the application, you want to file an issue so a qualified person will take care of it. How would you point her to the incriminating line? You could say, “Go to line 42 of the class CreditCardValidator,” or, if your source code is addressable through a repository browser, you could save the URI of the line itself in the bug report. This raises the issue of defining the granularity of your RESTful resources in your application: it could be at the line, method, or class level, and so forth.

Unique URIs make your resources linkable, and, because they are exposed through a uniform interface, everyone knows exactly how to interact with them, allowing people to use your application in ways you would have never imagined.

Connectedness

In graph theory, a graph is called connected if every pair of distinct vertices in the graph can be connected through some path. It is said to be strongly connected if it contains a direct path from u to v and a direct path from v to u for every pair of vertices u,v. REST advocates that resources should be as connected as possible.

Once again, this daunting statement resulted from an examination of the success of the Web. Web pages embed links to navigate through pages in a logical and smooth manner and, as such, the Web is very well connected. If there is a strong relationship between two resources, they should be connected. REST states that web services should also take advantage of hypermedia to inform the client of what is available and where to go. It promotes the discoverability of services. From a single URI, a user agent accessing a well-connected web service could discover all available actions, resources, their various representations, and so forth.

For instance, when a user agent (e.g., a Web browser) looks up the representation of a CD (see Listing 15-1), this representation could have not only the names of the artist, but also a link, or a URI, to the biography. It’s up to the user agent to actually retrieve it or not. The representation could also link to other representations of the resource or available actions.

Listing 15-1.  A CD Representation Connected to Other Services

<cd>
  <title>Ella and Louis</title>
  <year ref=" http://music.com/year/1956 ">1956</year >
  <artist ref=" http://music.com/artists/123">Ella Fitzgerald</artist>
  <artist ref=" http://music.com/artists/456 ">Louis Armstrong</artist>
  <link rel="self" type="text/json" href=" http://music.com/album/789 "/>
  <link rel="self" type="text/xml" href=" http://music.com/album/789 "/>
  <link rel=" http://music.com/album/comments " type="text/xml" →
       href=" http://music.com/album/789/comments "/>
</cd>

Another crucial aspect of the hypermedia principle is the state of the application, which must be led by the hypermedia. In short, the fact that the web service provides a set of links enables the client to move the application from one state to the next by simply following a link.

In the preceding XML snippet, the client could change the state of the application by commenting on the album. The list of comments on the album is a resource addressable with the URI http://music.com/album/789/comments. Because this web service uses a uniform interface, once the client knows the URI format, the available content types and the data format, it will know exactly how to interact with it: a GET will retrieve the list of existing comments, a PUT will update the comment, and so on. From this single initial request, the client can take many actions: the hypermedia drives the state of the application.

Uniform Interface

One of the main constraints that make an architecture RESTful is the use of a uniform interface to manage your resources. Pick whatever interface suits you, but use it in the same way across the board, from resource to resource, from service to service. Never stray from it or alter the original meaning. By using a uniform interface, “the overall system architecture is simplified and the visibility of interactions is improved” (Roy Thomas Fielding, Architectural Styles and the Design of Network-based Software Architectures). Your services become part of a community of services using the exact same semantic.

The de facto web protocol is HTTP, which is a document-based standardized request/response protocol between a client and a server. HTTP is the uniform interface of RESTful web services. Web services built on SOAP, WSDL, and other WS-* standards also use HTTP as the transport layer, but they leverage only a very few of its capabilities (as SOAP web services can also use other transport protocols such as JMS). You have to discover the semantic of the service by analyzing the WSDL and then invoke the right methods. RESTful web services have a uniform interface (HTTP methods and URIs), so, once you know where the resource is (URI), you can invoke the HTTP method (GET, POST, etc.).

In addition to familiarity, a uniform interface promotes interoperability between applications; HTTP is widely supported, and the number of HTTP client libraries guarantees that you won’t have to deal with communication issues.

Statelessness

The last feature of REST is statelessness, which means that every HTTP request happens in complete isolation, as the server should never keep track of requests that were executed before. For the sake of clarity, resource state and application state are usually distinguished. The resource state must live on the server and is shared by everybody, while the application state must remain on the client and is its sole property. Going back to the example in Listing 15-1, the application state is that the client has fetched a representation of the album Ella and Louis, but the server should not hold onto this information. The resource state is the album information itself; the server should obviously maintain this information. The client may change the resource state. If the shopping cart is a resource with restricted access to just one client, the application needs to keep track of the shopping cart ID in the client session.

Statelessness comes with many advantages such as better scalability: no session information to handle, no need to route subsequent requests to the same server (load-balancing), failure handling (e.g., service interruptions), and so on. If you need to keep state, the client has to do extra work to store it.

HTTP

HTTP, a protocol for distributed, collaborative, hypermedia information systems, led to the establishment of the World Wide Web together with URIs, HTML, and the first browsers. Coordinated by the World Wide Web Consortium (W3C) and the Internet Engineering Task Force (IETF), HTTP is the result of several Requests For Comment (RFC), notably RFC 216, which defines HTTP 1.1.

$ curl -v –X GEThttp://www.apress.com/java?limit=all&mode=list
> GET /java?limit=all&mode=list HTTP/1.1
> User-Agent: curl/7.23.1 (x86_64-apple-darwin11.2.0) libcurl/7.23.1 zlib/1.2.5
> Host: www.apress.com
> Accept: */*

< HTTP/1.1 200 OK
< Date : Sat, 17 Nov 2012 17:42:15 GMT
< Server: Apache/2.2.3 (Red Hat)
< X-Powered-By: PHP/5.2.17
< Vary: Accept-Encoding,User-Agent
< Transfer-Encoding: chunked
< Content-Type : text/html; charset=UTF-8
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
  <title>
  ...

From the Web to Web Services

We all use the Web and know how it works, so why should web services behave differently? After all, services also often exchange uniquely identified resources, linked with others like hyperlinks. Web architecture has proven its scalability for years; why reinvent the wheel? To create, update, and delete a book resource, why not use the common HTTP verbs? For example:

• Use POST to create a book resource (passing XML, JSON, or any other format) with the URI http://www.apress.com/book/. Once created, the response sends back the URI of the new resource: http://www.apress.com/book/123456.
• Use GET to read the resource (and possible links to other resources from the entity body) at http://www.apress.com/book/123456.
• Use PUT on data to update the book resource at http://www.apress.com/book/123456.
• Use DELETE to delete the resource at http://www.apress.com/book/123456.

By using HTTP verbs, we have access to all possible Create, Read, Update, Delete (CRUD) actions on a resource.

WADL

While SOAP-based services rely on WSDL to describe the format of possible requests for a given web service, Web Application Description Language (WADL) is used to expose the possible interactions with a given RESTful web service. It eases client development, which can load and interact directly with the resources. WADL was submitted to the W3C but the consortium has no current plans to standardize it because it is not widely supported. Listing 15-2 shows you what it can look like.

Listing 15-2.  WADL Defining Several Operations That Can Be Invoked on a Resource

<application xmlns=" http://wadl.dev.java.net/2009/02 ">
  <doc xmlns:jersey=" http://jersey.java.net/ " jersey:generatedBy="Jersey: 2.0"/>
 
  <resources base=" http://www.apress.com/ ">
 
      <resource path=" {id} ">
        <param name="id" style="template" type="xs:long"/>
        <method name=" GET ">
          <response>
            <representation element="book" mediaType="application/xml"/>
            <representation element="book" mediaType="application/json"/>
          </response>
        </method>
        <method name=" DELETE "/>
      </resource>
 
      <resource path=" book ">
        <method name=" GET ">
          <response>
            <representation element="book" mediaType=" application/xml "/>
            <representation element="book" mediaType=" application/json "/>
          </response>
        </method>
      </resource>
 
  </resources>
</application>

Listing 15-2 describes a resource root (http://www.apress.com/) to where you can pass an id ({id}) to GET or DELETE a book. Another resource allows you to GET all the books from APress in JSON or XML.

A Brief History of REST

The term REST was first introduced by Roy Thomas Fielding in Chapter 5 of his PhD thesis, Architectural Styles and the Design of Network-based Software Architectures (University of California, Irvine, 2000, http://www.ics.uci.edu/∼fielding/pubs/dissertation/top.htm). The dissertation is a retrospective explanation of the architecture chosen to develop the Web. In his thesis, Fielding takes a look at the parts of the World Wide Web that work very well and extracts design principles that could make any other distributed hypermedia system—whether related to the Web or not—as efficient.

The original motivation for developing REST was to create an architectural model of the Web. Roy T. Fielding is also one of the authors of the HTTP specification, so it’s not surprising that HTTP fits quite well the architectural design he described in his dissertation.

Java API for RESTful Web Services

To write RESTful web services in Java, you would only need a client and a server that support HTTP. Any browser and an HTTP servlet container will do the job at the cost of some XML configuration and glue-code pain to parse HTTP requests and responses. Once completed, this technical code would be barely readable and maintainable. This is where JAX-RS comes to the rescue. As you’ll see, with just a few annotations you get the full power of invoking HTTP resources and parsing them.

The first version of the JAX-RS specification (JSR 311), finalized in October 2008, defined a set of APIs that promoted the REST architecture style. But it only covered the server-side aspect of REST. With Java EE 7, JAX-RS has been updated to a 2.0 version and now defines a client API among other novelties.

What’s New in JAX-RS 2.0?

JAX-RS 2.0 (JSR 339) is a major release focusing on integration with Java EE 7 and its new features. The major new features of JAX-RS 2.0 are as follows:

• A client API was missing from JAX-RS 1.x so each implementation defined its own proprietary API. JAX-RS 2.0 fills this gap with a fluent, low-level, request building API.
• Like SOAP handlers or Managed Bean interceptors, JAX-RS 2.0 now has filters and interceptors so you can intercept request and response and do some processing.
• With the new asynchronous processing you can now implement long-polling interfaces or server-side push.
• Integration with Bean Validation has been achieved so you can constrain your RESTful web services.

Table 15-4 lists the main packages defined in JAX-RS.

Reference Implementation

Jersey is the reference implementation of JAX-RS. It is an open source project under dual CDDL and GPL licenses. Jersey also provides a specific API so that you can extend Jersey itself.

Other implementations of JAX-RS are also available such as CXF (Apache), RESTEasy (JBoss), and Restlet (a senior project that existed even before JAX-RS was finalized).

Anatomy of a RESTful Web Service

From Listing 15-3, you can see that the REST service doesn’t implement any interface nor extend any class; the only mandatory annotation to turn a POJO into a REST service is @Path. JAX-RS relies on configuration by exception, so it has a set of annotations to configure the default behavior. Following are the requirements to write a REST service:

• The class must be annotated with @javax.ws.rs.Path (in JAX-RS 2.0 there is no XML equivalent to meta-data as there is no deployment descriptor).
• The class must be defined as public, and it must not be final or abstract.
• Root resource classes (classes with a @Path annotation) must have a default public constructor. Non-root resource classes do not require such a constructor.
• The class must not define the finalize() method.
• To add EJB capabilities to a REST service, the class has to be annotated with @javax.ejb.Stateless or @javax.ejb.Singleton (see Chapter 7).
• A service must be a stateless object and should not save client-specific state across method calls.

CRUD Operations on a RESTful Web Service

Listing 15-3 shows how to write a very simple REST service that returns a String. But most of the time you need to access a database, retrieve or store data in a transactional manner. For this you can have a REST service and add stateless session beans functionalities by adding the @Stateless annotation. This will allow transactional access to a persistent layer (JPA entities), as shown in Listing 15-4.

Listing 15-4.  A Book RESTful Web Service Creating, Deleting, and Retrieving Books from the Database

@Path("book")
@Stateless
public class BookRestService {
 
  @Context
  private UriInfo uriInfo;
  @PersistenceContext(unitName = "chapter15PU")
  private EntityManager em ;
 
  @GET
  @Produces(MediaType.APPLICATION_XML)
  public Books getBooks() {
    TypedQuery<Book> query = em.createNamedQuery (Book.FIND_ALL, Book.class);
    Books books = new Books(query.getResultList());
    return books;
  }
 
  @POST
  @Consumes(MediaType.APPLICATION_XML)
  public Response createBook(Book book) {
    em.persist (book);
    URI bookUri = uriInfo.getAbsolutePathBuilder().path(book.getId().toString()).build();
    return Response.created(bookUri).build();
  }
 
  @DELETE
  @Path("{id}")
  public Response deleteBook(@PathParam("id") Long bookId) {
    em.remove (em.find(Book.class, bookId));
    return Response.noContent().build();
  }
}

The code in Listing 15-4 represents a REST service that can consume and produce an XML representation of a book. The getBooks() method retrieves the list of books from the database and returns an XML representation (using content negotiation) of this list, accessible through a GET method. The createBook() method takes an XML representation of a book and persists it to the database. This method is invoked with an HTTP POST and returns a Response with the URI (bookUri) of the new book as well as the created status. The deleteBook method takes a book id as a parameter and deletes it from the database.

The code in Listing 15-4 follows a very simple JAX-RS model and uses a set of powerful annotations. Let’s now take a deeper look at all the concepts shown in the code.

URI Definition and Binding URIs

The @Path annotation represents a relative URI that can annotate a class or a method. When used on classes, it is referred to as the root resource, providing the root of the resource tree and giving access to subresources. Listing 15-5 shows a REST service that can be access at http://www.myserver.com/items. All the methods of this service will have /items as root.

Listing 15-5.  Root Path to an Item Resource

@Path ("/items")
public class ItemRestService {
 
  @GET
  public Items getItems() {
    // ...
  }
}

You can then add subpaths to your methods, which can be useful to group together common functionalities for several resources as shown in Listing 15-6 (you may ignore for the moment the @GET, @POST, and @DELETE annotations in the listing, as they will be described later in the “HTTP Method Matching” section).

Listing 15-6.  Several Subpaths in the ItemRestService

@Path(" /items ")
public class ItemRestService {
 
  @GET
  public Items getItems() {
    // URI : /items
  }
 
  @GET
  @Path(" /cds ")
  public CDs getCDs() {
    // URI : /items/cds
  }
 
  @GET
  @Path(" /books ")
  public Books getBooks() {
    // URI : /items/books
  }
 
  @POST
  @Path(" /book ")
  public Response createBook(Book book) {
    // URI : /items/book
  }
}

Listing 15-6 represents a RESTful web service that will give you methods to get all the items (CDs and books) from the CD-BookStore Application. When requesting the root resource /items, the only method without sub @Path will be selected (getItems()). Then, when @Path exists on both the class and method, the relative path to the method is a concatenation of both. For example, to get all the CDs, the path will be /items/cds. When requesting /items/books, the getBooks() method will be invoked. To create a new book you need to point at /items/book.

If @Path("/items") only existed on the class, and not on any methods, the path to access each method would be the same. The only way to differentiate them would be the HTTP verb (GET, PUT, etc.) and the content negotiation (text, XML, etc.), as you’ll later see.

Extracting Parameters

Having nice URIs by concatenating paths to access your resource is very important in REST. But paths and subpaths are not enough: you also need to pass parameters to your RESTful web services, extract and process them at runtime. Listing 15-4 showed how to get a parameter out of the path with @javax.ws.rs.PathParam. JAX-RS provides a rich set of annotations to extract the different parameters that a request could send (@PathParam, @QueryParam, @MatrixParam, @CookieParam, @HeaderParam, and @FormParam).

Listing 15-7 shows how the @PathParam annotation is used to extract the value of a URI template parameter. A parameter has a name and is represented by a variable between curly braces or by a variable that follows a regular expression. The searchCustomers method takes any String parameter while getCustomerByLogin only allows lowercase/uppercase alphabetical letters ([a-zA-Z]*) and getCustomerById only digits (\d+).

Listing 15-7.  Extracting Path Parameters and Regular Expressions

@Path("/customer")
@Produces(MediaType.APPLICATION_JSON)
public class CustomerRestService {
 
  @Path("search/ {text} ")
  public Customers searchCustomers( @PathParam("text") String textToSearch) {
    // URI : /customer/search/ smith
  }
 
  @GET
  @Path(" {login: [a-zA-Z]*} ")
  public Customer getCustomerByLogin( @PathParam("login") String login) {
    // URI : /customer/ foobarsmith
  }
 
  @GET
  @Path(" {customerId : \d+} ")
  public Customer getCustomerById( @PathParam("customerId") Long id) {
    // URI : /customer/ 12345
  }
}

The @QueryParam annotation extracts the value of a URI query parameter. Query parameters are key/value pairs separated by an & symbol such as http://www.myserver.com/customer?zip=75012&city=Paris. The @MatrixParam annotation acts like @QueryParam, except it extracts the value of a URI matrix parameter (; is used as a delimiter instead of ?). Listing 15-8 shows how to extract both query and matrix parameters from URIs.

Listing 15-8.  Extracting Query and Matrix Parameters

@Path("/customer")
@Produces(MediaType.APPLICATION_JSON)
public class CustomerRestService {
 
  @GET
  public Customers getCustomersByZipCode( @QueryParam("zip") Long zip, →
                                              @QueryParam("city") String city) {
    // URI : /customer ?zip=75012&city=Paris
  }
 
  @GET
  @Path("search")
  public Customers getCustomersByName( @MatrixParam("firstname") String firstname, →
                                           @MatrixParam("surname") String surname) {
    // URI : /customer/search ;firstname=Antonio;surname=Goncalves
  }
}

Two other annotations are related to the innards of HTTP, things you don’t see directly in URIs: cookies and HTTP headers @CookieParam extracts the value of a cookie, while @HeaderParam extracts the value of a header field. Listing 15-9 extracts the session ID from the cookie and the User Agent from the HTTP header.

Listing 15-9.  Extracting Values From the Cookie and HTTP Header

@Path("/customer")
@Produces(MediaType.TEXT_PLAIN)
public class CustomerRestService {
 
  @GET
  public String extractSessionID( @CookieParam("sessionID") String sessionID) {
    // ...
  }
 
  @GET
  public String extractUserAgent( @HeaderParam("User-Agent") String userAgent) {
    // ...
  }
}

The @FormParam annotation specifies that the value of a parameter is to be extracted from a form in a request entity body. @FormParam is not required to be supported on fields or properties.

With all these annotations, you can add a @DefaultValue annotation to define the default value for a parameter you’re expecting. The default value is used if the corresponding parameter is not present in the request. Listing 15-10 sets default values to query and matrix parameters. For example, in the method getCustomersByAge, if the query parameter age is not in the request, the default value is set to 50.

Listing 15-10.  Defining Default Values

@Path("/customer")
public class CustomerRestService {
 
  @GET
  public Customers getCustomersByAge( @DefaultValue("50") @QueryParam("age") int age) {
    // ...
  }
 
  @GET
  public Customers getCustomersByCity( @DefaultValue("Paris") @MatrixParam("city") →
                                                                    String city) {
    // ...
  }
}

Consuming and Producing Content Types

With REST, the same resource can have several representations; a book can be represented as a web page, a PDF, or an image showing the book cover. JAX-RS specifies a number of Java types that can represent a resource such as String, InputStream and JAXB beans. The @javax.ws.rs.Consumes and @javax.ws.rs.Produces annotations may be applied to a resource where several representations are possible. It defines the media types of the representation exchanged between the client and the server. JAX-RS has a javax.ws.rs.core.MediaType class that acts like an abstraction for a MIME type. It has several methods and defines the constants listed in Table 15-5.

Using the @Consumes and @Produces annotations on a method overrides any annotations on the resource class for a method argument or return type. In the absence of either of these annotations, support for any media type (*/*) is assumed. By default, CustomerRestService produces plain text representations that are overridden in some methods (see Listing 15-11). Note that the getAsJsonAndXML produces an array of representations (XML or JSON).

Listing 15-11.  A Customer Resource with Several Representations

@Path("/customer")
@Produces(MediaType.TEXT_PLAIN)
public class CustomerRestService {
 
  @GET
  public Response getAsPlainText() {
    // ...
  }
 
  @GET
  @Produces(MediaType.TEXT_HTML)
  public Response getAsHtml() {
    // ...
  }
 
  @GET
  @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
  public Response getAsJsonAndXML() {
    // ...
  }
 
  @PUT
  @Consumes(MediaType.TEXT_PLAIN)
  public void putName(String customer) {
    // ...
  }
}

If a RESTful web service is capable of producing more than one media type, the targeted method will correspond to the most acceptable media type, as declared by the client in the Accept header of the HTTP request. For example, if the Accept header is:

Accept: text/plain

and the URI is /customer, the getAsPlainText() method will be invoked. But the client could have used the following HTTP header:

Accept: text/plain; q=0.8, text/html

This header declares that the client can accept media types of text/plain and text/html but prefers the latter using the quality factor (or preference weight) of 0.8 (“I prefer text/html, but send me text/plain if it is the best available after an 80% markdown in quality”). By including such header and pointing at the /customer URI, the getAsHtml() method will be invoked.

Returned Types

So far you’ve seen mostly how to invoke a method (using parameters, media type, HTTP methods . . .) without caring about the returned type. What can a RESTful web service return? Like any Java class, a method can return any standard Java type, a JAXB bean or any other object as long as it has a textual representation that can be transported over HTTP. In this case, the runtime determines the MIME type of the object being returned and invokes the appropriate Entity Provider (see later) to get its representation. The runtime also determines the appropriate HTTP return code to send to the consumer (204-No Content if the resource method's return type is void or null; 200-OK if the returned value is not null). But sometimes you want finer control of what you are returning: the response body (a.k.a. an entity) of course, but also the response code and/or response headers or cookies. That’s when you return a Reponse object. It is a good practice to return a javax.ws.rs.core.Response with an entity since it would guarantee a return content type. Listing 15-12 shows you different return types.

Listing 15-12.  A Customer Service Returning Data Types, a JAXB Bean, and a Response

@Path("/customer")
public class CustomerRestService {
 
  @GET
  public String getAsPlainText() {
    return new Customer("John", "Smith", "[email protected]", "1234565").toString();
  }
 
  @GET
  @Path("maxbonus")
  public Long getMaximumBonusAllowed() {
    return 1234L;
  }
 
  @GET
  @Produces(MediaType.APPLICATION_XML)
  public Customer getAsXML() {
    return new Customer("John", "Smith", "[email protected]", "1234565");
  }
 
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public Response getAsJson() {
    return Response.ok(new Customer("John", "Smith", "[email protected]", "1234565"),→
                                                        MediaType.APPLICATION_JSON).build();
  }
}

The getAsPlainText method returns a String representation of a customer and the getMaximumBonusAllowed returns a numerical constant. The defaults will apply so the return HTTP status on both methods will be 200-OK (if no exception occurs). The getAsXML returns a Customer JAXB POJO meaning that the runtime will marshall the object into an XML representation.

The getAsJson method doesn’t return an entity but instead a javax.ws.rs.core.Response object. A Response wraps the entity that is returned to the consumer and it’s instantiated using the ResponseBuilder class as a factory. In this example, we still want to return a JAXB object (the Customer) with a 200-OK status code (the ok() method), but we also want to specify the MIME type to be JSON. Calling the ResponseBuilder.build() method creates the final Response instance.

It is recommended to return a custom Response for all requests rather than the entity itself (you can then set a specific status code if needed). Table 15-6 shows a subset of the Response API.

The Response and ResponseBuilder follow the fluent API design pattern. Meaning you can easily write a response by concatenating methods. This also makes the code more readable. Here are some examples of what you can write with this API:

Response. ok ().build();
Response.ok(). cookie (new NewCookie("SessionID", "5G79GDIFY09")).build();
Response.ok("Plain Text"). expires (new Date()).build();
Response.ok(new Customer ("John", "Smith"), MediaType.APPLICATION_JSON). build ();
Response. noContent ().build();
Response. accepted (new Customer("John", "Smith", "[email protected]", "1234565")).build();
Response.notModified(). header ("User-Agent", "Mozilla").build();

HTTP Method Matching

You’ve seen how the HTTP protocol works with its requests, responses, and action methods (GET, POST, PUT, etc.). JAX-RS defines these common HTTP methods using annotations: @GET, @POST, @PUT, @DELETE, @HEAD, and @OPTIONS. Only public methods may be exposed as resource methods. Listing 15-13 shows a customer RESTful web service exposing CRUD methods: @GET methods to retrieve resources, @POST methods to create a new resource, @PUT methods to update an existing resource, and @DELETE methods to delete a resource.

Listing 15-13.  A Customer Resource Exposing CRUD Operations and Retuning Responses

@Path("/customer")
@Produces(MediaType.APPLICATION_XML)
@Consumes(MediaType.APPLICATION_XML)
public class CustomerRestService {
 
  @GET
  public Response getCustomers() {
    // ..
    return Response. ok (customers).build();
  }
 
  @GET
  @Path("{customerId}")
  public Response getCustomer(@PathParam("customerId") String customerId) {
    // ..
    return Response. ok (customer).build();
  }
 
  @POST
  public Response createCustomer(Customer customer) {
    // ..
    return Response. created (createdCustomerURI).build();
  }
 
  @PUT
  public Response updateCustomer(Customer customer) {
    // ..
    return Response. ok (customer).build();
  }
 
  @DELETE
  @Path("{customerId}")
  public Response deleteCustomer(@PathParam("customerId") String customerId) {
    // ..
    return Response. noContent ().build();
  }
}

The HTTP specification defines what HTTP response codes should be on a successful request. You can expect JAX-RS to return the same default response codes:

• GET methods retrieve whatever information (in the form of an entity) is identified by the requested URI. GET should return 200-OK.
• The PUT method refers to an already existing resource that needs to be updated. If an existing resource is modified, either the 200-OK or 204-No Content response should be sent to indicate successful completion of the request.
• The POST method is used to create a new resource identified by the request URI. The response should return 201-CREATED with the URI of this new resource or 204-No Content if it does not result in a resource that can be identified by a URI.
• The DELETE method requests that the server deletes the resource identified by the requested URI. A successful response should be 200-OK if the response includes an entity, 202-Accepted if the action has not yet been enacted, or 204-No Content if the action has been enacted but the response does not include an entity.

public class URIBuilderTest {
 
  @Test
  public void shouldBuildURIs() {
    URI uri = →
        UriBuilder.fromUri (" http://www.myserver.com").path("book").path("1234").build();
    assertEquals(" http://www.myserver.com/book/1234 ", uri.toString());
 
    uri = UriBuilder.fromUri(" http://www.myserver.com").path(SPI_AMPquot;book ") →
                                  . queryParam ("author", "Goncalves").build();
    assertEquals(" http://www.myserver.com/book?author=Goncalves ", uri.toString());
 
    uri = UriBuilder.fromUri(" http://www.myserver.com").path(SPI_AMPquot;book ") →
                                 . matrixParam ("author", "Goncalves").build();
    assertEquals(" http://www.myserver.com/book;author=Goncalves ", uri.toString());
 
    uri = UriBuilder.fromUri(" http://www.myserver.com").path(SPI_AMPquot; {path} ") →
           .queryParam("author", " {value} ").build(" book ", " Goncalves ");
    assertEquals(" http://www.myserver.com/book?author=Goncalves ", uri.toString());
 
 
    uri = UriBuilder. fromResource (BookRestService.class).path("1234").build();
    assertEquals(" /book/1234 ", uri.toString());
 
    uri = UriBuilder.fromUri(" http://www.myserver.com").fragment("book").build() ;
    assertEquals(" http://www.myserver.com/#book", uri.toString());
 
  }
}

Contextual Information

When a request is being processed, the resource provider needs contextual information to perform the request properly. The @javax.ws.rs.core.Context annotation is intended to inject into an attribute or a method parameter the following classes: HttpHeaders, UriInfo, Request, SecurityContext, and Providers. For example, Listing 15-15 shows the code that injects UriInfo so it can build URIs and HttpHeaders to return some headers information.

Listing 15-15.  A Customer Resource Getting HttpHeaders and UriInfo

@Path("/customer")
public class CustomerRestService {
 
  @Context
  UriInfo uriInfo ;
 
  @Inject
  private CustomerEJB customerEJB;
 
  @GET
  @Path("media")
  public String getDefaultMediaType( @Context HttpHeaders headers) {
    List<MediaType> mediaTypes = headers.getAcceptableMediaTypes();
    return mediaTypes.get(0).toString();
  }
 
  @GET
  @Path("language")
  public String getDefaultLanguage( @Context HttpHeaders headers) {
    List<String> mediaTypes = headers.getRequestHeader(HttpHeaders.ACCEPT_LANGUAGE);
    return mediaTypes.get(0);
  }
 
  @POST
  @Consumes(MediaType.APPLICATION_XML)
  public Response createCustomer(Customer cust) {
    Customer customer = customerEJB.persist(cust);
    URI bookUri = uriInfo .getAbsolutePathBuilder().path(customer.getId()).build();
    return Response.created(bookUri).build();
  }
}

As you saw earlier with HTTP, information is transported between the client and the server not only in the entity body, but also in the headers (Date, Server, Content-Type, etc.). HTTP headers take part in the uniform interface, and RESTful web services use them in their original meanings. As a resource developer, you may need to access HTTP headers; that’s what the javax.ws.rs.core.HttpHeaders interface serves. An instance of HttpHeaders can be injected into an attribute or a method parameter using the @Context annotation, as the HttpHeaders class is a map with helper methods to access the header values in a case-insensitive manner. In Listing 15-15 the service returns the default Accept-Language and MediaType.

Entity Provider

When entities are received in requests or sent in responses, the JAX-RS implementation needs a way to convert the representations to a Java type and vice versa. This is the role of entity providers that supply mapping services between representations and their associated java types. An example is JAXB, which maps an object to an XML representation and vice versa. If the default XML and JSON providers are not sufficient, then you can develop your own custom entity providers. You can even define your own format. What you need then is to give the JAX-RS runtime a way to read/write your custom format into/from an entity by implementing your own entity provider. Entity providers come in two flavors: MessageBodyReader and MessageBodyWriter.

Let’s say you want to exchange your Customer bean into a custom/format that would look like this: 1234/John/Smith. As you can see, the delimiter is the ‘/’ symbol, the first token is the customer id, the second the first name and the last one the surname. You first need a class (a writer) that takes a Customer bean and maps it to a response body. Listing 15-16 shows the CustomCustomerWriter class that must implement the javax.ws.rs.ext.MessageBodyWriter interface and be annotated with @Provider. The annotation @Produces specifies our custom media type ("custom/format"). As you can see, the writeTo method converts a Customer bean into a stream following the custom format.

Listing 15-16.  A Provider Producing a Custom Representation of a Customer

@Provider
@Produces("custom/format")
public class CustomCustomerWriter implements MessageBodyWriter <Customer> {
 
  @Override
  public boolean isWriteable(Class<?> type, Type genericType, Annotation[] annotations, →
                                                              MediaType mediaType) {
    return Customer.class.isAssignableFrom(type);
  }
 
  @Override
  public void writeTo(Customer customer, Class<?> type, Type gType, Annotation[] →
             annotations, MediaType mediaType, MultivaluedMap<String, Object> httpHeaders, →
                   OutputStream outputStream) throws IOException, WebApplicationException {
 
    outputStream.write(customer. getId ().getBytes());
    outputStream.write(' / '),
    outputStream.write(customer. getFirstName ().getBytes());
    outputStream.write(' / '),
    outputStream.write(customer. getLastName ().getBytes());
  }
 
  @Override
  public long getSize(Customer customer, Class<?> type, Type genericType, Annotation[] →
                                                        annotations, MediaType mediaType) {
    return customer.getId().length() + 1 + customer.getFirstName().length() + 1 +  →
                                           customer.getLastName().length();
  }
}

On the other hand, to map a request body to a Java type, a class must implement the javax.ws.rs.ext.MessageBodyReader interface and be annotated with @Provider. By default, the implementation is assumed to consume all media types (*/*). The annotation @Consumes in Listing 15-17 is used to specify our custom media type. The method readFrom takes the input stream, tokenizes it using the ‘/’ delimiter and converts it into a Customer object. MessageBodyReader and MessageBodyWriter implementations may throw a WebApplicationException if they can’t produce any representation.

Listing 15-17.  A Provider Consuming a Custom Stream and Creating a Customer

@Provider
@Consumes("custom/format")
public class CustomCustomerReader implements MessageBodyReader <Customer> {
 
  @Override
  public boolean isReadable(Class<?> type, Type genericType, Annotation[] annotations, →
                                                             MediaType mediaType) {
    return Customer.class.isAssignableFrom(type);
  }
 
  @Override
  public Customer readFrom(Class<Customer> type, Type gType, Annotation[] annotations, →
                      MediaType mediaType, MultivaluedMap<String, String> httpHeaders, →
                      InputStream inputStream) throws IOException, WebApplicationException {
 
    String str = convertStreamToString(inputStream);
    StringTokenizer s = new StringTokenizer(str, " / ");
 
    Customer customer = new Customer();
    customer.setId(s.nextToken());
    customer.setFirstName(s.nextToken());
    customer.setLastName(s.nextToken());
 
    return customer;
  }
}

Thanks to our CustomCustomerWriter and CustomCustomerReader we can now exchange data represented by our custom format, back and forth from the service to the consumer. The RESTful web service just has to declare the correct media type and the JAX-RS runtime will do the rest:

@GET
@Produces("custom/format")
public Customer getCustomCustomer () {
  return new Customer("1234", "John", "Smith");
}

Our custom format is a specific case, but for common media types, the JAX-RS implementation comes with a set of default entity providers (see Table 15-7). So for most common cases you don’t have to worry about implementing your own reader and writer.

Handling Exceptions

The code so far was executed in a happy world where everything works and no exception handling has been necessary. Unfortunately, life is not that perfect, and sooner or later you’ll have to face a resource being blown up either because the data you received is not valid or because pieces of the network are not reliable.

A resource method may throw any checked or unchecked exception. Unchecked exceptions can be rethrown and allowed to propagate to the underlying container. Conversely, checked exceptions cannot be thrown directly and must be wrapped in a container-specific exception (ServletException, WebServiceException or WebApplicationException). But you can also throw a javax.ws.rs.WebApplicationException or subclasses of it (BadRequestException, ForbiddenException, NotAcceptableException, NotAllowedException, NotAuthorizedException, NotFoundException, NotSupportedException). The exception will be caught by the JAX-RS implementation and converted into an HTTP response. The default error is a 500 with a blank message, but the class javax.ws.rs.WebApplicationException offers various constructors so you can pick a specific status code (defined in the enumeration javax.ws.rs.core.Response.Status) or an entity. In Listing 15-18 the method getCustomer throws an unchecked exception (IllegalArgumentException) if the customer id is lower than 1000, and a 404-Not Found if the customer is not found in the database (instead it could have thrown a NotFoundException).

Listing 15-18.  A Method Throwing Exceptions

@Path("/customer")
public class CustomerRestService {
 
  @Inject
  private CustomerEJB customerEJB;
 
  @Path("{customerId}")
  public Customer getCustomer(@PathParam("customerId") Long customerId) {
    if (customerId < 1000)
      throw new IllegalArgumentException("Id must be greater than 1000!");
 
    Customer customer = customerEJB.find(customerId);
    if (customer == null)
      throw new WebApplicationException(Response.Status.NOT_FOUND);
    return customer;
  }
}

To keep your code DRY (which stands for Don’t Repeat Yourself), you can supply exception mapping providers. An exception mapping provider maps a general exception to a Response. If this exception is thrown, the JAX-RS implementation will catch it and invoke the corresponding exception mapping provider. An exception mapping provider is an implementation of ExceptionMapper<E extends java.lang.Throwable>, annotated with @Provider. Listing 15-19 maps a javax.persistence.EntityNotFoundException to a 404-Not Found status code.

Listing 15-19.  An JPA Exception Mapped to a 404-Not Found Status Code

@Provider
public class EntityNotFoundMapper implements ExceptionMapper <EntityNotFoundException> {
 
  public Response toResponse(javax.persistence.EntityNotFoundException ex) {
    return Response.status(404).entity(ex.getMessage()).type(MediaType.TEXT_PLAIN).build();
  }
}

Life Cycle and Callback

When a request comes in, the targeted RESTful web service is resolved, and a new instance of the matching class is created. Thus, the life cycle of a RESTful web service is per request so the service does not have to worry about concurrency and can use instance variables safely.

If deployed in a Java EE container (servlet or EJB), JAX-RS resource classes and providers may also make use of the JSR 250 life-cycle management and security annotations: @PostConstruct, @PreDestroy, @RunAs, @RolesAllowed, @PermitAll, @DenyAll, and @DeclareRoles. The life cycle of a resource can use @PostConstruct and @PreDestroy to add business logic after the resource is created or before it is destroyed. Figure 15-3 shows the life cycle that is equivalent to most components in Java EE.

Packaging

RESTful web services may be packaged in a war or an EJB jar file depending if you are targeting the Web Profile or Full Java EE 7 services. Remember that a RESTful web service can also be annotated with @Stateless or @Singleton to benefit from the services of session beans. SOAP web services had several generated artifacts to package but that’s not the case for REST. The developer is responsible for just packaging the classes annotated with @Path (and other helper classes). Note that there is no deployment descriptor in JAX-RS 2.0.

The Client API

JAX-RS 2.0 introduces a new client API so that you can make HTTP requests to your remote RESTful web services easily (despite all the low-level details of the HTTP protocol). It is a fluent request building API (i.e., using the Builder design pattern) that uses a small number of classes and interfaces (see Table 15-8 to have an overview of the javax.ws.rs.client package as well as Table 15-6 for the Response API). Very often, you will come across three main classes: Client, WebTarget, and Response. The Client interface (obtained with the ClientBuilder) is a builder of WebTarget instances. A WebTarget represents a distinct URI from which you can invoke requests on to obtain a Response. From this Response you can check HTTP status, length or cookies but more importantly you can get its content (a.k.a. entity, message body or payload) through the Entity class.

Let’s take it step by step to discover how to use this new API and then put it all together to test a RESTful web service.

Client client = ClientBuilder.newClient();

Client client = ClientBuilder.newClient();
client.configuration().register(CustomCustomerReader.class).setProperty("MyProperty", 1234);

WebTarget target = client.target(" http://www.myserver.com/book ");

URI uri = new URI(" http://www.myserver.com/book ");
WebTarget target = client.target(uri);

Invocation invocation  = target.request().buildGet()

target.request(). buildDelete ();
target. queryParam ("author", "Eloise").request().buildGet();
target. path (bookId).request().buildGet();
target.request(MediaType.APPLICATION_XML).buildGet();
target.request(MediaType.APPLICATION_XML). acceptLanguage ("pt").buildGet();
target.request().buildPost( Entity.entity(new Book() ));

Response response = invocation.invoke();

Client client = ClientBuilder.newClient();
WebTarget target = client. target (" http://www.myserver.com/book ");
Invocation invocation  = target. request (MediaType.TEXT_PLAIN). buildGet ();
Response response = invocation.invoke();

Response response = ClientBuilder.newClient(). target (" http://www.myserver.com/book ") →
                                             . request (MediaType.TEXT_PLAIN). get ();

assertTrue(response. getStatusInfo () == Response.Status.OK );
assertTrue(response. getLength () == 4);
assertTrue(response. getDate () != null);
assertTrue(response. getHeaderString ("Content-type").equals("text/plain"));

String body = response. readEntity (String.class);

Book book = response.readEntity( Book.class );

Response response = ClientBuilder.newClient().target(" http://www.myserver.com/book ") →
                                             .request().get();
String body = response. readEntity(String.class) ;

String body = ClientBuilder.newClient().target(" http://www.myserver.com/book ") →
                                       .request(). get(String.class) ;

Anatomy of a REST Consumer

Contrary to JAX-WS, which is embedded in Java SE and allows you to invoke SOAP web services out of the box with a JDK, with JAX-RS you need the client API in your classpath. But that’s the only constraint. Unlike SOAP you don’t have to generate any artifacts. So RESTful web service consumers can be from any Java class running on the JVM (main class, integration test, batch processing), to any Java EE component running in a container (Servlet, EJB, Managed Bean).

Of course, one of the strength of RESTful web services is interoperability. So if you expose a set of resources on the Internet you will be able to have mobile devices (smartphones, tablets) and other web technologies (e.g., JavaScript) accessing them.

Writing the Book Entity

By now you understand the code of the Book entity, but there is one very important element to notice: this entity is also annotated with the JAXB @XmlRootElement annotation (see Listing 15-20), which allows it to have an XML representation of a book (and JSON with a Jersey extension that you will see later).

Listing 15-20.  A Book Entity with a JAXB Annotation

@Entity
@XmlRootElement
@NamedQuery(name = Book.FIND_ALL, query = "SELECT b FROM Book b")
public class Book {
 
  public static final String FIND_ALL = "Book.findAll";
 
  @Id
  @GeneratedValue
  private String id;
  @Column(nullable = false)
  private String title;
  private Float price;
  @Column(length = 2000)
  private String description;
  private String isbn;
  private Integer nbOfPage;
  private Boolean illustrations;
 
  // Constructors, getters, setters
}

This entity also has to be packaged with a persistence.xml file (not shown here for simplicity).

Writing the Books JAXB Bean

One of the methods of the RESTful web service retrieves all the books from the database. This method could have returned a List<Book> but that would not allow JAXB marshalling. To have an XML representation of a list of books we need to have a JAXB annotated POJO. As you can see in Listing 15-21, the Books class inherits from ArrayList<Book> and has an @XmlRootElement annotation.

Listing 15-21.  A Books JAXB Bean Containing a List of Book

@XmlRootElement
@XmlSeeAlso(Book.class)
public class Books extends ArrayList<Book> {
 
  public Books() {
    super();
  }
 
  public Books(Collection<? extends Book> c) {
    super(c);
  }
 
  @XmlElement(name = "book")
  public List<Book> getBooks() {
    return this;
  }
 
  public void setBooks(List<Book> books) {
    this.addAll(books);
  }
}

Writing the BookRestService

The BookRestService is a RESTful web service, implemented as a stateless session bean, using an entity manager to create, delete, and retrieve books. Let’s split the class in several parts and explain them all.

@Path("/book")
@Produces ({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Consumes ({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Stateless
public class BookRestService {
 
  @PersistenceContext(unitName = "chapter15PU")
  private EntityManager em;
  @Context
  private UriInfo uriInfo;
  // ...

  // ...
  @POST
  public Response createBook(Book book) {
    if (book == null)
      throw new BadRequestException ();
 
    em.persist(book);
    URI bookUri = uriInfo.getAbsolutePathBuilder().path(book.getId()).build();
    return Response.created(bookUri) .build();
  }
  // ...

$ curl -X POST --data-binary "{"description":"Science fiction comedy book", →
 "illustrations":false,"isbn":"1-84023-742-2","nbOfPage":354,"price":12.5, →
 "title":"The Hitchhiker's Guide to the Galaxy"}"  →
 -H "Content-Type: application/json " http://localhost:8080/chapter15-service-1.0/rs/book -v

> POST /chapter15-service-1.0/rs/book HTTP/1.1
> User-Agent: curl/7.23.1 (x86_64-apple-darwin11.2.0) libcurl/7.23.1
> Host: localhost:8080
> Accept: */*
> Content-Type: application/json
> Content-Length: 165
>
< HTTP/1.1 201 Created
< Server: GlassFish Server Open Source Edition  4.0
< Location: http://localhost:8080/chapter15-service-1.0/rs/book/601
< Date: Thu, 29 Nov 2012 21:49:44 GMT
< Content-Length: 0

// ...
@GET
@Path("{id}")
public Response getBook( @PathParam("id") String id) {
  Book book = em.find(Book.class, id);
 
  if (book == null)
    throw new NotFoundException ();
 
  return Response.ok(book) .build();
}
// ...

$ curl -X GET -H "Accept: application/json " →
                  http://localhost:8080/chapter15-service-1.0/rs/book/601
{"description":"Science fiction comedy book","id":"1","illustrations":false, →
                      "isbn":"1-84023-742-2","nbOfPage":354,"price":12.5,"title":"H2G2"}

$ curl -X GET -H "Accept: application/xml " →
                  http://localhost:8080/chapter15-service-1.0/rs/book/601
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><book><description>Science fiction →
 comedy book</description><id>601</id><illustrations>false</illustrations>978-1-4302-4188-1 →
1-84023-742-2</isbn><nbOfPage>354</nbOfPage><price>12.5</price><title>H2G2</title></book>

// ...
@GET
public Response getBooks() {
  TypedQuery<Book> query = em.createNamedQuery(Book.FIND_ALL, Book.class);
  Books books = new Books(query.getResultList()) ;
  return Response.ok( books ).build();
}
// ...

$ curl -X GET -H "Accept: application/ json " →
                          http://localhost:8080/chapter15-service-1.0/rs/book
$ curl -X GET -H "Accept: application/ xml " →
                          http://localhost:8080/chapter15-service-1.0/rs/book

// ...
@DELETE
@Path("{id}")
public Response deleteBook( @PathParam("id") String id ) {
  Book book = em.find(Book.class, id );
 
  if (book == null)
    throw new NotFoundException();
 
  em.remove(book);
 
  return Response.noContent().build();
}
// ...

$ curl -X DELETE http://localhost:8080/chapter15-service-1.0/rs/book/601 -v
> DELETE /chapter15-service-1.0/rs/book/601 HTTP/1.1
> User-Agent: curl/7.23.1 (x86_64-apple-darwin11.2.0) libcurl/7.23.1
> Host: localhost:8080
> Accept: */*
>
< HTTP/1.1 204 No Content
< Server: GlassFish Server Open Source Edition  4.0

Configuring JAX-RS

Before deploying the BookRestService and Book entity, we need to register a url pattern in Jersey to intercept HTTP calls to the services. This way the requests sent to the /rs path will get intercepted by Jersey. You can either set this url pattern by configuring the Jersey servlet in the web.xml file, or use the @ApplicationPath annotation (see Listing 15-27). The ApplicationConfig class needs to extend javax.ws.rs.core.Application and define all the RESTful web services of the application (here c.add(BookRestService.class)) as well as any other needed extension (c.add(MOXyJsonProvider.class)).

Listing 15-27.  The ApplicationConfig Class Declaring the /rs URL Pattern

@ApplicationPath("rs")
public class ApplicationConfig extends Application {
 
  private final Set<Class<?>> classes;
 
  public ApplicationConfig() {
    HashSet<Class<?>> c = new HashSet<>();
    c.add( BookRestService.class );
 
    c.add( MOXyJsonProvider.class );
 
    classes = Collections.unmodifiableSet(c);
  }
 
  @Override
  public Set<Class<?>> getClasses() {
    return classes;
  }
}

This class has to be somewhere in your project (no particular package) and, thanks to the @ApplicationPath annotation, it will map the requests to the /rs/* URL pattern. This means, each time a URL starts with /rs/, it will be handled by Jersey. And, indeed, in the examples that I have used with cURL, all the resource URLs start with /rs:

$ curl -X GET -H "Accept: application/json" →
                          http://localhost:8080/chapter15-service-1.0/rs/book

Compiling and Packaging with Maven

All the classes need now to be compiled and packaged in a war file (<packaging>war</packaging>). The pom.xml in Listing 15-28 declares all necessary dependencies to compile the code (which are all in glassfish-embedded-all). Remember that JAXB is part of Java SE, so we don’t need to add this dependency. Notice that the pom.xml declares the Failsafe plugin that is designed to run integration tests (used later to run the BookRestServiceIT integration test class).

Listing 15-28.  The pom.xml File to Compile, Test, and Package the RESTful Web Service

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns=" http://maven.apache.org/POM/4.0.0 " →
         xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance " →
         xsi:schemaLocation=" http://maven.apache.org/POM/4.0.0 →
         http://maven.apache.org/xsd/maven-4.0.0.xsd ">
  <modelVersion>4.0.0</modelVersion>
 
  <parent>
    <artifactId>chapter15</artifactId>
    <groupId>org.agoncal.book.javaee7</groupId>
    <version>1.0</version>
  </parent>
 
  <groupId>org.agoncal.book.javaee7.chapter15</groupId>
  <artifactId>chapter15-service</artifactId>
  <version>1.0</version>
  <packaging>war</packaging>
 
  <dependencies>
    <dependency>
      <groupId>org.glassfish.main.extras</groupId>
      <artifactId> glassfish-embedded-all </artifactId>
      <version>4.0</version>
      <scope>provided</scope>
    </dependency>
 
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
 
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.5.1</version>
        <configuration>
          <source> 1.7 </source>
          <target>1.7</target>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.2</version>
        <configuration>
          <failOnMissingWebXml>false</failOnMissingWebXml>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId> maven-failsafe-plugin </artifactId>
        <version>2.12.4</version>
        <executions>
          <execution>
            <id>integration-test</id>
            <goals>
              <goal> integration-test </goal>
              <goal>verify</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

To compile and package the classes, open a command line in the root directory containing the pom.xml file and enter the following Maven command:

$ mvn package

Go to the target directory, look for a file named chapter15-service-1.0.war, and open it. Notice that Book.class, Books.class, ApplicationConfig.class, and BookRestService.class are all under the WEB-INFclasses directory. The persistence.xml file is also packaged in the war file.

Deploying on GlassFish

Once the code is packaged, make sure GlassFish and Derby are up and running and deploy the war file by issuing the asadmin command-line interface. Open a console, go to the target directory where the chapter15-service-1.0.war file is located, and enter:

$ asadmin deploy chapter15-service-1.0.war

If the deployment is successful, the following command should return the name of the deployed component and its type:

$ asadmin list-components
chapter15-service-1.0 <ejb, web>

Now that the application is deployed, you can use cURL in a command line to create book resources by sending POST requests and get all or a specific resource with GET requests. DELETE will remove book resources.

WADL

I introduced the WADL (Web Application Description Language) at the beginning of the chapter saying that it wasn’t standardized and not very much used in RESTful architecture. But if you want to have a look at what it could look like for our BookRestService RESTful web service, check the following URL: http://localhost/8080/chapter15-service-1.0/rs/application.wadl. Listing 15-29 shows an abstract of this WADL.

Listing 15-29.  Extract of the WADL Generated by GlassFish for the BookRestService RESTful web service

<application xmlns=" http://wadl.dev.java.net/2009/02 ">
  <resources base=" http://localhost:8080/chapter15-service-1.0/rs/ ">
    <resource path=" /book ">
      <method id=" POST " name="POST">
        <request>
          <representation element="book" mediaType="application/xml"/>
          <representation element="book" mediaType="application/json"/>
        </request>
      </method>
      <resource path=" {id} ">
        <param name="id" style="template" type="xs:string"/>
        <method id=" GET{id} " name="GET">
          <response>
            <representation mediaType="application/xml"/>
            <representation mediaType="application/json"/>
          </response>
        </method>
        <method id=" DELETE{id} " name="DELETE"/>
      </resource>
    </resource>
    ...
  </resources>
</application>

The WADL in Listing 15-29 describes the root path (http://localhost:8080/chapter15-service-1.0/rs/) and all the subpaths available in the RESTful service (/book and {id}). It also gives you the HTTP method you can invoke (POST, GET, DELETE . . .).

Writing the BookRestServiceIT Integration Test

Now that the code is packaged and deployed into GlassFish we can write an integration test that will make HTTP requests to the RESTful web service using the new JAX-RS 2.0 Client API. Integration tests are different from unit tests because they don’t test your code in isolation, they need all the containers services. Typically, if GlassFish and Derby are not up and running, the code in Listing 15-30 will not work.

The two first methods test failures. shouldNotCreateANullBook makes sure you cannot create a book with a null Book object. So it posts a null entity and expects a 400-Bad Request. The shouldNotFindTheBookID test case passes an unknown book id and expects a 404-Not Found.

The shouldCreateAndDeleteABook test case is a bit more complex as it invokes several operations. First, it posts an XML representation of a Book object and makes sure the status code is 201-Created. The bookURI variable is the URI of the newly created book. The test case uses this URI to request the new book, then reads the message body, casts it to a Book class (book = response.readEntity(Book.class)) and asserts that the values are correct. Then a DELETE invocation deletes the book from the database and checks the response status code is 204-No Content. A last GET on the resource makes sure it has been deleted by checking the 404-Not Found status code.

Listing 15-30.  The ApplicationConfig Class Declaring the /rs URL Pattern

public class BookRestServiceIT {
 
  private static URI uri = UriBuilder.
               fromUri("http://localhost/chapter15-service-1.0/rs/book").port(8080).build ();
  private static Client client = ClientBuilder.newClient();
  
  @Test
  public void shouldNotCreateANullBook() throws JAXBException {
 
    // POSTs a Null Book
    Response response = client.target(uri).request(). post (Entity.entity( null , →
                                                          MediaType.APPLICATION_XML));
    assertEquals(Response.Status. BAD_REQUEST , response.getStatusInfo());
  }
 
  @Test
  public void shouldNotFindTheBookID() throws JAXBException {
 
    // GETs a Book with an unknown ID
    Response response = client.target(uri).path(" unknownID ").request(). get ();
    assertEquals(Response.Status. NOT_FOUND , response.getStatusInfo());
  }
 
  @Test
  public void shouldCreateAndDeleteABook() throws JAXBException {
 
    Book book = new Book("H2G2", 12.5F, "Science book", "1-84023-742-2", 354, false);
 
    // POSTs a Book
    Response response = client.target(uri).request(). post (Entity.entity( book , →
                                                          MediaType.APPLICATION_XML));
    assertEquals( Response.Status.CREATED , response.getStatusInfo());
    URI bookURI = response.getLocation() ;
 
    // With the location, GETs the Book
    response = client.target( bookURI ).request(). get ();
    book = response. readEntity (Book.class);
    assertEquals(Response.Status.OK, response.getStatusInfo());
    assertEquals("H2G2", book.getTitle());
 
    // Gets the book id and DELETEs it
    String bookId = bookURI.toString().split("/")[6];
    response = client.target(uri).path(bookId).request(). delete ();
    assertEquals(Response.Status. NO_CONTENT , response.getStatusInfo());
 
    // GETs the Book and checks it has been deleted
    response = client.target(bookURI).request(). get ();
    assertEquals(Response.Status. NOT_FOUND , response.getStatusInfo());
 
  }
}

Make sure GlassFish and Derby are up and running, that the application is deployed, and execute this integration test with the Maven Failsafe plugin by entering the following Maven command:

$ mvn failsafe:integration-test