javax.ws.rs.core.Request Maven / Gradle / Ivy
/*
* 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();
}