public abstract class Response extends Object
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(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(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 Set<String> |
getAllowedMethods()
Get the allowed HTTP methods from the Allow HTTP header.
|
abstract Map<String,NewCookie> |
getCookies()
Get any new cookies set on the response message.
|
abstract Date |
getDate()
Get message date.
|
abstract Object |
getEntity()
Get the message entity Java instance.
|
abstract EntityTag |
getEntityTag()
Get the entity tag.
|
MultivaluedMap<String,Object> |
getHeaders()
Get view of the response headers and their object values.
|
abstract String |
getHeaderString(String name)
Get a message header as a single string value.
|
abstract Locale |
getLanguage()
Get the language of the message entity.
|
abstract Date |
getLastModified()
Get the last modified date.
|
abstract int |
getLength()
Get Content-Length value.
|
abstract Link |
getLink(String relation)
Get the link for the relation.
|
abstract Link.Builder |
getLinkBuilder(String relation)
Convenience method that returns a
Link.Builder for the relation. |
abstract Set<Link> |
getLinks()
Get the links attached to the message as headers.
|
abstract URI |
getLocation()
Get the location.
|
abstract MediaType |
getMediaType()
Get the media type of the message entity.
|
abstract MultivaluedMap<String,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<String,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(String relation)
Check if link for relation exists.
|
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> 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(Class<T> entityType,
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,
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(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.
|
protected Response()
Response.ResponseBuilder
instance and obtain a Response from that.public abstract int getStatus()
public abstract Response.StatusType getStatusInfo()
null
.public abstract 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
).IllegalStateException
- if the entity was previously fully consumed
as an input stream
, or
if the response has been closed
.public abstract <T> T readEntity(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.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.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(Class<T> entityType, 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.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, 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.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.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.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.
ProcessingException
- if there is an error closing the response.public abstract MediaType getMediaType()
null
if there is no response entity.public abstract Locale getLanguage()
public abstract int getLength()
-1
.public abstract Set<String> getAllowedMethods()
public abstract Map<String,NewCookie> getCookies()
public abstract EntityTag getEntityTag()
null
if not present.public abstract Date getDate()
null
if not present.public abstract Date getLastModified()
null
if not present.public abstract URI getLocation()
null
if not present.public abstract Set<Link> getLinks()
Set
if no links are present. Does
not return null
.public abstract boolean hasLink(String relation)
relation
- link relation.true
if the link for the relation is present in the
message headers
, false
otherwise.public abstract Link getLink(String relation)
relation
- link relation.null
if not present.public abstract Link.Builder getLinkBuilder(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<String,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<String,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<String,String> getStringHeaders()
getHeaders()
,
getHeaderString(java.lang.String)
public abstract String getHeaderString(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 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.IllegalArgumentException
- if status is null
.public static Response.ResponseBuilder status(Response.Status status)
status
- the response status.IllegalArgumentException
- if status is null
.public static Response.ResponseBuilder status(int status)
status
- the response status.IllegalArgumentException
- if status is less than 100
or greater
than 599
.public static Response.ResponseBuilder ok()
public static Response.ResponseBuilder ok(Object entity)
GenericEntity
if preservation of its generic type is required.entity
- the representation entity data.public static Response.ResponseBuilder ok(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(Object entity, 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(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(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 request URI (see UriInfo.getRequestUri()
).IllegalArgumentException
- if location is null
.public static Response.ResponseBuilder accepted()
public static Response.ResponseBuilder accepted(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.IllegalArgumentException
- if tag is null
.public static Response.ResponseBuilder notModified(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.IllegalArgumentException
- if tag is null
.public static Response.ResponseBuilder seeOther(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()
).IllegalArgumentException
- if location is null
.public static Response.ResponseBuilder temporaryRedirect(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()
).IllegalArgumentException
- if location is null
.public static Response.ResponseBuilder notAcceptable(List<Variant> variants)
variants
- list of variants that were available, a null value is
equivalent to an empty list.Copyright © 2007-2015, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.