javax.ws.rs.core
Interface Request

public interface Request

An injectable helper for request processing, all methods throw an IllegalStateException if called outside the scope of a request (e.g. from a provider constructor). Precondition processing (see the evaluatePreconditions methods) can result in either a null return value to indicate that preconditions have been met and that the request should continue, or a non-null return value to indicate that preconditions were not met. In the event that preconditions were not met, the returned ResponseBuilder instance will have an appropriate status and will also include a Vary header if the selectVariant(List) method was called prior to to calling evaluatePreconditions. It is the responsibility of the caller to check the status and add additional metadata if required. E.g., see HTTP/1.1, section 10.3.5 for details of the headers that are expected to accompany a 304 Not Modified response.

Since:

1.0

Author:

Paul Sandoz, Marc Hadley, Marek Potociar

See Also:

Request.RequestBuilder

Nested Class Summary

static interface

Request.RequestBuilder An interface used to build Request instances, typically used in JAX-RS filters.

Method Summary

void	bufferEntity() Buffer the message entity.
void	close() Close the message entity input stream (if available and open).
Response.ResponseBuilder	evaluatePreconditions() Evaluate request preconditions for a resource that does not currently exist.
Response.ResponseBuilder	evaluatePreconditions(Date lastModified) Evaluate request preconditions based on the passed in value.
Response.ResponseBuilder	evaluatePreconditions(Date lastModified, EntityTag eTag) Evaluate request preconditions based on the passed in value.
Response.ResponseBuilder	evaluatePreconditions(EntityTag eTag) Evaluate request preconditions based on the passed in value.
Object	getEntity() Get the message entity Java instance.
RequestHeaders	getHeaders() Get the request message headers.
String	getMethod() Get the request method, e.g.
Map<String,Object>	getProperties() Get a mutable map of request-scoped properties that can be used for communication between different request/response processing components.
URI	getUri() Get the absolute request URI.
boolean	hasEntity() Check if there is an entity available in the request.
boolean	isEntityRetrievable() Check if the entity instance is present and available for a retrieval via getEntity().
<T> T	readEntity(Class<T> type) Read the message entity as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
<T> T	readEntity(Class<T> type, Annotation[] annotations) Read the message entity as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
<T> T	readEntity(GenericType<T> entityType) Read the message entity as an instance of specified (generic) Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
<T> T	readEntity(GenericType<T> entityType, Annotation[] annotations) Read the message entity as an instance of specified (generic) Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type.
Variant	selectVariant(List<Variant> variants) Select the representation variant that best matches the request.

Method Detail

getMethod

String getMethod()

Get the request method, e.g. GET, POST, etc.

Returns:

the request method.

See Also:

HttpMethod

getHeaders

RequestHeaders getHeaders()

Get the request message headers. This method never returns null.

Returns:

request message headers. Returned headers may be empty but never null.

Since:

2.0

See Also:

RuntimeDelegate.HeaderDelegate

getUri

URI getUri()

Get the absolute request URI. This includes query parameters and any supplied fragment.

Returns:

the absolute request URI.

Since:

2.0

getEntity

Object getEntity()

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

Returns:

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

Throws:

IllegalStateException - in case the existing message entity is not retrievable as a Java type. This is typically the case (on the server side) when the entity input stream has not been read as a Java type using one of the readEntity(...) methods yet.

MessageProcessingException - if the entity was previously fully consumed as an input stream.

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.GenericType), bufferEntity(), MessageBodyWriter

readEntity

<T> T readEntity(Class<T> type)
             throws MessageProcessingException

Read the message entity as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Returns null if the message does not contain an entity body. Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream (if open) and makes the entity available for retrieval.

A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). If the message has previously been read as an instance of a different Java type, invoking this method will cause the cached entity instance to be serialized into a temporary input stream using a compatible MessageBodyWriter and then read again from the stream. This operation is thus potentially expensive and should be used with care.

Note that a message entity can also be read as a raw entity input stream, in which case it will be fully consumed once the reading from the entity input stream is finished. Once the entity is read as an input stream, any subsequent calls to one of the readEntity(...) methods or getEntity() method on the same message instance will result in a MessageProcessingException being thrown. It is up to the consumer of the entity input stream to ensure that consuming the stream is properly mitigated (e.g. by substituting the consumed response instance with a new one etc.).

Type Parameters:

T - entity instance Java type.

Parameters:

type - the type of entity.

Returns:

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

Throws:

MessageProcessingException - if the content of the message cannot be mapped to an entity of the requested type or if the entity input stream was previously directly consumed by invoking readEntity(InputStream.class).

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(java.lang.Class, java.lang.annotation.Annotation[]), readEntity(javax.ws.rs.core.GenericType), readEntity(javax.ws.rs.core.GenericType, java.lang.annotation.Annotation[]), bufferEntity(), close(), MessageBodyWriter, MessageBodyReader

readEntity

<T> T readEntity(GenericType<T> entityType)
             throws MessageProcessingException

Read the message entity as an instance of specified (generic) Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Returns null if the message does not contain an entity body. Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream (if open) and makes the entity available for retrieval.

A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). If the message has previously been read as an instance of a different Java type, invoking this method will cause the cached entity instance to be serialized into a temporary input stream using a compatible MessageBodyWriter and then read again from the stream. This operation is thus potentially expensive and should be used with care.

Note that a message entity can also be read as a raw entity input stream, in which case it will be fully consumed once the reading from the entity input stream is finished. Once the entity is read as an input stream, any subsequent calls to one of the readEntity(...) methods or getEntity() method on the same message instance will result in a MessageProcessingException being thrown. It is up to the consumer of the entity input stream to ensure that consuming the stream is properly mitigated (e.g. by substituting the consumed response instance with a new one etc.).

Type Parameters:

T - entity instance Java type.

Parameters:

entityType - the type of entity; may be generic.

Returns:

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

Throws:

MessageProcessingException - if the content of the message cannot be mapped to an entity of the requested type or if the entity input stream was previously directly consumed by invoking readEntity(InputStream.class).

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(javax.ws.rs.core.GenericType, java.lang.annotation.Annotation[]), readEntity(java.lang.Class), readEntity(java.lang.Class, java.lang.annotation.Annotation[]), bufferEntity(), close(), MessageBodyWriter, MessageBodyReader

readEntity

<T> T readEntity(Class<T> type,
                 Annotation[] annotations)
             throws MessageProcessingException

Read the message entity as an instance of specified Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Returns null if the message does not contain an entity body. Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream (if open) and makes the entity available for retrieval.

A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). If the message has previously been read as an instance of a different Java type, invoking this method will cause the cached entity instance to be serialized into a temporary input stream using a compatible MessageBodyWriter and then read again from the stream. This operation is thus potentially expensive and should be used with care.

Note that a message entity can also be read as a raw entity input stream, in which case it will be fully consumed once the reading from the entity input stream is finished. Once the entity is read as an input stream, any subsequent calls to one of the readEntity(...) methods or getEntity() method on the same message instance will result in a MessageProcessingException being thrown. It is up to the consumer of the entity input stream to ensure that consuming the stream is properly mitigated (e.g. by substituting the consumed response instance with a new one etc.).

Type Parameters:

T - entity instance Java type.

Parameters:

type - the type of entity.

annotations - annotations that will be passed to the MessageBodyReader.

Returns:

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

Throws:

MessageProcessingException - if the content of the message cannot be mapped to an entity of the requested type or if the entity input stream was previously directly consumed by invoking readEntity(InputStream.class).

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.GenericType), readEntity(javax.ws.rs.core.GenericType, java.lang.annotation.Annotation[]), bufferEntity(), close(), MessageBodyWriter, MessageBodyReader

readEntity

<T> T readEntity(GenericType<T> entityType,
                 Annotation[] annotations)
             throws MessageProcessingException

Read the message entity as an instance of specified (generic) Java type using a MessageBodyReader that supports mapping the message entity stream onto the requested type. Returns null if the message does not contain an entity body. Unless the supplied entity type is an input stream, this method automatically closes the consumed response entity stream (if open) and makes the entity available for retrieval.

A non-null message instance returned from this method will be cached for subsequent retrievals via getEntity(). If the message has previously been read as an instance of a different Java type, invoking this method will cause the cached entity instance to be serialized into a temporary input stream using a compatible MessageBodyWriter and then read again from the stream. This operation is thus potentially expensive and should be used with care.

Note that a message entity can also be read as a raw entity input stream, in which case it will be fully consumed once the reading from the entity input stream is finished. Once the entity is read as an input stream, any subsequent calls to one of the readEntity(...) methods or getEntity() method on the same message instance will result in a MessageProcessingException being thrown. It is up to the consumer of the entity input stream to ensure that consuming the stream is properly mitigated (e.g. by substituting the consumed response instance with a new one etc.).

Type Parameters:

T - entity instance Java type.

Parameters:

entityType - the type of entity; may be generic.

annotations - annotations that will be passed to the MessageBodyReader.

Returns:

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

Throws:

MessageProcessingException - if the content of the message cannot be mapped to an entity of the requested type or if the entity input stream was previously directly consumed by invoking readEntity(InputStream.class).

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(javax.ws.rs.core.GenericType), readEntity(java.lang.Class), readEntity(java.lang.Class, java.lang.annotation.Annotation[]), bufferEntity(), close(), MessageBodyWriter, MessageBodyReader

hasEntity

boolean hasEntity()

Check if there is an entity available in the request. The method returns true if the entity is present, returns false otherwise.

In case the message contained an entity, but it was already consumed as an input stream via readEntity(InputStream.class), the method returns false.

Returns:

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

Since:

2.0

See Also:

isEntityRetrievable(), getEntity(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.GenericType)

isEntityRetrievable

boolean isEntityRetrievable()

Check if the entity instance is present and available for a retrieval via getEntity(). The method returns true if the entity is retrievable, returns false in case there is no entity associated with the message or if the existing message entity is not available as a Java type. This is typically the case (on the server side) when the entity input stream has not been consumed using one of the readEntity(...) methods yet.

Note that even though entity buffering closes the original entity input stream, the buffered entity may still not be retrievable, unless the buffered data was previously read using one of the readEntity(...) methods.

Returns:

true if there is a retrievable message entity instance present, false otherwise.

Since:

2.0

See Also:

hasEntity(), getEntity(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.GenericType), bufferEntity()

bufferEntity

void bufferEntity()
                  throws MessageProcessingException

Buffer the message entity. In case the message entity input stream is open, all the bytes of the original entity input stream are read and stored in memory. The original entity input stream is automatically closed as part of the operation.

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.

Note that even though entity buffering closes the original entity input stream, the buffered entity may still not be retrievable, unless the buffered data was previously read using one of the readEntity(...) methods.

Throws:

MessageProcessingException - if there is an error buffering the message entity.

Since:

2.0

See Also:

hasEntity(), isEntityRetrievable(), getEntity(), readEntity(java.lang.Class), readEntity(javax.ws.rs.core.GenericType), close()

close

void close()
           throws MessageProcessingException

Close the message entity input stream (if available and open). This operation is idempotent, i.e. it can be invoked multiple times with the same effect which also means that calling the close() method on an already closed message instance is legal and has no further effect.

If the close() method is invoked before the message entity has been fully read from the input stream, any subsequent attempt to read the entity will result in an MessageProcessingException being thrown.

Closing an instance that has already been consumed has no effect. Similarly, closing an instance with no entity has not effect.

Throws:

MessageProcessingException - if there is an error closing the response.

Since:

2.0

See Also:

readEntity(java.lang.Class), readEntity(javax.ws.rs.core.GenericType)

getProperties

Map<String,Object> getProperties()

Get a mutable map of request-scoped properties that can be used for communication between different request/response processing components. May be empty, but MUST never be null. In the scope of a single request/response processing, a same property map instance is shared by the following methods:

• getProperties()
• Response.getProperties()
• FilterContext.getProperties()
• InterceptorContext.getProperties()

A request-scoped property is an application-defined property that may be added, removed or modified by any of the components (user, filter, interceptor etc.) that participate in a given request/response processing flow.

On the client side, this property map is initialized by calling Configuration.setProperties(java.util.Map) or Configuration.setProperty(java.lang.String, java.lang.Object) on the configuration object associated with the corresponding request invocation.

On the server side, specifying the initial values is implementation-specific.

If there are no initial properties set, the request-scoped property map is initialized to an empty map.

Returns:

a mutable request-scoped property map.

Since:

2.0

See Also:

Configuration

selectVariant

Variant selectVariant(List<Variant> variants)
                      throws IllegalArgumentException

Select the representation variant that best matches the request. More explicit variants are chosen ahead of less explicit ones. A vary header is computed from the supplied list and automatically added to the response.

Parameters:

variants - a list of Variant that describe all of the available representation variants.

Returns:

the variant that best matches the request.

Throws:

IllegalArgumentException - if variants is empty or null

IllegalStateException - if called outside the scope of a request

See Also:

Variant.VariantListBuilder

evaluatePreconditions

Response.ResponseBuilder evaluatePreconditions(EntityTag eTag)

Evaluate request preconditions based on the passed in value.

Parameters:

eTag - an ETag for the current state of the resource

Returns:

null if the preconditions are met or a ResponseBuilder set with the appropriate status if the preconditions are not met. A returned ResponseBuilder will include an ETag header set with the value of eTag.

Throws:

IllegalArgumentException - if eTag is null

IllegalStateException - if called outside the scope of a request

evaluatePreconditions

Response.ResponseBuilder evaluatePreconditions(Date lastModified)

Evaluate request preconditions based on the passed in value.

Parameters:

lastModified - a date that specifies the modification date of the resource

Returns:

null if the preconditions are met or a ResponseBuilder set with the appropriate status if the preconditions are not met.

Throws:

IllegalArgumentException - if lastModified is null

IllegalStateException - if called outside the scope of a request

evaluatePreconditions

Response.ResponseBuilder evaluatePreconditions(Date lastModified,
                                               EntityTag eTag)

Evaluate request preconditions based on the passed in value.

Parameters:

lastModified - a date that specifies the modification date of the resource

eTag - an ETag for the current state of the resource

Returns:

null if the preconditions are met or a ResponseBuilder set with the appropriate status if the preconditions are not met. A returned ResponseBuilder will include an ETag header set with the value of eTag.

Throws:

IllegalArgumentException - if lastModified or eTag is null

IllegalStateException - if called outside the scope of a request

evaluatePreconditions

Response.ResponseBuilder evaluatePreconditions()

Evaluate request preconditions for a resource that does not currently exist. The primary use of this method is to support the If-Match: * and If-None-Match: * preconditions.

Note that both preconditions If-None-Match: * and If-None-Match: something will always be considered to have been met and it is the applications responsibility to enforce any additional method-specific semantics. E.g. a PUT on a resource that does not exist might succeed whereas a GET on a resource that does not exist would likely result in a 404 response. It would be the responsibility of the application to generate the 404 response.

Returns:

null if the preconditions are met or a ResponseBuilder set with the appropriate status if the preconditions are not met.

Throws:

IllegalStateException - if called outside the scope of a request

Since:

1.1