javax.ws.rs.core
Class Response

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

public abstract class Response
extends java.lang.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

static Response.ResponseBuilder	accepted() Create a new ResponseBuilder with an ACCEPTED status.
static Response.ResponseBuilder	accepted(java.lang.Object entity) Create a new ResponseBuilder with an ACCEPTED status that contains a representation.
abstract boolean	bufferEntity() Buffer the message entity.
abstract void	close() Close the message entity input stream (if available and open).
static Response.ResponseBuilder	created(java.net.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 java.util.Set<java.lang.String>	getAllowedMethods() Get the allowed HTTP methods from the Allow HTTP header.
abstract java.util.Map<java.lang.String,NewCookie>	getCookies() Get any new cookies set on the response message.
abstract java.util.Date	getDate() Get message date.
abstract java.lang.Object	getEntity() Get the message entity Java instance.
abstract EntityTag	getEntityTag() Get the entity tag.
abstract java.lang.String	getHeader(java.lang.String name) Get a message header as a single string value.
abstract java.util.Locale	getLanguage() Get the language of the message entity.
abstract java.util.Date	getLastModified() Get the last modified date.
abstract int	getLength() Get Content-Length value.
abstract Link	getLink(java.lang.String relation) Get the link for the relation.
abstract Link.Builder	getLinkBuilder(java.lang.String relation) Convenience method that returns a Link.Builder for the relation.
abstract java.util.Set<Link>	getLinks() Get the links attached to the message as header.
abstract java.net.URI	getLocation() Get the location.
abstract MediaType	getMediaType() Get the media type of the message entity.
abstract MultivaluedMap<java.lang.String,java.lang.Object>	getMetadata() Get metadata (headers) associated with the response as a multivalued map.
abstract int	getStatus() Get the status code associated with the response.
abstract Response.StatusType	getStatusInfo() Get the complete status information associated with the response.
abstract boolean	hasEntity() Check if there is an entity available in the response.
abstract boolean	hasLink(java.lang.String relation) Check if link for relation exists.
static Response.ResponseBuilder	noContent() Create a new ResponseBuilder for an empty response.
static Response.ResponseBuilder	notAcceptable(java.util.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(java.lang.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(java.lang.Object entity) Create a new ResponseBuilder that contains a representation.
static Response.ResponseBuilder	ok(java.lang.Object entity, MediaType type) Create a new ResponseBuilder that contains a representation.
static Response.ResponseBuilder	ok(java.lang.Object entity, java.lang.String type) Create a new ResponseBuilder that contains a representation.
static Response.ResponseBuilder	ok(java.lang.Object entity, Variant variant) Create a new ResponseBuilder that contains a representation.
abstract <T> T	readEntity(java.lang.Class<T> entityType) Read the message entity input stream 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(java.lang.Class<T> entityType, java.lang.annotation.Annotation[] annotations) Read the message entity input stream 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(GenericType<T> entityType) Read the message entity input stream 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(GenericType<T> entityType, java.lang.annotation.Annotation[] annotations) Read the message entity input stream as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
static Response.ResponseBuilder	seeOther(java.net.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(java.net.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

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.

getStatusInfo

public abstract Response.StatusType getStatusInfo()

Get the complete status information associated with the response.

Returns:

the response status information or null if the status was not set.

getEntity

public abstract java.lang.Object getEntity()
                                    throws java.lang.IllegalStateException

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

If the entity is represented by an un-consumed input stream the method will return the input stream.

Returns:

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

Throws:

java.lang.IllegalStateException - if the entity was previously fully consumed as an input stream.

readEntity

public abstract <T> T readEntity(java.lang.Class<T> entityType)
                      throws MessageProcessingException,
                             java.lang.IllegalStateException

Read the message entity input stream as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Method throws an MessageProcessingException if the content of the message cannot be mapped to an entity of the requested type and IllegalStateException in case the entity is not backed by an input stream or if the entity input stream has already been consumed and has not been buffered prior consuming.

If the message does not contain an entity body null is returned. A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream if it is not buffered. In case he entity input stream has been buffered, it will be reset when the method returns to enable subsequent invocations of the readEntity(...) methods on this response.

Type Parameters:

T - entity instance Java type.

Parameters:

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

java.lang.IllegalStateException - if the entity is not backed by an input stream, or if the entity input stream has been fully consumed already and has not been buffered prior consuming.

Since:

2.0

See Also:

MessageBodyReader

readEntity

public abstract <T> T readEntity(GenericType<T> entityType)
                      throws MessageProcessingException,
                             java.lang.IllegalStateException

Read the message entity input stream as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Method throws an MessageProcessingException if the content of the message cannot be mapped to an entity of the requested type and IllegalStateException in case the entity is not backed by an input stream or if the entity input stream has already been consumed and has not been buffered prior consuming.

If the message does not contain an entity body null is returned. A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream if it is not buffered. In case he entity input stream has been buffered, it will be reset when the method returns to enable subsequent invocations of the readEntity(...) methods on this response.

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.

java.lang.IllegalStateException - if the entity is not backed by an input stream, or if the entity input stream has been fully consumed already and has not been buffered prior consuming.

Since:

2.0

See Also:

MessageBodyReader

readEntity

public abstract <T> T readEntity(java.lang.Class<T> entityType,
                                 java.lang.annotation.Annotation[] annotations)
                      throws MessageProcessingException,
                             java.lang.IllegalStateException

Read the message entity input stream as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Method throws an MessageProcessingException if the content of the message cannot be mapped to an entity of the requested type and IllegalStateException in case the entity is not backed by an input stream or if the entity input stream has already been consumed and has not been buffered prior consuming.

If the message does not contain an entity body null is returned. A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream if it is not buffered. In case he entity input stream has been buffered, it will be reset when the method returns to enable subsequent invocations of the readEntity(...) methods on this response.

Type Parameters:

T - entity instance Java type.

Parameters:

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

java.lang.IllegalStateException - if the entity is not backed by an input stream, or if the entity input stream has been fully consumed already and has not been buffered prior consuming.

Since:

2.0

See Also:

MessageBodyReader

readEntity

public abstract <T> T readEntity(GenericType<T> entityType,
                                 java.lang.annotation.Annotation[] annotations)
                      throws MessageProcessingException,
                             java.lang.IllegalStateException

Read the message entity input stream as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Method throws an MessageProcessingException if the content of the message cannot be mapped to an entity of the requested type and IllegalStateException in case the entity is not backed by an input stream or if the entity input stream has already been consumed and has not been buffered prior consuming.

If the message does not contain an entity body null is returned. A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream if it is not buffered. In case he entity input stream has been buffered, it will be reset when the method returns to enable subsequent invocations of the readEntity(...) methods on this response.

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.

java.lang.IllegalStateException - if the entity is not backed by an input stream, or if the entity input stream has been fully consumed already and has not been buffered prior consuming.

Since:

2.0

See Also:

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.

Returns:

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

Since:

2.0

bufferEntity

public abstract boolean bufferEntity()
                              throws MessageProcessingException

Buffer the message entity. In case the message entity is backed by an open input stream, all the bytes of the original entity input stream are read and stored locally. The original entity input stream is consumed and automatically closed as part of the operation and the method returns true.

A request for entity buffering is ignored if the response entity instance is not backed by an open input stream and method returns false.

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. Also, the result returned by the bufferEntity() method is consistent across all invocations of the method on the same Response instance.

Buffering the entity input stream allows for multiple invocations of readEntity(...) methods on this response.

Returns:

true if the message entity input stream was available and was buffered successfully, returns false if the entity stream was not available.

Throws:

MessageProcessingException - if there was an error while buffering the entity input stream.

Since:

2.0

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

getHeader

public abstract java.lang.String getHeader(java.lang.String name)

Get a message header as a single string value. Each single header value is converted to String using a RuntimeDelegate.HeaderDelegate if one is available via RuntimeDelegate.createHeaderDelegate(java.lang.Class) for the header value class or using its toString method if a header delegate is not available.

Parameters:

name - the message header.

Returns:

the message header value. If the message header is not present then null is returned. If the message header is present but has no value then the empty string is returned. If the message header is present more than once then the values of joined together and separated by a ',' character.

Since:

2.0

getMediaType

public abstract MediaType getMediaType()

Get the media type of the message entity.

Returns:

the media type or null if there is no response entity.

Since:

2.0

getLanguage

public abstract java.util.Locale getLanguage()

Get the language of the message entity.

Returns:

the language of the entity or null if not specified.

Since:

2.0

getLength

public abstract int getLength()

Get Content-Length value.

Returns:

Content-Length as integer if present and valid number. In other cases returns -1.

Since:

2.0

getAllowedMethods

public abstract java.util.Set<java.lang.String> getAllowedMethods()

Get the allowed HTTP methods from the Allow HTTP header.

Returns:

the allowed HTTP methods, all methods will returned as upper case strings.

Since:

2.0

getCookies

public abstract java.util.Map<java.lang.String,NewCookie> getCookies()

Get any new cookies set on the response message.

Returns:

a read-only map of cookie name (String) to Cookie.

Since:

2.0

getEntityTag

public abstract EntityTag getEntityTag()

Get the entity tag.

Returns:

the entity tag, otherwise null if not present.

Since:

2.0

getDate

public abstract java.util.Date getDate()

Get message date.

Returns:

the message date, otherwise null if not present.

Since:

2.0

getLastModified

public abstract java.util.Date getLastModified()

Get the last modified date.

Returns:

the last modified date, otherwise null if not present.

Since:

2.0

getLocation

public abstract java.net.URI getLocation()

Get the location.

Returns:

the location URI, otherwise null if not present.

Since:

2.0

getLinks

public abstract java.util.Set<Link> getLinks()

Get the links attached to the message as header.

Returns:

links, may return empty Set if no links are present. Does not return null.

Since:

2.0

hasLink

public abstract boolean hasLink(java.lang.String relation)

Check if link for relation exists.

Parameters:

relation - link relation.

Returns:

true if the link for the relation is present in the message headers, false otherwise.

Since:

2.0

getLink

public abstract Link getLink(java.lang.String relation)

Get the link for the relation.

Parameters:

relation - link relation.

Returns:

the link for the relation, otherwise null if not present.

Since:

2.0

getLinkBuilder

public abstract Link.Builder getLinkBuilder(java.lang.String relation)

Convenience method that returns a Link.Builder for the relation.

Parameters:

relation - link relation.

Returns:

the link builder for the relation, otherwise null if not present.

Since:

2.0

getMetadata

public abstract MultivaluedMap<java.lang.String,java.lang.Object> getMetadata()

Get metadata (headers) associated with the response as a multivalued map. The returned map is immutable, but the underlying data may be subsequently modified by the JAX-RS runtime. When the message is sent, the non-string 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.

Returns:

response meta-data (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. The original response entity instance reference is set in the new response builder.

Note that if the entity is backed by an un-consumed input stream, the reference to the stream is copied. In such case make sure to buffer the entity stream of the original response instance before passing it to this method.

Parameters:

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

Returns:

a new response builder.

Since:

2.0

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

Throws:

java.lang.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 response builder.

Throws:

java.lang.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 response builder.

Throws:

java.lang.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 response builder.

ok

public static Response.ResponseBuilder ok(java.lang.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 response builder.

ok

public static Response.ResponseBuilder ok(java.lang.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 response builder.

ok

public static Response.ResponseBuilder ok(java.lang.Object entity,
                                          java.lang.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 response builder.

ok

public static Response.ResponseBuilder ok(java.lang.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 response builder.

serverError

public static Response.ResponseBuilder serverError()

Create a new ResponseBuilder with an server error status.

Returns:

a new response builder.

created

public static Response.ResponseBuilder created(java.net.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 response builder.

Throws:

java.lang.IllegalArgumentException - if location is null.

accepted

public static Response.ResponseBuilder accepted()

Create a new ResponseBuilder with an ACCEPTED status.

Returns:

a new response builder.

Since:

2.0

accepted

public static Response.ResponseBuilder accepted(java.lang.Object entity)

Create a new ResponseBuilder with an ACCEPTED status 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 response builder.

Since:

2.0

noContent

public static Response.ResponseBuilder noContent()

Create a new ResponseBuilder for an empty response.

Returns:

a new response builder.

notModified

public static Response.ResponseBuilder notModified()

Create a new ResponseBuilder with a not-modified status.

Returns:

a new response builder.

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

Throws:

java.lang.IllegalArgumentException - if tag is null.

notModified

public static Response.ResponseBuilder notModified(java.lang.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 response builder.

Throws:

java.lang.IllegalArgumentException - if tag is null.

seeOther

public static Response.ResponseBuilder seeOther(java.net.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 response builder.

Throws:

java.lang.IllegalArgumentException - if location is null.

temporaryRedirect

public static Response.ResponseBuilder temporaryRedirect(java.net.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 response builder.

Throws:

java.lang.IllegalArgumentException - if location is null.

notAcceptable

public static Response.ResponseBuilder notAcceptable(java.util.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 response builder.