The Response class has several static methods that create and return a ResponseBuilder object.

To create an OK response, with HTTP Response code of 200, we can invoke the ok() method. We can also supply an entity of the response with the entity() method, which specifies the payload to send back to the client. We can set the MIME content of the entity too.

After configuring the ResponseBuilder, we then need to actually construct a response, which is sent to the client, by calling the build() method.

The following code shows a sample class that demonstrates some of the ways to build generic response outputs programmatically:

package je7hb.jaxrs.basic;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

public class SampleResponse {
  public Response generateSimpleOk() {
    return Response.ok().build();
  }

  public Response generateSimpleOkWithEntity() {
    return Response.ok().entity("This is message")
    .type(MediaType.TEXT_PLAIN_TYPE).build();
  }

  public Response generateSimpleOkWithEntityXml() {
    return Response.ok().entity("<msg>This ismessage</msg>")
    .type(MediaType.TEXT_XML_TYPE).build();
  }

  public Response generateSimpleOkWithGermanyLang() {
    return Response.ok()
    .language(„de_de")
    .entity(„<msg>Einfaches boetschaft</msg>")
    .type(MediaType.TEXT_XML_TYPE).build();
  }

  public Response generateUnauthorisedError() {
    return Response.status(Response.Status.UNAUTHORIZED)
      .build();
  }


  public Response generateUnauthorisedWithEntityXml() {
    return Response.status(Response.Status.UNAUTHORIZED)
    .entity("<msg>Unauthorised</msg>")
    .type(MediaType.TEXT_XML_TYPE).build();
  }
}

In the SampleResponse class, we just saw, to avoid subtle literal string errors, note how we make use of the javax.ws.rs.core.MediaType. Static definitions of this class are used to set the MIME content as an argument to the response builder's type() method.

It is also possible to set the language and the character encoding of the response with methods language() and encoding(). Although not shown here, ResponseBuilder does have more additional methods in order to configure response headers, last modification date, expiration date and time, new cookies, and links for purpose of URI redirection.

MediaType class defines static constants, such as APPLICATION_JSON_TYPE, TEXT_PLAIN_TYPE, and TEXT_HTMLTYPE. The class also defines String equivalents of these, such as APPLICATION_JSON ("application/json"), TEXT_PLAIN ("text/plain"), and TEXT_HTML ("text/html").

This, then, is useful for setting the value @Produces and @Consumes in JAX-RS resource methods. For instance, we can write the code in the following way:

  @GET
  @Produces(MediaType.TEXT_PLAIN)
  public String getList() { /* ...*/
  return buf.toString();
}

The class javax.ws.js.core.Response.Status defines a set of enumeration values that correspond to the response code in the HTTP 1.1 communication standard. Refer to the following table:

ResponseBuilder has several helpful functions to build a response. The Response object is supported in both server and client JAX-RS APIs. Users are encouraged to take advantage of the strong type safety by referencing static constants in Java class rather than loose literal strings.

Since Java has generics, how does JAX-RS take care of parameterized collection types? The answer is the runtime requires some help, because of type erasure.

In order to inform the runtime about a generic collection, there is a class, which developers can use, called javax.ws.rs.core.GenericEntity.

The following code shows a REST style planning resource that illustrates how to return a generic collection to the client.

@Plan("plans")
public PlanningResource {
  @Path("{id}")
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public Response getPlanList( @PathParam("id") String id ) {
    List<Plan> plans = findPlanCollectionById(id);
    Collections.sort( plans new AscendingDateOrderComparator() );
    GenericEntity entity = new GenericEntity<List<Plan>>(plans);
    return Response.ok(entity).build();
  }
}

The PlanningResource class has a resource method getPlanList(), which retrieves a list of business plans from a persistence store in the application. It sorts these Plan objects into ascending order and then wraps the list collections of plans in a GenericEntity. The method returns a response with the generic entity.

After the resource method returns the entity, the JAX-RS runtime will then take care of the rest of the response processing. The runtime applies a converter, if it was registered, to map each Plan entity object into the required media type "application/json" and the assembled response is sent over the wire to the client.

Resource methods are allowed to return void, Response, GenericEntity, or another Java type. These return types are mapped to the response sent to the client.

It is the responsibility of the developer to supply additional converters beyond the JAX-RS standard. They may do so through the @Provider annotation in order to register custom filters and entity interceptors.

Hypermedia linking is the ability for REST services to explicitly reference other endpoints in order to allow a client to navigate information. This capability is actually a constraint of fully REST application architecture and the term for it is Hypermedia as the Engine of Application State (HATEOS). The design of HATEOS system implies that a REST client requires only basic knowledge to interact with an application. The best way to understand this is to think of hyperlinks in HTML. A web browser knows that an HTML anchor element is a navigation point to another HTTP resource. If a user clicks on an anchor, this is instruction to surf to the next web page. The engine of application state for a web browser is the uniform access rule to a spider web of Internet HTTP servers. No special protocols are required beyond the norm.

JAX-RS 2.0 supports Hypermedia by allowing a RESTful server endpoint to add special linkage information to the headers of a HTTP Response. The information in the HTTP header is separate to the actual content. So the response can be anything such as JSON or XML or byte stream and the developer can add linkage information to it.

The class javax.ws.rs.core.Response.ResponseBuilder has a couple of methods link() and links(). These methods create instances of javax.ws.rs.core.Link, which is the class that encapsulates hypermedia links. A link() accepts a URI that references the target resource and parameter. A parameter is a relative name for the navigation link called rel or it can be code.

Link relations are descriptive attributes that associated with hyperlink and define the semantic meaning of the relationship between the source and destination resources. Link relations are used in HTML5 as the common cascading style sheet. The following line of code shows the same:

<link href="stylesheets/bootstrap.css" rel="stylesheet" />

In REST and JAX-RS 2.0 the rel parameter is retained in a hypermedia link. The Link class adds a title, type, and optional of map of key-value parameters.

To understand better, let's adapt the book RESTful endpoint with hypermedia links. We will start with a refactored class as shown in the following code:

@Path("/hyperbooks")
public class RestfulBookServiceWithHypermedia {
  private List<HyperBook> products = Arrays.asList(
    new HyperBook(101,"Sir Arthur Dolan Coyle","Sherlock Holmes and the Hounds of the Baskervilles"),
    new HyperBook(102,"Dan Brown","Da Vinci Code"),
    new HyperBook(103,"Charles Dickens","Great Expectations"),
    new HyperBook(104,"Robert Louis Stevenson","Treasure Island"));
  private final JsonBuilderFactory factory;

  public RestfulBookServiceWithHypermedia() {
    factory = Json.createBuilderFactory(null);
  }

  @GET
  @Path("{id}")
  @Produces({"application/json"})
  public Response getProduct(@PathParam("id")int id) {
    HyperBook product = null;
    for ( HyperBook book: products ) {
      if ( book.id == id ) {
        product = book; break;
      }
    }
    if ( product == null)
    throw new RuntimeException("book not found");
    return Response.ok(product.asJsonObject())
    .link("http://localhost:8080/order/"+id+"/warehouse", "stock")
    .build();
  }
  // ...
}

In this endpoint RestfulBookServiceWithHypermedia, we changed the URI from /books to /hypermedia for the type in order to avoid a conflict between resources. This class creates JsonBuilderFactory that we use later. We have given all the hypermedia books a new Java type HyperBook and they have a unique ID.

The method getProduct() maps to HTTP GET request and accepts a REST path parameter ID, which references the bookID. The code attempts to look up the product by the ID. If the product does exists, we convert the Hyperbook instance to a JSON representation with call to asJsonObject(). We use the JSON-P API from Java EE 7 (See Appendix D, Java EE 7 Assorted Topics for more details).

If it is not found in the list, then a RuntimeException exception is thrown. The key to the method is link() call that accepts an URI for the link header and a value for the rel parameter. The method generates a response header that looks like the following code:

header[Link] = <http://localhost:8080/order/101/warehouse>;
 rel="stock"
header[Date] = Sun, 18 Aug 2013 17:38:33 GMT
header[Content-Length] = 105
header[Content-Type] = application/json

The link relation is a navigation to a warehouse note on a particular order that has a rel name stock and the URI http://localhost:8080/order/101/warehouse. It is also possible to generate a collection of link headers for a given response. In order to achieve this aim, we need to invoke indirectly Link.Builder class.

Let's add one method to retrieve all the hypermedia books in our endpoint, the following code will explain how to do just that:

@GET
@Produces({"application/json"})
public Response getProductList() {
  JsonObjectBuilder builder = factory.createObjectBuilder();
  JsonArrayBuilder arrayBuilder = factory.createArrayBuilder();

  List<Link> links = new ArrayList<>();
  for ( HyperBook book: products ) {
    arrayBuilder.add( book.asJsonObject() );
    links.add(
      Link.fromPath("http://localhost:8080/order/" +book.id + "/warehouse")
      .rel("stock")
      .build());
  }
  builder.add("products", arrayBuilder.build());

  return Response.ok(builder.build())
  .links( links.toArray( new Link[]{}))
  build();
}

The method getProducts() maps also HTTP GET request, but without any parameter and returns a JSON array of all products, the hypermedia books. In order to create a collection of link relations, we use ArrayList<Link>.

For each hypermedia product, we iterate over all of them, we need a link relation builder. The static call Link.fromPath() instantiates a Link.Builder instance from a String. From there, we set rel parameter name using the rel() method and then obtain a Link instance by calling build().

At the same time when we are creating link relations, we create a JsonArray object. We obtain the JSON representation of the Hyperbook instance and add it to the JsonArray. The final part of the puzzle is, while building the response, the conversion of the ArrayList<List> to the Link[] primitive array for the links(Links… ) call.

The output for the HTTP Response headers looks something like this:

header[Link] = 
 <http://localhost:8080/ordering/104/shipment>; rel="ship",
 <http://localhost:8080/ordering/103/shipment>; rel="ship",
 <http://localhost:8080/ordering/102/shipment>; rel="ship",
 <http://localhost:8080/ordering/101/shipment>; rel="ship"
 header[Date] = Mon, 19 Aug 2013 08:26:01 GMT
 header[Content-Length] = 314
 header[Content-Type] = application/json

As you can observe the Links HTTP response is actually comma-delimited. The client-side JAX-RS 2.0 delivers this view resembles the following code extract:

@Test
public void shouldRetrieveHyperbooks() throws Exception {
  WebTarget target = ClientBuilder.newClient()
  .target(
    "http://localhost:8080/mywebapp/rest/hyperbooks");
  Response response = target.request().get();
  // ...
  Set<Link> links = response.getLinks();
  assertFalse(links.isEmpty());
  for (Link link: links) {
    System.out.printf("link relation uri=%s, rel=%s 
",link.getUri(), link.getRel());
  }
  assertEquals(200, response.getStatus());
}

From the unit test method shouldRetrieveHyperbooks(), we are using the JAX-RS 2.0 client side API that we will discuss, very soon, in the section. The important point in the code is retrieval of Link in a Set collection from the response. The client side can conveniently parse that set of link relations in the instance, which is very useful. From there, we can get access to the URI, parameter rel name, the type, and other parameters.

The output should appear as the following:

link relation uri=http://localhost:8080/ordering/103/shipment,rel=ship 
link relation uri=http://localhost:8080/ordering/102/shipment,rel=ship

This covers building a response. Let's now move to the client side.