001 /*
002 * The contents of this file are subject to the terms
003 * of the Common Development and Distribution License
004 * (the "License"). You may not use this file except
005 * in compliance with the License.
006 *
007 * You can obtain a copy of the license at
008 * http://www.opensource.org/licenses/cddl1.php
009 * See the License for the specific language governing
010 * permissions and limitations under the License.
011 */
012
013 /*
014 * Request.java
015 *
016 * Created on September 27, 2007, 5:39 PM
017 *
018 */
019
020 package javax.ws.rs.core;
021
022 import java.util.Date;
023 import java.util.List;
024 import javax.ws.rs.core.Response.ResponseBuilder;
025
026 /**
027 * An injectable helper for request processing, all methods throw
028 * java.lang.IllegalStateException if called outside the scope of a request
029 * (e.g. from a provider constructor).
030 *
031 * Precondition processing (see the <code>evaluatePreconditions</code> methods)
032 * can result in either a <code>null</code> return value to indicate that
033 * preconditions have been met and that the request should continue, or
034 * a non-null return value to indicate that preconditions were not met. In the
035 * event that preconditions were not met, the returned <code>ResponseBuilder</code>
036 * instance will have an appropriate status and will also include a <code>Vary</code>
037 * header if the {@link #selectVariant} method was called prior to to calling
038 * <code>evaluatePreconditions</code>. It is the responsibility of the caller
039 * to check the status and add additional metadata if required. E.g., see
040 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5">HTTP/1.1, section 10.3.5</a>
041 * for details of the headers that are expected to accompany a <code>304 Not Modified</code>
042 * response.
043 */
044 public interface Request {
045
046 /**
047 * Get the request method, e.g. GET, POST, etc.
048 * @return the request method
049 * @see javax.ws.rs.HttpMethod
050 */
051 String getMethod();
052
053 /**
054 * Select the representation variant that best matches the request. More
055 * explicit variants are chosen ahead of less explicit ones. A vary header
056 * is computed from the supplied list and automatically added to the
057 * response.
058 *
059 * @param variants a list of Variant that describe all of the
060 * available representation variants.
061 * @return the variant that best matches the request.
062 * @see Variant.VariantListBuilder
063 * @throws java.lang.IllegalArgumentException if variants is empty or null
064 * @throws java.lang.IllegalStateException if called outside the scope of a request
065 */
066 Variant selectVariant(List<Variant> variants) throws IllegalArgumentException;
067
068 /**
069 * Evaluate request preconditions based on the passed in value.
070 *
071 * @param eTag an ETag for the current state of the resource
072 * @return null if the preconditions are met or a ResponseBuilder set with
073 * the appropriate status if the preconditions are not met. A returned
074 * ResponseBuilder will include an ETag header set with the value of eTag.
075 * @throws java.lang.IllegalArgumentException if eTag is null
076 * @throws java.lang.IllegalStateException if called outside the scope of a request
077 */
078 ResponseBuilder evaluatePreconditions(EntityTag eTag);
079
080 /**
081 * Evaluate request preconditions based on the passed in value.
082 *
083 * @param lastModified a date that specifies the modification date of the resource
084 * @return null if the preconditions are met or a ResponseBuilder set with
085 * the appropriate status if the preconditions are not met.
086 * @throws java.lang.IllegalArgumentException if lastModified is null
087 * @throws java.lang.IllegalStateException if called outside the scope of a request
088 */
089 ResponseBuilder evaluatePreconditions(Date lastModified);
090
091 /**
092 * Evaluate request preconditions based on the passed in value.
093 *
094 * @param lastModified a date that specifies the modification date of the resource
095 * @param eTag an ETag for the current state of the resource
096 * @return null if the preconditions are met or a ResponseBuilder set with
097 * the appropriate status if the preconditions are not met. A returned
098 * ResponseBuilder will include an ETag header set with the value of eTag.
099 * @throws java.lang.IllegalArgumentException if lastModified or eTag is null
100 * @throws java.lang.IllegalStateException if called outside the scope of a request
101 */
102 ResponseBuilder evaluatePreconditions(Date lastModified, EntityTag eTag);
103
104 /**
105 * Evaluate request preconditions for a resource that does not currently
106 * exist. The primary use of this method is to support the {@link <a
107 * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24">
108 * If-Match: *</a>} and {@link <a
109 * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26">
110 * If-None-Match: *</a>} preconditions.
111 *
112 * <p>Note that both preconditions <code>If-None-Match: *</code> and
113 * <code>If-None-Match: <i>something</i></code> will always be considered to
114 * have been met and it is the applications responsibility
115 * to enforce any additional method-specific semantics. E.g. a
116 * <code>PUT</code> on a resource that does not exist might succeed whereas
117 * a <code>GET</code> on a resource that does not exist would likely result
118 * in a 404 response. It would be the responsibility of the application to
119 * generate the 404 response.</p>
120 *
121 * @return null if the preconditions are met or a ResponseBuilder set with
122 * the appropriate status if the preconditions are not met.
123 * @throws java.lang.IllegalStateException if called outside the scope of
124 * a request
125 */
126 ResponseBuilder evaluatePreconditions();
127 }