Server Responses and Exception Handling - RESTful Java with JAX-RS 2.0 - page 103

of HTTP methods the URI supports. So, if our client did a GET /customers in our example,
the server would send this response back:

HTTP / 1.1 405 , Method Not Allowed
Allow: POST

The exception to this rule is the HTTP HEAD and OPTIONS methods. If a JAX-RS resource
method isn't available that can service HEAD requests for that particular URI, but there does
exist a method that can handle GET, JAX-RS will invoke the JAX-RS resource method that
handles GET and return the response from that minus the request body. If there is no existing
method that can handle OPTIONS, the JAX-RS implementation is required to send back
some meaningful, automatically generated response along with the Allow header set.

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 of
javax.ws.rs.core.Response :

public public abstract abstract class class Response Response {

public public abstract abstract Object getEntity ();

public public abstract abstract int int getStatus ();

public public abstract 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 a MultivaluedMap 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 public abstract abstract class class Response Response {

...

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

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

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

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