001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.http.header;
018
019import java.util.function.*;
020
021import org.apache.juneau.http.annotation.*;
022
023/**
024 * Represents a parsed <l>Upgrade</l> HTTP request header.
025 *
026 * <p>
027 * Ask the client to upgrade to another protocol.
028 *
029 * <h5 class='figure'>Example</h5>
030 * <p class='bcode'>
031 *    Upgrade: HTTP/2.0, HTTPS/1.3, IRC/6.9, RTA/x11, websocket
032 * </p>
033 *
034 * <h5 class='topic'>RFC2616 Specification</h5>
035 *
036 * The Upgrade general-header allows the client to specify what additional communication protocols it supports and
037 * would like to use if the server finds it appropriate to switch protocols.
038 * The server MUST use the Upgrade header field within a 101 (Switching Protocols) response to indicate which
039 * protocol(s) are being switched.
040 *
041 * <p class='bcode'>
042 *    Upgrade        = "Upgrade" ":" 1#product
043 * </p>
044 *
045 * <p>
046 * For example,
047 * <p class='bcode'>
048 *    Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
049 * </p>
050 *
051 * <p>
052 * The Upgrade header field is intended to provide a simple mechanism for transition from HTTP/1.1 to some other,
053 * incompatible protocol.
054 * It does so by allowing the client to advertise its desire to use another protocol, such as a later version of HTTP
055 * with a higher major version number, even though the current request has been made using HTTP/1.1.
056 * This eases the difficult transition between incompatible protocols by allowing the client to initiate a request in
057 * the more commonly supported protocol while indicating to the server that it would like to use a "better" protocol if
058 * available (where "better" is determined by the server, possibly according to the nature of the method and/or resource
059 * being requested).
060 *
061 * <p>
062 * The Upgrade header field only applies to switching application-layer protocols upon the existing transport-layer
063 * connection.
064 * Upgrade cannot be used to insist on a protocol change; its acceptance and use by the server is optional.
065 * The capabilities and nature of the application-layer communication after the protocol change is entirely dependent
066 * upon the new protocol chosen, although the first action after changing the protocol MUST be a response to the initial
067 * HTTP request containing the Upgrade header field.
068 *
069 * <p>
070 * The Upgrade header field only applies to the immediate connection.
071 * Therefore, the upgrade keyword MUST be supplied within a Connection header field (section 14.10) whenever Upgrade is
072 * present in an HTTP/1.1 message.
073 *
074 * <p>
075 * The Upgrade header field cannot be used to indicate a switch to a protocol on a different connection.
076 * For that purpose, it is more appropriate to use a 301, 302, 303, or 305 redirection response.
077 *
078 * <p>
079 * This specification only defines the protocol name "HTTP" for use by the family of Hypertext Transfer Protocols, as
080 * defined by the HTTP version rules of section 3.1 and future updates to this specification.
081 * Any token can be used as a protocol name; however, it will only be useful if both the client and server associate
082 * the name with the same protocol.
083 *
084 * <h5 class='section'>See Also:</h5><ul>
085 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommonBasics">juneau-rest-common Basics</a>
086 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
087 * </ul>
088 *
089 * @serial exclude
090 */
091@Header("Upgrade")
092public class Upgrade extends BasicCsvHeader {
093
094   //-----------------------------------------------------------------------------------------------------------------
095   // Static
096   //-----------------------------------------------------------------------------------------------------------------
097
098   private static final long serialVersionUID = 1L;
099   private static final String NAME = "Upgrade";
100
101   /**
102    * Static creator.
103    *
104    * @param value
105    *    The header value.
106    *    <br>Can be <jk>null</jk>.
107    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
108    */
109   public static Upgrade of(String value) {
110      return value == null ? null : new Upgrade(value);
111   }
112
113   /**
114    * Static creator.
115    *
116    * @param value
117    *    The header value.
118    *    <br>Can be <jk>null</jk>.
119    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
120    */
121   public static Upgrade of(String...value) {
122      return value == null ? null : new Upgrade(value);
123   }
124
125   /**
126    * Static creator with delayed value.
127    *
128    * <p>
129    * Header value is re-evaluated on each call to {@link #getValue()}.
130    *
131    * @param value
132    *    The supplier of the header value.
133    *    <br>Can be <jk>null</jk>.
134    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
135    */
136   public static Upgrade of(Supplier<String[]> value) {
137      return value == null ? null : new Upgrade(value);
138   }
139
140   //-----------------------------------------------------------------------------------------------------------------
141   // Instance
142   //-----------------------------------------------------------------------------------------------------------------
143
144   /**
145    * Constructor.
146    *
147    * @param value
148    *    The header value.
149    *    <br>Can be <jk>null</jk>.
150    */
151   public Upgrade(String value) {
152      super(NAME, value);
153   }
154
155   /**
156    * Constructor.
157    *
158    * @param value
159    *    The header value.
160    *    <br>Can be <jk>null</jk>.
161    */
162   public Upgrade(String...value) {
163      super(NAME, value);
164   }
165
166   /**
167    * Constructor with delayed value.
168    *
169    * <p>
170    * Header value is re-evaluated on each call to {@link #getValue()}.
171    *
172    * @param value
173    *    The supplier of the header value.
174    *    <br>Can be <jk>null</jk>.
175    */
176   public Upgrade(Supplier<String[]> value) {
177      super(NAME, value);
178   }
179}