Chapter 47. Returning Information to the Consumer

Abstract

RESTful requests require that at least an HTTP response code be returned to the consumer. In many cases, a request can be satisfied by returning a plain JAXB object or a GenericEntity object. When the resource method needs to return additional metadata along with the response entity, JAX-RS resource methods can return a Response object containing any needed HTTP headers or other metadata.

47.1. Return Types

The information returned to the consumer determines the exact type of object a resource method returns. This may seem obvious, but the mapping between Java return objects and what is returned to a RESTful consumer is not one-to-one. At a minimum, RESTful consumers need to be returned a valid HTTP return code in addition to any response entity body. The mapping of the data contained within a Java object to a response entity is effected by the MIME types a consumer is willing to accept.
To address the issues involved in mapping Java object to RESTful response messages, resource methods are allowed to return four types of Java constructs:
  • common Java types return basic information with HTTP return codes determined by the JAX-RS runtime.
  • JAXB objects return complex information with HTTP return codes determined by the JAX-RS runtime.
  • JAX-RS return complex information with a programmatically determined HTTP return status. The Response object also allows HTTP headers to be specified.
  • JAX-RS return complex information with HTTP return codes determined by the JAX-RS runtime. The GenericEnitity object provides more information to the runtime components serializing the data.