javax.ws.rs.core.Request Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of ehcache Show documentation
Show all versions of ehcache Show documentation
Ehcache is an open source, standards-based cache used to boost performance,
offload the database and simplify scalability. Ehcache is robust, proven and full-featured and
this has made it the most widely-used Java-based cache.
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the "License"). You may not use this file except
* in compliance with the License.
*
* You can obtain a copy of the license at
* http://www.opensource.org/licenses/cddl1.php
* See the License for the specific language governing
* permissions and limitations under the License.
*/
/*
* Request.java
*
* Created on September 27, 2007, 5:39 PM
*
*/
package javax.ws.rs.core;
import java.util.Date;
import java.util.List;
import javax.ws.rs.core.Response.ResponseBuilder;
/**
* An injectable helper for request processing, all methods throw
* java.lang.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 {@link #selectVariant} 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.
*/
public interface Request {
/**
* Get the request method, e.g. GET, POST, etc.
* @return the request method
* @see javax.ws.rs.HttpMethod
*/
String getMethod();
/**
* 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.
*
* @param variants a list of Variant that describe all of the
* available representation variants.
* @return the variant that best matches the request.
* @see Variant.VariantListBuilder
* @throws java.lang.IllegalArgumentException if variants is empty or null
* @throws java.lang.IllegalStateException if called outside the scope of a request
*/
Variant selectVariant(List variants) throws IllegalArgumentException;
/**
* Evaluate request preconditions based on the passed in value.
*
* @param eTag an ETag for the current state of the resource
* @return 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 java.lang.IllegalArgumentException if eTag is null
* @throws java.lang.IllegalStateException if called outside the scope of a request
*/
ResponseBuilder evaluatePreconditions(EntityTag eTag);
/**
* Evaluate request preconditions based on the passed in value.
*
* @param lastModified a date that specifies the modification date of the resource
* @return null if the preconditions are met or a ResponseBuilder set with
* the appropriate status if the preconditions are not met.
* @throws java.lang.IllegalArgumentException if lastModified is null
* @throws java.lang.IllegalStateException if called outside the scope of a request
*/
ResponseBuilder evaluatePreconditions(Date lastModified);
/**
* Evaluate request preconditions based on the passed in value.
*
* @param lastModified a date that specifies the modification date of the resource
* @param eTag an ETag for the current state of the resource
* @return 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 java.lang.IllegalArgumentException if lastModified or eTag is null
* @throws java.lang.IllegalStateException if called outside the scope of a request
*/
ResponseBuilder evaluatePreconditions(Date lastModified, EntityTag eTag);
/**
* Evaluate request preconditions for a resource that does not currently
* exist. The primary use of this method is to support the {@link
* If-Match: *} and {@link
* 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.
*
* @return null if the preconditions are met or a ResponseBuilder set with
* the appropriate status if the preconditions are not met.
* @throws java.lang.IllegalStateException if called outside the scope of
* a request
*/
ResponseBuilder evaluatePreconditions();
}