Red Hat Training

A Red Hat training course is available for Red Hat Fuse

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.
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.

47.1. Returning plain Java constructs

Overview

In many cases a resource class can return a standard Java type, a JAXB object, or any object for which the application has an entity provider. In these cases the runtime determines the MIME type information using the Java class of the object being returned. The runtime also determines the appropriate HTTP return code to send to the consumer.

Returnable types

Resource methods can return void or any Java type for which an entity writer is provided. By default, the runtime has providers for the following:
  • the Java primitives
  • the Number representations of the Java primitives
  • JAXB objects
the section called “Natively supported types” lists all of the return types supported by default. the section called “Custom writers” describes how to implement a custom entity writer.

MIME types

The runtime determines the MIME type of the returned entity by first checking the resource method and resource class for a @Produces annotation. If it finds one, it uses the MIME type specified in the annotation. If it does not find one specified by the resource implementation, it relies on the entity providers to determine the proper MIME type.
By default the runtime assign MIME types as follows:
  • Java primitives and their Number representations are assigned a MIME type of application/octet-stream.
  • JAXB objects are assigned a MIME type of application/xml.
Applications can use other mappings by implementing custom entity providers as described in the section called “Custom writers”.

Response codes

When resource methods return plain Java constructs, the runtime automatically sets the response's status code if the resource method completes without throwing an exception. The status code is set as follows:
  • 204(No Content)—the resource method's return type is void
  • 204(No Content)—the value of the returned entity is null
  • 200(OK)—the value of the returned entity is not null
If an exception is thrown before the resource method completes the return status code is set as described in Chapter 48, Handling Exceptions.