javax.ws.rs.core
Class Response

java.lang.Object
  javax.ws.rs.core.Response

public abstract class Response
extends Object

Defines the contract between a returned instance and the runtime when an application needs to provide meta-data to the runtime. An application class can extend this class directly or can use one of the static methods to create an instance using a ResponseBuilder.

Several methods have parameters of type URI, UriBuilder provides convenient methods to create such values as does URI.create(java.lang.String).

Since:

1.0

Author:

Paul Sandoz, Marc Hadley, Marek Potociar

See Also:

Response.ResponseBuilder

Nested Class Summary

static class	Response.ResponseBuilder A class used to build Response instances that contain metadata instead of or in addition to an entity.
static class	Response.Status Commonly used status codes defined by HTTP, see HTTP/1.1 documentation for the complete list.
static interface	Response.StatusType Base interface for statuses used in responses.

Constructor Summary

protected

Response() Protected constructor, use one of the static methods to obtain a Response.ResponseBuilder instance and obtain a Response from that.

Method Summary

abstract void	bufferEntity() Buffer the message entity.
abstract void	close() Close the message entity input stream (if available and open).
static Response.ResponseBuilder	created(URI location) Create a new ResponseBuilder for a created resource, set the location header using the supplied value.
static Response.ResponseBuilder	fromResponse(Response response) Create a new ResponseBuilder by performing a shallow copy of an existing Response.
abstract Object	getEntity() Get the message entity Java instance.
abstract ResponseHeaders	getHeaders() Get the response message headers.
abstract MultivaluedMap<String,Object>	getMetadata() Get metadata (headers) associated with the response as a map.
abstract Map<String,Object>	getProperties() Get a mutable map of request-scoped properties that can be used for communication between different request/response processing components.
abstract int	getStatus() Get the status code associated with the response.
abstract Response.Status	getStatusEnum() Get the response status represented as a response Response.Status enumeration value.
abstract boolean	hasEntity() Check if there is an entity available in the response.
abstract boolean	isEntityRetrievable() Check if the entity instance is present and available for a retrieval via getEntity().
static Response.ResponseBuilder	noContent() Create a new ResponseBuilder for an empty response.
static Response.ResponseBuilder	notAcceptable(List<Variant> variants) Create a new ResponseBuilder for a not acceptable response.
static Response.ResponseBuilder	notModified() Create a new ResponseBuilder with a not-modified status.
static Response.ResponseBuilder	notModified(EntityTag tag) Create a new ResponseBuilder with a not-modified status.
static Response.ResponseBuilder	notModified(String tag) Create a new ResponseBuilder with a not-modified status and a strong entity tag.
static Response.ResponseBuilder	ok() Create a new ResponseBuilder with an OK status.
static Response.ResponseBuilder	ok(Object entity) Create a new ResponseBuilder that contains a representation.
static Response.ResponseBuilder	ok(Object entity, MediaType type) Create a new ResponseBuilder that contains a representation.
static Response.ResponseBuilder	ok(Object entity, String type) Create a new ResponseBuilder that contains a representation.
static Response.ResponseBuilder	ok(Object entity, Variant variant) Create a new ResponseBuilder that contains a representation.
abstract <T> T	readEntity(Class<T> type) Read the message entity as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
abstract <T> T	readEntity(Class<T> type, Annotation[] annotations) Read the message entity as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
abstract <T> T	readEntity(TypeLiteral<T> entityType) Read the message entity as an instance of specified (generic) Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
abstract <T> T	readEntity(TypeLiteral<T> entityType, Annotation[] annotations) Read the message entity as an instance of specified (generic) Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
static Response.ResponseBuilder	seeOther(URI location) Create a new ResponseBuilder for a redirection.
static Response.ResponseBuilder	serverError() Create a new ResponseBuilder with an server error status.
static Response.ResponseBuilder	status(int status) Create a new ResponseBuilder with the supplied status.
static Response.ResponseBuilder	status(Response.Status status) Create a new ResponseBuilder with the supplied status.
static Response.ResponseBuilder	status(Response.StatusType status) Create a new ResponseBuilder with the supplied status.
static Response.ResponseBuilder	temporaryRedirect(URI location) Create a new ResponseBuilder for a temporary redirection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Response

protected Response()

Protected constructor, use one of the static methods to obtain a Response.ResponseBuilder instance and obtain a Response from that.

Method Detail

getProperties

public abstract Map<String,Object> getProperties()

Get a mutable map of request-scoped properties that can be used for communication between different request/response processing components. May be empty, but MUST never be null. In the scope of a single request/response processing, a same property map instance is shared by the following methods:

• Request.getProperties()
• getProperties()
• FilterContext.getProperties()
• InterceptorContext.getProperties()

A request-scoped property is an application-defined property that may be added, removed or modified by any of the components (user, filter, interceptor etc.) that participate in a given request/response processing flow.

On the client side, this property map is initialized by calling Configuration.setProperties(java.util.Map) or Configuration.setProperty(java.lang.String, java.lang.Object) on the configuration object associated with the corresponding request invocation.

On the server side, specifying the initial values is implementation-specific.

If there are no initial properties set, the request-scoped property map is initialized to an empty map.

Returns:

a mutable request-scoped property map.

Since:

2.0

See Also:

Configuration

getStatus

public abstract int getStatus()

Get the status code associated with the response.

Returns:

the response status code or -1 if the status was not set.

getStatusEnum

public abstract Response.Status getStatusEnum()

Get the response status represented as a response Response.Status enumeration value.

Returns:

the status type instance, or null if there is no mapping between the integer status code and the response status enumeration value.

Since:

2.0

getHeaders

public abstract ResponseHeaders getHeaders()

Get the response message headers. This method never returns null.

Returns:

response message headers. Returned headers may be empty but never null.

Since:

2.0

See Also:

RuntimeDelegate.HeaderDelegate

getEntity

public abstract Object getEntity()
                          throws IllegalStateException,
                                 MessageProcessingException

Get the message entity Java instance. Returns null if the message does not contain an entity body.

Returns:

the message entity or null if message does not contain an entity body.

Throws:

IllegalStateException - in case the existing message entity is not retrievable as a Java type. This is typically the case (on the client side) when the entity input stream has not been read as a Java type using one of the readEntity(...) methods yet.

MessageProcessingException - if the entity was previously fully consumed as an input stream.

See Also:

hasEntity(), isEntityRetrievable(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.TypeLiteral), bufferEntity(), MessageBodyWriter

readEntity

public abstract <T> T readEntity(Class<T> type)
                      throws MessageProcessingException

Read the message entity as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Returns null if the message does not contain an entity body. Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream (if open) and makes the entity available for retrieval.

A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). If the message has previously been read as an instance of a different Java type, invoking this method will cause the cached entity instance to be serialized into a temporary input stream using a compatible MessageBodyWriter and then read again from the stream. This operation is thus potentially expensive and should be used with care.

Note that a message entity can also be read as a raw entity input stream, in which case it will be fully consumed once the reading from the entity input stream is finished. Once the entity is read as an input stream, any subsequent calls to one of the readEntity(...) methods or getEntity() method on the same message instance will result in a MessageProcessingException being thrown. It is up to the consumer of the entity input stream to ensure that consuming the stream is properly mitigated (e.g. by substituting the consumed response instance with a new one etc.).

Type Parameters:

T - entity instance Java type.

Parameters:

type - the type of entity.

Returns:

the message entity or null if message does not contain an entity body.

Throws:

MessageProcessingException - if the content of the message cannot be mapped to an entity of the requested type or if the entity input stream was previously directly consumed by invoking readEntity(InputStream.class).

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(java.lang.Class, java.lang.annotation.Annotation[]), readEntity(javax.ws.rs.core.TypeLiteral), readEntity(javax.ws.rs.core.TypeLiteral, java.lang.annotation.Annotation[]), bufferEntity(), close(), MessageBodyWriter, MessageBodyReader

readEntity

public abstract <T> T readEntity(TypeLiteral<T> entityType)
                      throws MessageProcessingException

Read the message entity as an instance of specified (generic) Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Returns null if the message does not contain an entity body. Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream (if open) and makes the entity available for retrieval.

A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). If the message has previously been read as an instance of a different Java type, invoking this method will cause the cached entity instance to be serialized into a temporary input stream using a compatible MessageBodyWriter and then read again from the stream. This operation is thus potentially expensive and should be used with care.

Note that a message entity can also be read as a raw entity input stream, in which case it will be fully consumed once the reading from the entity input stream is finished. Once the entity is read as an input stream, any subsequent calls to one of the readEntity(...) methods or getEntity() method on the same message instance will result in a MessageProcessingException being thrown. It is up to the consumer of the entity input stream to ensure that consuming the stream is properly mitigated (e.g. by substituting the consumed response instance with a new one etc.).

Type Parameters:

T - entity instance Java type.

Parameters:

entityType - the type of entity; may be generic.

Returns:

the message entity or null if message does not contain an entity body.

Throws:

MessageProcessingException - if the content of the message cannot be mapped to an entity of the requested type or if the entity input stream was previously directly consumed by invoking readEntity(InputStream.class).

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(javax.ws.rs.core.TypeLiteral, java.lang.annotation.Annotation[]), readEntity(java.lang.Class), readEntity(java.lang.Class, java.lang.annotation.Annotation[]), bufferEntity(), close(), MessageBodyWriter, MessageBodyReader

readEntity

public abstract <T> T readEntity(Class<T> type,
                                 Annotation[] annotations)
                      throws MessageProcessingException

Read the message entity as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Returns null if the message does not contain an entity body. Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream (if open) and makes the entity available for retrieval.

A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). If the message has previously been read as an instance of a different Java type, invoking this method will cause the cached entity instance to be serialized into a temporary input stream using a compatible MessageBodyWriter and then read again from the stream. This operation is thus potentially expensive and should be used with care.

Note that a message entity can also be read as a raw entity input stream, in which case it will be fully consumed once the reading from the entity input stream is finished. Once the entity is read as an input stream, any subsequent calls to one of the readEntity(...) methods or getEntity() method on the same message instance will result in a MessageProcessingException being thrown. It is up to the consumer of the entity input stream to ensure that consuming the stream is properly mitigated (e.g. by substituting the consumed response instance with a new one etc.).

Type Parameters:

T - entity instance Java type.

Parameters:

type - the type of entity.

annotations - annotations that will be passed to the MessageBodyReader.

Returns:

the message entity or null if message does not contain an entity body.

Throws:

MessageProcessingException - if the content of the message cannot be mapped to an entity of the requested type or if the entity input stream was previously directly consumed by invoking readEntity(InputStream.class).

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.TypeLiteral), readEntity(javax.ws.rs.core.TypeLiteral, java.lang.annotation.Annotation[]), bufferEntity(), close(), MessageBodyWriter, MessageBodyReader

readEntity

public abstract <T> T readEntity(TypeLiteral<T> entityType,
                                 Annotation[] annotations)
                      throws MessageProcessingException

Read the message entity as an instance of specified (generic) Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Returns null if the message does not contain an entity body. Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream (if open) and makes the entity available for retrieval.

A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). If the message has previously been read as an instance of a different Java type, invoking this method will cause the cached entity instance to be serialized into a temporary input stream using a compatible MessageBodyWriter and then read again from the stream. This operation is thus potentially expensive and should be used with care.

Note that a message entity can also be read as a raw entity input stream, in which case it will be fully consumed once the reading from the entity input stream is finished. Once the entity is read as an input stream, any subsequent calls to one of the readEntity(...) methods or getEntity() method on the same message instance will result in a MessageProcessingException being thrown. It is up to the consumer of the entity input stream to ensure that consuming the stream is properly mitigated (e.g. by substituting the consumed response instance with a new one etc.).

Type Parameters:

T - entity instance Java type.

Parameters:

entityType - the type of entity; may be generic.

annotations - annotations that will be passed to the MessageBodyReader.

Returns:

the message entity or null if message does not contain an entity body.

Throws:

MessageProcessingException - if the content of the message cannot be mapped to an entity of the requested type or if the entity input stream was previously directly consumed by invoking readEntity(InputStream.class).

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(javax.ws.rs.core.TypeLiteral), readEntity(java.lang.Class), readEntity(java.lang.Class, java.lang.annotation.Annotation[]), bufferEntity(), close(), MessageBodyWriter, MessageBodyReader

hasEntity

public abstract boolean hasEntity()

Check if there is an entity available in the response. The method returns true if the entity is present, returns false otherwise.

In case the message contained an entity, but it was already consumed as an input stream via readEntity(InputStream.class), the method returns false.

Returns:

true if there is an entity present in the message, false otherwise.

Since:

2.0

See Also:

isEntityRetrievable(), getEntity(), readEntity(java.lang.Class), readEntity(java.lang.Class, java.lang.annotation.Annotation[]), readEntity(javax.ws.rs.core.TypeLiteral), readEntity(javax.ws.rs.core.TypeLiteral, java.lang.annotation.Annotation[])

isEntityRetrievable

public abstract boolean isEntityRetrievable()

Check if the entity instance is present and available for a retrieval via getEntity(). The method returns true if the entity is retrievable, returns false in case there is no entity associated with the message or if the existing message entity is not available as a Java type. This is typically the case (on the client side) when the entity input stream has not been consumed using one of the readEntity(...) methods yet.

Note that even though entity buffering closes the original entity input stream, the buffered entity may still not be retrievable, unless the buffered data was previously read using one of the readEntity(...) methods.

Returns:

true if there is a retrievable message entity instance present, false otherwise.

Since:

2.0

See Also:

hasEntity(), getEntity(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.TypeLiteral), bufferEntity()

bufferEntity

public abstract void bufferEntity()
                           throws MessageProcessingException

Buffer the message entity. In case the message entity input stream is open, all the bytes of the original entity input stream are read and stored in memory. The original entity input stream is automatically closed as part of the operation.

This operation is idempotent, i.e. it can be invoked multiple times with the same effect which also means that calling the bufferEntity() method on an already buffered (and thus closed) message instance is legal and has no further effect.

Note that even though entity buffering closes the original entity input stream, the buffered entity may still not be retrievable, unless the buffered data was previously read using one of the readEntity(...) methods.

Throws:

MessageProcessingException - if there is an error buffering the message entity.

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.TypeLiteral), close()

close

public abstract void close()
                    throws MessageProcessingException

Close the message entity input stream (if available and open). This operation is idempotent, i.e. it can be invoked multiple times with the same effect which also means that calling the close() method on an already closed message instance is legal and has no further effect.

The close() method should be invoked on all instances that contain an un-consumed entity input stream to ensure the resources associated with the instance are properly cleaned-up and prevent potential memory leaks. This is typical for client-side scenarios where application layer code processes only the response headers and ignores the response entity.

If the close() method is invoked before the message entity has been fully read from the input stream, any subsequent attempt to read the entity will result in an MessageProcessingException being thrown.

Closing an instance that has already been consumed has no effect. Similarly, closing an instance with no entity has not effect.

Throws:

MessageProcessingException - if there is an error closing the response.

Since:

2.0

See Also:

readEntity(java.lang.Class), readEntity(javax.ws.rs.core.TypeLiteral)

getMetadata

public abstract MultivaluedMap<String,Object> getMetadata()

Get metadata (headers) associated with the response as a map. The returned map may be subsequently modified by the JAX-RS runtime. Values will be serialized using a RuntimeDelegate.HeaderDelegate if one is available via RuntimeDelegate.createHeaderDelegate(java.lang.Class) for the class of the value or using the values toString method if a header delegate is not available.

This method is effectively a shortcut for getHeaders().asMap() and may be deprecated in the future versions of JAX-RS API.

Returns:

response metadata (headers) as a map.

fromResponse

public static Response.ResponseBuilder fromResponse(Response response)

Create a new ResponseBuilder by performing a shallow copy of an existing Response. The returned builder has its own response headers but the header values are shared with the original Response instance. If retrievable, the original response entity instance is set in the new response builder.

Parameters:

response - a Response from which the status code, entity (if retrievable) and response headers will be copied.

Returns:

a new ReponseBuilder.

status

public static Response.ResponseBuilder status(Response.StatusType status)

Create a new ResponseBuilder with the supplied status.

Parameters:

status - the response status

Returns:

a new ResponseBuilder

Throws:

IllegalArgumentException - if status is null

status

public static Response.ResponseBuilder status(Response.Status status)

Create a new ResponseBuilder with the supplied status.

Parameters:

status - the response status

Returns:

a new ResponseBuilder

Throws:

IllegalArgumentException - if status is null

status

public static Response.ResponseBuilder status(int status)

Create a new ResponseBuilder with the supplied status.

Parameters:

status - the response status

Returns:

a new ResponseBuilder

Throws:

IllegalArgumentException - if status is less than 100 or greater than 599.

ok

public static Response.ResponseBuilder ok()

Create a new ResponseBuilder with an OK status.

Returns:

a new ResponseBuilder

ok

public static Response.ResponseBuilder ok(Object entity)

Create a new ResponseBuilder that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.

Parameters:

entity - the representation entity data

Returns:

a new ResponseBuilder

ok

public static Response.ResponseBuilder ok(Object entity,
                                          MediaType type)

Create a new ResponseBuilder that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.

Parameters:

entity - the representation entity data

type - the media type of the entity

Returns:

a new ResponseBuilder

ok

public static Response.ResponseBuilder ok(Object entity,
                                          String type)

Create a new ResponseBuilder that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.

Parameters:

entity - the representation entity data

type - the media type of the entity

Returns:

a new ResponseBuilder

ok

public static Response.ResponseBuilder ok(Object entity,
                                          Variant variant)

Create a new ResponseBuilder that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.

Parameters:

entity - the representation entity data

variant - representation metadata

Returns:

a new ResponseBuilder

serverError

public static Response.ResponseBuilder serverError()

Create a new ResponseBuilder with an server error status.

Returns:

a new ResponseBuilder

created

public static Response.ResponseBuilder created(URI location)

Create a new ResponseBuilder for a created resource, set the location header using the supplied value.

Parameters:

location - the URI of the new resource. If a relative URI is supplied it will be converted into an absolute URI by resolving it relative to the request URI (see UriInfo.getRequestUri()).

Returns:

a new ResponseBuilder

Throws:

IllegalArgumentException - if location is null

noContent

public static Response.ResponseBuilder noContent()

Create a new ResponseBuilder for an empty response.

Returns:

a new ResponseBuilder

notModified

public static Response.ResponseBuilder notModified()

Create a new ResponseBuilder with a not-modified status.

Returns:

a new ResponseBuilder

notModified

public static Response.ResponseBuilder notModified(EntityTag tag)

Create a new ResponseBuilder with a not-modified status.

Parameters:

tag - a tag for the unmodified entity

Returns:

a new ResponseBuilder

Throws:

IllegalArgumentException - if tag is null

notModified

public static Response.ResponseBuilder notModified(String tag)

Create a new ResponseBuilder with a not-modified status and a strong entity tag. This is a shortcut for notModified(new EntityTag(value)).

Parameters:

tag - the string content of a strong entity tag. The JAX-RS runtime will quote the supplied value when creating the header.

Returns:

a new ResponseBuilder

Throws:

IllegalArgumentException - if tag is null

seeOther

public static Response.ResponseBuilder seeOther(URI location)

Create a new ResponseBuilder for a redirection. Used in the redirect-after-POST (aka POST/redirect/GET) pattern.

Parameters:

location - the redirection URI. If a relative URI is supplied it will be converted into an absolute URI by resolving it relative to the base URI of the application (see UriInfo.getBaseUri()).

Returns:

a new ResponseBuilder

Throws:

IllegalArgumentException - if location is null

temporaryRedirect

public static Response.ResponseBuilder temporaryRedirect(URI location)

Create a new ResponseBuilder for a temporary redirection.

Parameters:

location - the redirection URI. If a relative URI is supplied it will be converted into an absolute URI by resolving it relative to the base URI of the application (see UriInfo.getBaseUri()).

Returns:

a new ResponseBuilder

Throws:

IllegalArgumentException - if location is null

notAcceptable

public static Response.ResponseBuilder notAcceptable(List<Variant> variants)

Create a new ResponseBuilder for a not acceptable response.

Parameters:

variants - list of variants that were available, a null value is equivalent to an empty list.

Returns:

a new ResponseBuilder