46.4. Parsing Requests and Responses
Overview
An essential aspect of making HTTP invocations is that the client must be able to parse the outgoing request messages and the incoming responses. In JAX-RS 2.0, the key concept is the
Entity class, which represents a raw message tagged with a media type. In order to parse the raw message, you can register multiple entity providers, which have the capability to convert media types to and from particular Java types.
In other words, in the context of JAX-RS 2.0, an
Entity is the representation of a raw message and an entity provider is the plug-in that provides the capability to parse the raw message (based on the media type).
Entities
An
Entity is a message body augmented by metadata (media type, language, and encoding). An Entity instance holds the message in a raw format and is associated with a specific media type. To convert the contents of an Entity object to a Java object you require an entity provider, which is capable of mapping the given media type to the required Java type.
Variants
A
javax.ws.rs.core.Variant object encapsulates the metadata associated with an Entity, as follows:
- Media type,
- Language,
- Encoding.
Effectively, you can think of an
Entity as consisting of the HTTP message contents, augmented by Variant metadata.
Entity providers
An entity provider is a class that provides the capability of mapping between a media type and a Java type. Effectively, you can think of an entity provider as a class that provides the ability to parse messages of a particular media type (or possibly of multiple media types). There are two different varieties of entity provider:
MessageBodyReader- Provides the capability of mapping from media type(s) to a Java type.
MessageBodyWriter- Provides the capability of mapping from a Java type to a media type.
Standard entity providers
Entity providers for the following Java and media type combinations are provided as standard:
byte[]- All media types (
*/*). java.lang.String- All media types (
*/*). java.io.InputStream- All media types (
*/*). java.io.Reader- All media types (
*/*). java.io.File- All media types (
*/*). javax.activation.DataSource- All media types (
*/*). javax.xml.transform.Source- XML types (
text/xml,application/xml, and media types of the formapplication/*+xml). javax.xml.bind.JAXBElementand application-supplied JAXB classes- XML types (
text/xml,application/xml, and media types of the formapplication/*+xml). MultivaluedMap<String,String>- Form content (
application/x-www-form-urlencoded). StreamingOutput- All media types (
*/*),MessageBodyWriteronly. java.lang.Boolean,java.lang.Character,java.lang.Number- Only for
text/plain. Corresponding primitive types supported through boxing/unboxing conversion.
Response object
The default return type is the
javax.ws.rs.core.Response type, which represents an untyped response. The Response object provides access to the complete HTTP response, including the message body, HTTP status, HTTP headers, media type, and so on.
Accessing the response status
You can access the response status, either through the
getStatus method (which returns the HTTP status code):
int status = resp.getStatus();
Or though the
getStatusInfo method, which also provides a description string:
String statusReason = resp.getStatusInfo().getReasonPhrase();
Accessing the returned headers
You can access the HTTP headers using any of the following methods:
MultivaluedMap<String,Object> getHeaders() MultivaluedMap<String,String> getStringHeaders() String getHeaderString(String name)
For example, if you know that the
Response has a Date header, you could access it as follows:
String dateAsString = resp.getHeaderString("Date");Accessing the returned cookies
You can access any new cookies set on the
Response using the getCookies method, as follows:
import javax.ws.rs.core.NewCookie; ... java.util.Map<String,NewCookie> cookieMap = resp.getCookies(); java.util.Collection<NewCookie> cookieCollection = cookieMap.values();
Accessing the returned message content
You can access the returned message content by invoking one of the
readEntity methods on the Response object. The readEntity method automatically invokes the available entity providers to convert the message to the requested type (specified as the first argument of readEntity). For example, to access the message content as a String type:
String messageBody = resp.readEntity(String.class);
Collection return value
If you need to access the returned message as a Java generic type—for example, as a
List or Collection type—you can specify the request message type using the javax.ws.rs.core.GenericType<T> construction. For example:
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Client;
import javax.ws.rs.core.GenericType;
import java.util.List;
...
GenericType<List<String>> stringListType = new GenericType<List<String>>() {};
Client client = ClientBuilder.newClient();
List<String> bookNames = client.target("http://example.org/bookstore/booknames")
.request("text/plain")
.get(stringListType);