Fuse ESB - Developing RESTful Web Services - Basics of building responses

Basics of building responses

Overview

RESTful services often need more precise control over the response returned to a consumer than is allowed when a resource method returns a plain Java construct. The JAX-RS Response class allows a resource method to have some control over the return status sent to the consumer and to specify HTTP message headers and cookies in the response.

Response objects wrap the object representing the entity that is returned to the consumer. Response objects are instantiated using the ResponseBuilder class as a factory.

The ResponseBuilder class also has many of the methods used to manipulate the response's metadata. For instance the ResonseBuilder class contains the methods for setting HTTP headers and cache control directives.

Relationship between a response and a response builder

The Response class has a protected constructor, so they cannot be instantiated directly. They are created using the ResponseBuilder class enclosed by the Response class. The ResponseBuilder class is a holder for all of the information that will be encapsulated in the response created from it. The ResponseBuilder class also has all of the methods responsible for setting HTTP header properties on the message.

The Response class does provide some methods that ease setting the proper response code and wrapping the entity. There are methods for each of the common response status codes. The methods corresponding to status that include an entity body, or required metadata, include versions that allow for directly setting the information into the associated response builder.

The ResponseBuilder class' build() method returns a response object containing the information stored in the response builder at the time the method is invoked. After the response object is returned, the response builder is returned to a clean state.

Getting a response builder

There are two ways to get a response builder:

Using the static methods of the Response class as shown in Example 21.
Example 21. Getting a response builder using the Response class
```
import javax.ws.rs.core.Response;

Response r = Response.ok().build();
```
When getting a response builder this way you do not get access to an instance you can manipulate in multiple steps. You must string all of the actions into a single method call.
Using the Apache CXF specific ResponseBuilderImpl class. This class allows you to work directly with a response builder. However, it requires that you manually set all of the response builders information manually.
Example 22 shows how Example 21 could be rewritten using the ResponseBuilderImpl class.
Example 22. Getting a response builder using the ResponseBuilderImpl class
```
import javax.ws.rs.core.Response;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.status(200);
Response r = builder.build();
```
Tip
You could also simply assign the ResponseBuilder returned from a Response class' method to a ResponseBuilderImpl object.

More information

For more information about the Response class see the Response class' Javadoc.

For more information about the ResponseBuilder class see the ResponseBuilder class' Javadoc.

For more information on the Apache CXF ResponseBuilderIml class see the ResponseBuilderImpl Javadoc.

Comments powered by Disqus