public abstract class Response
extends java.lang.Object
implements java.lang.AutoCloseable
An application class should not extend this class directly. Response
class is reserved for an extension by a
JAX-RS implementation providers. An application should use one of the static methods to create a Response
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)
.
Response.ResponseBuilder
Modifier and Type | Class and Description |
---|---|
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.
|
Modifier | Constructor and Description |
---|---|
protected |
Response()
Protected constructor, use one of the static methods to obtain a
Response.ResponseBuilder instance and obtain a
Response from that. |
Modifier and Type | Method and Description |
---|---|
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 data.
|
abstract void |
close()
Close the underlying message entity input stream (if available and open) as well as releases any other resources
associated with the response (e.g.
|
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.
|
MultivaluedMap<java.lang.String,java.lang.Object> |
getHeaders()
Get view of the response headers and their object values.
|
abstract java.lang.String |
getHeaderString(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 headers.
|
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()
See
getHeaders() . |
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 MultivaluedMap<java.lang.String,java.lang.String> |
getStringHeaders()
Get view of the response headers and their string values.
|
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.
|
boolean |
isClosed()
Check if the response is closed.
|
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(int status,
java.lang.String reasonPhrase)
Create a new ResponseBuilder with the supplied status and reason phrase.
|
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.
|
protected Response()
Response.ResponseBuilder
instance and obtain a
Response from that.public abstract int getStatus()
public abstract Response.StatusType getStatusInfo()
null
.public abstract java.lang.Object getEntity()
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.
null
if message does not contain an entity body (i.e. when hasEntity()
returns false
).java.lang.IllegalStateException
- if the entity was previously fully consumed as an input stream
, or
if the response has been closed
.public abstract <T> T readEntity(java.lang.Class<T> entityType)
MessageBodyReader
that supports mapping the message entity stream onto the requested type.
Method throws an ProcessingException
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
original entity input stream has already been consumed without buffering
the entity data
prior consuming.
A 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 an unconsumed original response entity data stream if open. In case the entity data has
been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of
readEntity(...)
methods on this response.
T
- entity instance Java type.entityType
- the type of entity.ProcessingException
wrapping the underlying NoContentException
is thrown.ProcessingException
- 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, the response has been closed
already, or if the entity input stream has been fully consumed already and has not been buffered prior
consuming.MessageBodyReader
public abstract <T> T readEntity(GenericType<T> entityType)
MessageBodyReader
that supports mapping the message entity stream onto the requested type.
Method throws an ProcessingException
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
original entity input stream has already been consumed without buffering
the entity data
prior consuming.
A 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 an unconsumed original response entity data stream if open. In case the entity data has
been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of
readEntity(...)
methods on this response.
T
- entity instance Java type.entityType
- the type of entity; may be generic.ProcessingException
wrapping the underlying NoContentException
is thrown.ProcessingException
- 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, the response has been closed
already, or if the entity input stream has been fully consumed already and has not been buffered prior
consuming.MessageBodyReader
public abstract <T> T readEntity(java.lang.Class<T> entityType, java.lang.annotation.Annotation[] annotations)
MessageBodyReader
that supports mapping the message entity stream onto the requested type.
Method throws an ProcessingException
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
original entity input stream has already been consumed without buffering
the entity data
prior consuming.
A 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 an unconsumed original response entity data stream if open. In case the entity data has
been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of
readEntity(...)
methods on this response.
T
- entity instance Java type.entityType
- the type of entity.annotations
- annotations that will be passed to the MessageBodyReader
.ProcessingException
wrapping the underlying NoContentException
is thrown.ProcessingException
- 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, the response has been closed
already, or if the entity input stream has been fully consumed already and has not been buffered prior
consuming.MessageBodyReader
public abstract <T> T readEntity(GenericType<T> entityType, java.lang.annotation.Annotation[] annotations)
MessageBodyReader
that supports mapping the message entity stream onto the requested type.
Method throws an ProcessingException
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
original entity input stream has already been consumed without buffering
the entity data
prior consuming.
A 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 an unconsumed original response entity data stream if open. In case the entity data has
been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of
readEntity(...)
methods on this response.
T
- entity instance Java type.entityType
- the type of entity; may be generic.annotations
- annotations that will be passed to the MessageBodyReader
.ProcessingException
wrapping the underlying NoContentException
is thrown.ProcessingException
- 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, the response has been closed
already, or if the entity input stream has been fully consumed already and has not been buffered prior
consuming.MessageBodyReader
public abstract boolean hasEntity()
true
if the entity is present,
returns false
otherwise.
Note that the method may return true
also for response messages with a zero-length content, in case the
"Content-Length"
and
"Content-Type"
headers are specified in the message. In such case, an
attempt to read the entity using one of the readEntity(...)
methods will return a corresponding instance
representing a zero-length entity for a given Java type or produce a ProcessingException
in case no such
instance is available for the Java type.
true
if there is an entity present in the message, false
otherwise.java.lang.IllegalStateException
- in case the response has been closed
.public abstract boolean bufferEntity()
In case the message entity is backed by an unconsumed entity input stream, all the bytes of the original entity input
stream are read and stored in a local buffer. The original entity input stream is consumed and automatically closed
as part of the operation and the method returns true
.
In case the response entity instance is not backed by an unconsumed input stream an invocation of
bufferEntity
method is ignored and the 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 message entity data allows for multiple invocations of readEntity(...)
methods on the response
instance. Note however, that once the response instance itself is closed
, the implementations are
expected to release the buffered message entity data too. Therefore any subsequent attempts to read a message entity
stream on such closed response will result in an IllegalStateException
being thrown.
true
if the message entity input stream was available and was buffered successfully, returns
false
if the entity stream was not available.ProcessingException
- if there was an error while buffering the entity input stream.java.lang.IllegalStateException
- in case the response has been closed
.public abstract void close()
buffered message entity data
).
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.
Any attempts to manipulate (read, get, buffer) a message entity on a closed response will result in an
IllegalStateException
being thrown.
close
in interface java.lang.AutoCloseable
ProcessingException
- if there is an error closing the response.public abstract MediaType getMediaType()
null
if there is no response entity.public abstract java.util.Locale getLanguage()
public abstract int getLength()
-1
.public abstract java.util.Set<java.lang.String> getAllowedMethods()
public abstract java.util.Map<java.lang.String,NewCookie> getCookies()
public abstract EntityTag getEntityTag()
null
if not present.public abstract java.util.Date getDate()
null
if not present.public abstract java.util.Date getLastModified()
null
if not present.public abstract java.net.URI getLocation()
null
if not present.public abstract java.util.Set<Link> getLinks()
Set
if no links are present. Does not return null
.public abstract boolean hasLink(java.lang.String relation)
relation
- link relation.true
if the link for the relation is present in the message headers
,
false
otherwise.public abstract Link getLink(java.lang.String relation)
relation
- link relation.null
if not present.public abstract Link.Builder getLinkBuilder(java.lang.String relation)
Link.Builder
for the relation. See getLink(java.lang.String)
for more information.relation
- link relation.null
if not present.public abstract MultivaluedMap<java.lang.String,java.lang.Object> getMetadata()
getHeaders()
.
This method is considered deprecated. Users are encouraged to switch their code to use the getHeaders()
method instead. The method may be annotated as @Deprecated
in a future release of JAX-RS API.public MultivaluedMap<java.lang.String,java.lang.Object> getHeaders()
On the server-side, 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.
On the client side, the returned map is identical to the one returned by getStringHeaders()
.
getStringHeaders()
,
getHeaderString(java.lang.String)
public abstract MultivaluedMap<java.lang.String,java.lang.String> getStringHeaders()
getHeaders()
,
getHeaderString(java.lang.String)
public abstract java.lang.String getHeaderString(java.lang.String name)
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.name
- the message header.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.getHeaders()
,
getStringHeaders()
public boolean isClosed()
true
if the response is closed,
returns false
otherwise.true
if the response has been closed
, false
otherwise.public static Response.ResponseBuilder fromResponse(Response 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.
response
- a Response from which the status code, entity and response headers
will be
copied.public static Response.ResponseBuilder status(Response.StatusType status)
status
- the response status.java.lang.IllegalArgumentException
- if status is null
.public static Response.ResponseBuilder status(Response.Status status)
status
- the response status.java.lang.IllegalArgumentException
- if status is null
.public static Response.ResponseBuilder status(int status)
status
- the response status.java.lang.IllegalArgumentException
- if status is less than 100
or greater than 599
.public static Response.ResponseBuilder status(int status, java.lang.String reasonPhrase)
status
- the response status.reasonPhrase
- the reason phrase.java.lang.IllegalArgumentException
- if status is less than 100
or greater than 599
.public static Response.ResponseBuilder ok()
public static Response.ResponseBuilder ok(java.lang.Object entity)
GenericEntity
if preservation of its generic type is required.entity
- the representation entity data.public static Response.ResponseBuilder ok(java.lang.Object entity, MediaType type)
GenericEntity
if preservation of its generic type is required.entity
- the representation entity data.type
- the media type of the entity.public static Response.ResponseBuilder ok(java.lang.Object entity, java.lang.String type)
GenericEntity
if preservation of its generic type is required.entity
- the representation entity data.type
- the media type of the entity.public static Response.ResponseBuilder ok(java.lang.Object entity, Variant variant)
GenericEntity
if preservation of its generic type is required.entity
- the representation entity data.variant
- representation metadata.public static Response.ResponseBuilder serverError()
public static Response.ResponseBuilder created(java.net.URI location)
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 base URI (see UriInfo.getRequestUri()
).java.lang.IllegalArgumentException
- if location is null
.public static Response.ResponseBuilder accepted()
public static Response.ResponseBuilder accepted(java.lang.Object entity)
GenericEntity
if preservation of its generic type is required.entity
- the representation entity data.public static Response.ResponseBuilder noContent()
public static Response.ResponseBuilder notModified()
public static Response.ResponseBuilder notModified(EntityTag tag)
tag
- a tag for the unmodified entity.java.lang.IllegalArgumentException
- if tag is null
.public static Response.ResponseBuilder notModified(java.lang.String tag)
notModified(new EntityTag(value))
.tag
- the string content of a strong entity tag. The JAX-RS runtime will quote the supplied value when creating
the header.java.lang.IllegalArgumentException
- if tag is null
.public static Response.ResponseBuilder seeOther(java.net.URI location)
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()
).java.lang.IllegalArgumentException
- if location is null
.public static Response.ResponseBuilder temporaryRedirect(java.net.URI location)
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()
).java.lang.IllegalArgumentException
- if location is null
.public static Response.ResponseBuilder notAcceptable(java.util.List<Variant> variants)
variants
- list of variants that were available, a null value is equivalent to an empty list.