001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.http.header;
014
015import java.util.function.*;
016
017import org.apache.juneau.http.annotation.*;
018
019/**
020 * Represents a parsed <l>Expect</l> HTTP request header.
021 *
022 * <p>
023 * Indicates that particular server behaviors are required by the client.
024 *
025 * <h5 class='figure'>Example</h5>
026 * <p class='bcode w800'>
027 *    Expect: 100-continue
028 * </p>
029 *
030 * <h5 class='topic'>RFC2616 Specification</h5>
031 *
032 * The Expect request-header field is used to indicate that particular server behaviors are required by the client.
033 * <p class='bcode w800'>
034 *    Expect       =  "Expect" ":" 1#expectation
035 *    expectation  =  "100-continue" | expectation-extension
036 *    expectation-extension =  token [ "=" ( token | quoted-string )
037 *                             *expect-params ]
038 *    expect-params =  ";" token [ "=" ( token | quoted-string ) ]
039 * </p>
040 *
041 * <p>
042 * A server that does not understand or is unable to comply with any of the expectation values in the Expect field of a
043 * request MUST respond with appropriate error status.
044 * The server MUST respond with a 417 (Expectation Failed) status if any of the expectations cannot be met or, if there
045 * are other problems with the request, some other 4xx status.
046 *
047 * <p>
048 * This header field is defined with extensible syntax to allow for future extensions.
049 * If a server receives a request containing an Expect field that includes an expectation-extension that it does not
050 * support, it MUST respond with a 417 (Expectation Failed) status.
051 *
052 * <p>
053 * Comparison of expectation values is case-insensitive for unquoted tokens (including the 100-continue token), and is
054 * case-sensitive for quoted-string expectation-extensions.
055 *
056 * <p>
057 * The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST return a 417 (Expectation Failed) status if it
058 * receives a request with an expectation that it cannot meet.
059 * However, the Expect request-header itself is end-to-end; it MUST be forwarded if the request is forwarded.
060 *
061 * <p>
062 * Many older HTTP/1.0 and HTTP/1.1 applications do not understand the Expect header.
063 *
064 * <p>
065 * See section 8.2.3 for the use of the 100 (continue) status.
066 *
067 * <ul class='seealso'>
068 *    <li class='extlink'>{@doc ExtRFC2616}
069 * </ul>
070 */
071@Header("Expect")
072public class Expect extends BasicStringHeader {
073
074   private static final long serialVersionUID = 1L;
075
076   /**
077    * Convenience creator.
078    *
079    * @param value
080    *    The header value.
081    *    <br>Can be any of the following:
082    *    <ul>
083    *       <li>{@link String}
084    *       <li>Anything else - Converted to <c>String</c> then parsed.
085    *    </ul>
086    * @return A new {@link Expect} object.
087    */
088   public static Expect of(Object value) {
089      if (value == null)
090         return null;
091      return new Expect(value);
092   }
093
094   /**
095    * Convenience creator using supplier.
096    *
097    * <p>
098    * Header value is re-evaluated on each call to {@link #getValue()}.
099    *
100    * @param value
101    *    The header value supplier.
102    *    <br>Can be any of the following:
103    *    <ul>
104    *       <li>{@link String}
105    *       <li>Anything else - Converted to <c>String</c> then parsed.
106    *    </ul>
107    * @return A new {@link Expect} object.
108    */
109   public static Expect of(Supplier<?> value) {
110      if (value == null)
111         return null;
112      return new Expect(value);
113   }
114
115   /**
116    * Constructor.
117    *
118    * @param value
119    *    The header value.
120    *    <br>Can be any of the following:
121    *    <ul>
122    *       <li>{@link String}
123    *       <li>Anything else - Converted to <c>String</c> then parsed.
124    *       <li>A {@link Supplier} of anything on this list.
125    *    </ul>
126    */
127   public Expect(Object value) {
128      super("Expect", value);
129   }
130
131   /**
132    * Constructor
133    *
134    * @param value
135    *    The header value.
136    */
137   public Expect(String value) {
138      this((Object)value);
139   }
140}