RESTful Java with JAX-RS 2.0 (2013)

Complex Responses

Sometimes the web service you are writing can’t be implemented using the default request/response behavior inherent in JAX-RS. For the cases in which you need to explicitly control the response sent back to the client, your JAX-RS resource methods can return instances ofjavax.ws.rs.core.Response:

public abstract class Response {

public abstract Object getEntity();

public abstract int getStatus();

public abstract MultivaluedMap<String, Object> getMetadata();

...

}

The Response class is an abstract class that contains three simple methods. The getEntity() method returns the Java object you want converted into an HTTP message body. The getStatus() method returns the HTTP response code. The getMetadata() method is aMultivaluedMap of response headers.

Response objects cannot be created directly; instead, they are created from javax.ws.rs.core.Response.ResponseBuilder instances returned by one of the static helper methods of Response:

public abstract class Response {

...

public static ResponseBuilder status(Status status) {...}

public static ResponseBuilder status(int status) {...}

public static ResponseBuilder ok() {...}

public static ResponseBuilder ok(Object entity) {...}

public static ResponseBuilder ok(Object entity, MediaType type) {...}

public static ResponseBuilder ok(Object entity, String type) {...}

public static ResponseBuilder ok(Object entity, Variant var) {...}

public static ResponseBuilder serverError() {...}

public static ResponseBuilder created(URI location) {...}

public static ResponseBuilder noContent() {...}

public static ResponseBuilder notModified() {...}

public static ResponseBuilder notModified(EntityTag tag) {...}

public static ResponseBuilder notModified(String tag) {...}

public static ResponseBuilder seeOther(URI location) {...}

public static ResponseBuilder temporaryRedirect(URI location) {...}

public static ResponseBuilder notAcceptable(List<Variant> variants) {...}

public static ResponseBuilder fromResponse(Response response) {...}

...

}

If you want an explanation of each and every static helper method, the JAX-RS Javadocs are a great place to look. They generally center on the most common use cases for creating custom responses. For example:

public static ResponseBuilder ok(Object entity, MediaType type) {...}

The ok() method here takes the Java object you want converted into an HTTP response and the Content-Type of that response. It returns a preinitialized ResponseBuilder with a status code of 200, “OK.” The other helper methods work in a similar way, setting appropriate response codes and sometimes setting up response headers automatically.

The ResponseBuilder class is a factory that is used to create one individual Response instance. You store up state you want to use to create your response and when you’re finished, you have the builder instantiate the Response:

public static abstract class ResponseBuilder {

public abstract Response build();

public abstract ResponseBuilder clone();

public abstract ResponseBuilder status(int status);

public ResponseBuilder status(Status status) {...}

public abstract ResponseBuilder entity(Object entity);

public abstract ResponseBuilder type(MediaType type);

public abstract ResponseBuilder type(String type);

public abstract ResponseBuilder variant(Variant variant);

public abstract ResponseBuilder variants(List<Variant> variants);

public abstract ResponseBuilder language(String language);

public abstract ResponseBuilder language(Locale language);

public abstract ResponseBuilder location(URI location);

public abstract ResponseBuilder contentLocation(URI location);

public abstract ResponseBuilder tag(EntityTag tag);

public abstract ResponseBuilder tag(String tag);

public abstract ResponseBuilder lastModified(Date lastModified);

public abstract ResponseBuilder cacheControl(CacheControl cacheControl);

public abstract ResponseBuilder expires(Date expires);

public abstract ResponseBuilder header(String name, Object value);

public abstract ResponseBuilder cookie(NewCookie... cookies);

}

As you can see, ResponseBuilder has a lot of helper methods for initializing various response headers. I don’t want to bore you with all the details, so check out the JAX-RS Javadocs for an explanation of each one. I’ll be giving examples using many of them throughout the rest of this book.

Now that we have a rough idea about creating custom responses, let’s look at an example of a JAX-RS resource method setting some specific response headers:

@Path("/textbook")

public class TextBookService {

@GET

@Path("/restfuljava")

@Produces("text/plain")

public Response getBook() {

String book = ...;

ResponseBuilder builder = Response.ok(book);

builder.language("fr")

.header("Some-Header", "some value");

return builder.build();

}

}

Here, our getBook() method is returning a plain-text string that represents a book our client is interested in. We initialize the response body using the Response.ok() method. The status code of the ResponseBuilder is automatically initialized with 200. Using theResponseBuilder.language() method, we then set the Content-Language header to French. We then use the ResponseBuilder.header() method to set a custom response header. Finally, we create and return the Response object using the ResponseBuilder.build()method.

One interesting thing to note about this code is that we never set the Content-Type of the response. Because we have already specified an @Produces annotation, the JAX-RS runtime will set the media type of the response for us.