Class RestResponse<T>
- All Implemented Interfaces:
AutoCloseable
- Direct Known Subclasses:
RestResponseImpl
An application class should not extend this class directly. RestResponse
class is
reserved for an extension by API implementation providers. An application should use one
of the static methods to create a RestResponse
instance using a RestResponseBuilder.
Several methods have parameters of type URI, UriBuilder
provides
convenient methods to create such values as does URI.create(java.lang.String)
.
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
A class used to build RestResponse instances that contain metadata instead of or in addition to an entity.static enum
Commonly used status codes defined by HTTP, see {@link <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10">HTTP/1.1 documentation} for the complete list.static class
Commonly used status codes defined by HTTP, see {@link <a href="https://tools.ietf.org/html/rfc7231#section-6.2">HTTP/1.1 documentation} for the complete list. -
Constructor Summary
ModifierConstructorDescriptionprotected
Protected constructor, use one of the static methods to obtain aRestResponse.ResponseBuilder
instance and obtain a RestResponse from that. -
Method Summary
Modifier and TypeMethodDescriptionstatic <IGNORED> RestResponse<IGNORED>
accepted()
Create a new RestResponse with an ACCEPTED status.static <T> RestResponse<T>
accepted
(T entity) Create a new RestResponse with an ACCEPTED status that contains a representation.abstract boolean
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 <IGNORED> RestResponse<IGNORED>
Create a new RestResponse for a created resource, set the location header using the supplied value.static <T> RestResponse<T>
fromResponse
(RestResponse<T> response) Create a new ResponseBuilder by performing a shallow copy of an existing RestResponse.Get the allowed HTTP methods from the Allow HTTP header.Get any new cookies set on the response message.abstract Date
getDate()
Get message date.abstract T
Get the message entity Java instance.abstract jakarta.ws.rs.core.EntityTag
Get the entity tag.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
Get the language of the message entity.abstract Date
Get the last modified date.abstract int
Get Content-Length value.abstract jakarta.ws.rs.core.Link
Get the link for the relation.abstract jakarta.ws.rs.core.Link.Builder
getLinkBuilder
(String relation) Convenience method that returns aLink.Builder
for the relation.abstract Set<jakarta.ws.rs.core.Link>
getLinks()
Get the links attached to the message as headers.abstract URI
Get the location.abstract jakarta.ws.rs.core.MediaType
Get the media type of the message entity.SeegetHeaders()
.abstract int
Get the status code associated with the response.abstract jakarta.ws.rs.core.Response.StatusType
Get the complete status information associated with the response.Get view of the response headers and their string values.abstract boolean
Check if there is an entity available in the response.abstract boolean
Check if link for relation exists.static <IGNORED> RestResponse<IGNORED>
Create a new RestResponse for an empty response.static <IGNORED> RestResponse<IGNORED>
notAcceptable
(List<jakarta.ws.rs.core.Variant> variants) Create a new RestResponse for a not acceptable response.static <IGNORED> RestResponse<IGNORED>
notFound()
Create a new RestResponse for a not found response.static <IGNORED> RestResponse<IGNORED>
Create a new RestResponse with a not-modified status.static <IGNORED> RestResponse<IGNORED>
notModified
(jakarta.ws.rs.core.EntityTag tag) Create a new RestResponse with a not-modified status.static <IGNORED> RestResponse<IGNORED>
notModified
(String tag) Create a new RestResponse with a not-modified status and a strong entity tag.static <IGNORED> RestResponse<IGNORED>
ok()
Create a new RestResponse with an OK status.static <T> RestResponse<T>
ok
(T entity) Create a new RestResponse that contains a representation.static <T> RestResponse<T>
ok
(T entity, jakarta.ws.rs.core.MediaType type) Create a new RestResponse that contains a representation.static <T> RestResponse<T>
ok
(T entity, jakarta.ws.rs.core.Variant variant) Create a new RestResponse that contains a representation.static <T> RestResponse<T>
Create a new RestResponse that contains a representation.abstract <OtherT> OtherT
readEntity
(jakarta.ws.rs.core.GenericType<OtherT> entityType) Read the message entity input stream as an instance of specified Java type using aMessageBodyReader
that supports mapping the message entity stream onto the requested type.abstract <OtherT> OtherT
readEntity
(jakarta.ws.rs.core.GenericType<OtherT> entityType, Annotation[] annotations) Read the message entity input stream as an instance of specified Java type using aMessageBodyReader
that supports mapping the message entity stream onto the requested type.abstract <OtherT> OtherT
readEntity
(Class<OtherT> entityType) Read the message entity input stream as an instance of specified Java type using aMessageBodyReader
that supports mapping the message entity stream onto the requested type.abstract <OtherT> OtherT
readEntity
(Class<OtherT> entityType, Annotation[] annotations) Read the message entity input stream as an instance of specified Java type using aMessageBodyReader
that supports mapping the message entity stream onto the requested type.static <IGNORED> RestResponse<IGNORED>
Create a new RestResponse for a redirection.static <IGNORED> RestResponse<IGNORED>
Create a new RestResponse with an server error status.static <IGNORED> RestResponse<IGNORED>
status
(int status) Create a new RestResponse with the supplied status.static <IGNORED> RestResponse<IGNORED>
Create a new RestResponse with the supplied status and reason phrase.static <IGNORED> RestResponse<IGNORED>
status
(jakarta.ws.rs.core.Response.StatusType status) Create a new RestResponse with the supplied status.static <T> RestResponse<T>
status
(jakarta.ws.rs.core.Response.StatusType status, T entity) Create a new RestResponse with the supplied status.static <IGNORED> RestResponse<IGNORED>
status
(RestResponse.Status status) Create a new RestResponse with the supplied status.static <T> RestResponse<T>
status
(RestResponse.Status status, T entity) Create a new RestResponse with the supplied status.static <IGNORED> RestResponse<IGNORED>
temporaryRedirect
(URI location) Create a new RestResponse for a temporary redirection.abstract jakarta.ws.rs.core.Response
Turns thisRestResponse
into a JAX-RSResponse
.
-
Constructor Details
-
RestResponse
protected RestResponse()Protected constructor, use one of the static methods to obtain aRestResponse.ResponseBuilder
instance and obtain a RestResponse from that.
-
-
Method Details
-
getStatus
public abstract int getStatus()Get the status code associated with the response.- Returns:
- the response status code.
-
getStatusInfo
public abstract jakarta.ws.rs.core.Response.StatusType getStatusInfo()Get the complete status information associated with the response.- Returns:
- the response status information. The returned value is never
null
.
-
getEntity
Get the message entity Java instance. Returnsnull
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 (i.e. whenhasEntity()
returnsfalse
). - Throws:
IllegalStateException
- if the entity was previously fully consumed as aninput stream
, or if the response has beenclosed
.
-
readEntity
Read the message entity input stream as an instance of specified Java type using aMessageBodyReader
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 andIllegalStateException
in case the entity is not backed by an input stream or if the original entity input stream has already been consumed withoutbuffering
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 aninput stream
, this method automaticallycloses
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 ofreadEntity(...)
methods on this response.- Type Parameters:
OtherT
- entity instance Java type.- Parameters:
entityType
- the type of entity.- Returns:
- the message entity; for a zero-length response entities returns a corresponding
Java object that represents zero-length data. In case no zero-length representation
is defined for the Java type, a
ProcessingException
wrapping the underlyingNoContentException
is thrown. - Throws:
jakarta.ws.rs.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 beenclosed
already, or if the entity input stream has been fully consumed already and has not been buffered prior consuming.- See Also:
-
MessageBodyReader
-
readEntity
public abstract <OtherT> OtherT readEntity(jakarta.ws.rs.core.GenericType<OtherT> entityType) Read the message entity input stream as an instance of specified Java type using aMessageBodyReader
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 andIllegalStateException
in case the entity is not backed by an input stream or if the original entity input stream has already been consumed withoutbuffering
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 aninput stream
, this method automaticallycloses
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 ofreadEntity(...)
methods on this response.- Type Parameters:
OtherT
- entity instance Java type.- Parameters:
entityType
- the type of entity; may be generic.- Returns:
- the message entity; for a zero-length response entities returns a corresponding
Java object that represents zero-length data. In case no zero-length representation
is defined for the Java type, a
ProcessingException
wrapping the underlyingNoContentException
is thrown. - Throws:
jakarta.ws.rs.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 beenclosed
already, or if the entity input stream has been fully consumed already and has not been buffered prior consuming.- See Also:
-
MessageBodyReader
-
readEntity
Read the message entity input stream as an instance of specified Java type using aMessageBodyReader
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 andIllegalStateException
in case the entity is not backed by an input stream or if the original entity input stream has already been consumed withoutbuffering
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 aninput stream
, this method automaticallycloses
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 ofreadEntity(...)
methods on this response.- Type Parameters:
OtherT
- entity instance Java type.- Parameters:
entityType
- the type of entity.annotations
- annotations that will be passed to theMessageBodyReader
.- Returns:
- the message entity; for a zero-length response entities returns a corresponding
Java object that represents zero-length data. In case no zero-length representation
is defined for the Java type, a
ProcessingException
wrapping the underlyingNoContentException
is thrown. - Throws:
jakarta.ws.rs.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 beenclosed
already, or if the entity input stream has been fully consumed already and has not been buffered prior consuming.- See Also:
-
MessageBodyReader
-
readEntity
public abstract <OtherT> OtherT readEntity(jakarta.ws.rs.core.GenericType<OtherT> entityType, Annotation[] annotations) Read the message entity input stream as an instance of specified Java type using aMessageBodyReader
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 andIllegalStateException
in case the entity is not backed by an input stream or if the original entity input stream has already been consumed withoutbuffering
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 aninput stream
, this method automaticallycloses
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 ofreadEntity(...)
methods on this response.- Type Parameters:
OtherT
- entity instance Java type.- Parameters:
entityType
- the type of entity; may be generic.annotations
- annotations that will be passed to theMessageBodyReader
.- Returns:
- the message entity; for a zero-length response entities returns a corresponding
Java object that represents zero-length data. In case no zero-length representation
is defined for the Java type, a
ProcessingException
wrapping the underlyingNoContentException
is thrown. - Throws:
jakarta.ws.rs.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 beenclosed
already, or if the entity input stream has been fully consumed already and has not been buffered prior consuming.- See Also:
-
MessageBodyReader
-
hasEntity
public abstract boolean hasEntity()Check if there is an entity available in the response. The method returnstrue
if the entity is present, returnsfalse
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 thereadEntity(...)
methods will return a corresponding instance representing a zero-length entity for a given Java type or produce aProcessingException
in case no such instance is available for the Java type.- Returns:
true
if there is an entity present in the message,false
otherwise.- Throws:
IllegalStateException
- in case the response has beenclosed
.
-
bufferEntity
public abstract boolean bufferEntity()Buffer the message entity data.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 returnsfalse
.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 thebufferEntity()
method is consistent across all invocations of the method on the sameRestResponse
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 isclosed
, 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 anIllegalStateException
being thrown.- Returns:
true
if the message entity input stream was available and was buffered successfully, returnsfalse
if the entity stream was not available.- Throws:
jakarta.ws.rs.ProcessingException
- if there was an error while buffering the entity input stream.IllegalStateException
- in case the response has beenclosed
.
-
close
public 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.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.- Specified by:
close
in interfaceAutoCloseable
- Throws:
jakarta.ws.rs.ProcessingException
- if there is an error closing the response.
-
getMediaType
public abstract jakarta.ws.rs.core.MediaType getMediaType()Get the media type of the message entity.- Returns:
- the media type or
null
if there is no response entity.
-
getLanguage
Get the language of the message entity.- Returns:
- the language of the entity or null if not specified.
-
getLength
public abstract int getLength()Get Content-Length value.- Returns:
- Content-Length as integer if present and valid number. In other
cases returns
-1
.
-
getAllowedMethods
Get the allowed HTTP methods from the Allow HTTP header.- Returns:
- the allowed HTTP methods, all methods will returned as upper case strings.
-
getCookies
Get any new cookies set on the response message.- Returns:
- a read-only map of cookie name (String) to Cookie.
-
getEntityTag
public abstract jakarta.ws.rs.core.EntityTag getEntityTag()Get the entity tag.- Returns:
- the entity tag, otherwise
null
if not present.
-
getDate
Get message date.- Returns:
- the message date, otherwise
null
if not present.
-
getLastModified
Get the last modified date.- Returns:
- the last modified date, otherwise
null
if not present.
-
getLocation
Get the location.- Returns:
- the location URI, otherwise
null
if not present.
-
getLinks
Get the links attached to the message as headers. Any links in the message that are relative must be resolved with respect to the actual request URI that produced this response. Note that request URIs may be updated by filters, so the actual request URI may differ from that in the original invocation.- Returns:
- links, may return empty
Set
if no links are present. Does not returnnull
.
-
hasLink
Check if link for relation exists.- Parameters:
relation
- link relation.- Returns:
true
if the link for the relation is present in themessage headers
,false
otherwise.
-
getLink
Get the link for the relation. A relative link is resolved with respect to the actual request URI that produced this response. Note that request URIs may be updated by filters, so the actual request URI may differ from that in the original invocation.- Parameters:
relation
- link relation.- Returns:
- the link for the relation, otherwise
null
if not present.
-
getLinkBuilder
Convenience method that returns aLink.Builder
for the relation. SeegetLink(java.lang.String)
for more information.- Parameters:
relation
- link relation.- Returns:
- the link builder for the relation, otherwise
null
if not present.
-
getMetadata
SeegetHeaders()
. This method is considered deprecated. Users are encouraged to switch their code to use thegetHeaders()
method instead. The method may be annotated as@Deprecated
in a future release of the API.- Returns:
- response headers as a multivalued map.
-
getHeaders
Get view of the response headers and their object values. The underlying header data may be subsequently modified by the runtime on the server side. Changes in the underlying header data are reflected in this view.On the server-side, when the message is sent, the non-string values will be serialized using a
RuntimeDelegate.HeaderDelegate
if one is available viaRuntimeDelegate.createHeaderDelegate(java.lang.Class)
for the class of the value or using the valuestoString
method if a header delegate is not available.On the client side, the returned map is identical to the one returned by
getStringHeaders()
.- Returns:
- response headers as an object view of header values.
- See Also:
-
getStringHeaders
Get view of the response headers and their string values. The underlying header data may be subsequently modified by the runtime on the server side. Changes in the underlying header data are reflected in this view.- Returns:
- response headers as a string view of header values.
- See Also:
-
getHeaderString
Get a message header as a single string value. Each single header value is converted to String using aRuntimeDelegate.HeaderDelegate
if one is available viaRuntimeDelegate.createHeaderDelegate(java.lang.Class)
for the header value class or using itstoString
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. - See Also:
-
toResponse
public abstract jakarta.ws.rs.core.Response toResponse()Turns thisRestResponse
into a JAX-RSResponse
.- Returns:
- a JAX-RS
Response
representing this response.
-
fromResponse
Create a new ResponseBuilder by performing a shallow copy of an existing RestResponse.The returned builder has its own
response headers
but the header values are shared with the originalRestResponse
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 RestResponse from which the status code, entity andresponse headers
will be copied.- Returns:
- a new response builder.
-
status
Create a new RestResponse with the supplied status.- Parameters:
status
- the response status.- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if status isnull
.
-
status
Create a new RestResponse with the supplied status.- Parameters:
status
- the response status.- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if status isnull
.
-
status
Create a new RestResponse with the supplied status.- Parameters:
status
- the response status.- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if status isnull
.
-
status
Create a new RestResponse with the supplied status.- Parameters:
status
- the response status.- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if status isnull
.
-
status
Create a new RestResponse with the supplied status.- Parameters:
status
- the response status.- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if status is less than100
or greater than599
.
-
status
Create a new RestResponse with the supplied status and reason phrase.- Parameters:
status
- the response status.reasonPhrase
- the reason phrase.- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if status is less than100
or greater than599
.
-
ok
Create a new RestResponse with an OK status.- Returns:
- a new response.
-
ok
Create a new RestResponse that contains a representation. It is the callers responsibility to wrap the actual entity withGenericEntity
if preservation of its generic type is required.- Parameters:
entity
- the representation entity data.- Returns:
- a new response.
-
ok
Create a new RestResponse that contains a representation. It is the callers responsibility to wrap the actual entity withGenericEntity
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.
-
ok
Create a new RestResponse that contains a representation. It is the callers responsibility to wrap the actual entity withGenericEntity
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.
-
ok
Create a new RestResponse that contains a representation. It is the callers responsibility to wrap the actual entity withGenericEntity
if preservation of its generic type is required.- Parameters:
entity
- the representation entity data.variant
- representation metadata.- Returns:
- a new response.
-
serverError
Create a new RestResponse with an server error status.- Returns:
- a new response.
-
created
Create a new RestResponse 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 (seeUriInfo.getRequestUri()
).- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if location isnull
.
-
accepted
Create a new RestResponse with an ACCEPTED status.- Returns:
- a new response.
-
accepted
Create a new RestResponse with an ACCEPTED status that contains a representation. It is the callers responsibility to wrap the actual entity withGenericEntity
if preservation of its generic type is required.- Parameters:
entity
- the representation entity data.- Returns:
- a new response.
-
noContent
Create a new RestResponse for an empty response.- Returns:
- a new response.
-
notModified
Create a new RestResponse with a not-modified status.- Returns:
- a new response.
-
notModified
Create a new RestResponse with a not-modified status.- Parameters:
tag
- a tag for the unmodified entity.- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if tag isnull
.
-
notModified
Create a new RestResponse with a not-modified status and a strong entity tag. This is a shortcut fornotModified(new EntityTag(value))
.- Parameters:
tag
- the string content of a strong entity tag. The runtime will quote the supplied value when creating the header.- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if tag isnull
.
-
seeOther
Create a new RestResponse 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 (seeUriInfo.getBaseUri()
).- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if location isnull
.
-
temporaryRedirect
Create a new RestResponse 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 (seeUriInfo.getBaseUri()
).- Returns:
- a new response.
- Throws:
IllegalArgumentException
- if location isnull
.
-
notAcceptable
public static <IGNORED> RestResponse<IGNORED> notAcceptable(List<jakarta.ws.rs.core.Variant> variants) Create a new RestResponse 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.
-
notFound
Create a new RestResponse for a not found response.- Returns:
- a new response.
-