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'>
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'>
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 * <h5 class='section'>See Also:</h5><ul>
068 *    <li class='link'><a class="doclink" href="../../../../../index.html#juneau-rest-common">juneau-rest-common</a>
069 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
070 * </ul>
071 *
072 * @serial exclude
073 */
074@Header("Expect")
075public class Expect extends BasicStringHeader {
076
077   //-----------------------------------------------------------------------------------------------------------------
078   // Static
079   //-----------------------------------------------------------------------------------------------------------------
080
081   private static final long serialVersionUID = 1L;
082   private static final String NAME = "Expect";
083
084   /**
085    * Static creator.
086    *
087    * @param value
088    *    The header value.
089    *    <br>Can be <jk>null</jk>.
090    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
091    */
092   public static Expect of(String value) {
093      return value == null ? null : new Expect(value);
094   }
095
096   /**
097    * Static creator with delayed value.
098    *
099    * <p>
100    * Header value is re-evaluated on each call to {@link #getValue()}.
101    *
102    * @param value
103    *    The supplier of the header value.
104    *    <br>Can be <jk>null</jk>.
105    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
106    */
107   public static Expect of(Supplier<String> value) {
108      return value == null ? null : new Expect(value);
109   }
110
111   //-----------------------------------------------------------------------------------------------------------------
112   // Instance
113   //-----------------------------------------------------------------------------------------------------------------
114
115   /**
116    * Constructor.
117    *
118    * @param value
119    *    The header value.
120    *    <br>Can be <jk>null</jk>.
121    */
122   public Expect(String value) {
123      super(NAME, value);
124   }
125
126   /**
127    * Constructor with delayed value.
128    *
129    * <p>
130    * Header value is re-evaluated on each call to {@link #getValue()}.
131    *
132    * @param value
133    *    The supplier of the header value.
134    *    <br>Can be <jk>null</jk>.
135    */
136   public Expect(Supplier<String> value) {
137      super(NAME, value);
138   }
139}