javax.ws.rs.core.Response
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public abstract class Response
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).
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 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 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()
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. |
|
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
|
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
|
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
|
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
|
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 |
|---|
protected Response()
Response.ResponseBuilder instance and obtain a Response from that.
| Method Detail |
|---|
public abstract int getStatus()
public abstract Response.StatusType getStatusInfo()
null.
public abstract java.lang.Object getEntity()
throws java.lang.IllegalStateException
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.
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)
throws MessageProcessingException,
java.lang.IllegalStateException
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.
T - entity instance Java type.entityType - the type of entity.
null if message does not contain an
entity body.
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,
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)
throws MessageProcessingException,
java.lang.IllegalStateException
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.
T - entity instance Java type.entityType - the type of entity; may be generic.
null if message does not contain an
entity body.
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,
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)
throws MessageProcessingException,
java.lang.IllegalStateException
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.
T - entity instance Java type.entityType - the type of entity.annotations - annotations that will be passed to the MessageBodyReader.
null if message does not contain an
entity body.
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,
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)
throws MessageProcessingException,
java.lang.IllegalStateException
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.
T - entity instance Java type.entityType - the type of entity; may be generic.annotations - annotations that will be passed to the MessageBodyReader.
null if message does not contain an
entity body.
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,
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()
throws java.lang.IllegalStateException
true if the entity is present, returns false otherwise.
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()
throws MessageProcessingException,
java.lang.IllegalStateException
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 locally.
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. 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.
MessageProcessingException - 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()
throws MessageProcessingException
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.
MessageProcessingException - 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.
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 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 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 request 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.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||