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.classic.header;
018
019import java.util.function.*;
020
021import org.apache.juneau.http.*;
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/JuneauRestCommon">juneau-rest-common</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")
092@SuppressWarnings({
093   "java:S9149" // Public Juneau DSL factory; hiding parent of()/create() is intentional.
094})
095public class Upgrade extends BasicCsvHeader {
096   private static final long serialVersionUID = 1L;
097   private static final String NAME = "Upgrade";
098
099   /**
100    * Static creator.
101    *
102    * @param value
103    *    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 Upgrade of(String value) {
108      return value == null ? null : new Upgrade(value);
109   }
110
111   /**
112    * Static creator.
113    *
114    * @param value
115    *    The header value.
116    *    <br>Can be <jk>null</jk>.
117    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
118    */
119   public static Upgrade of(String...value) {
120      return value == null ? null : new Upgrade(value);
121   }
122
123   /**
124    * Static creator for two CSV tokens.
125    *
126    * <p>
127    * This distinct fixed-arity overload ensures two literal {@link String} arguments resolve to this class's own
128    * factory (returning an {@link Upgrade}) rather than the inherited fixed-arity {@link BasicCsvHeader#of(String,String)},
129    * which Java overload resolution would otherwise prefer.
130    *
131    * @param value1 The first CSV token.
132    * @param value2 The second CSV token.
133    * @return A new header bean.
134    */
135   public static Upgrade of(String value1, String value2) {
136      return new Upgrade(value1, value2);
137   }
138
139   /**
140    * Static creator with delayed value.
141    *
142    * <p>
143    * Header value is re-evaluated on each call to {@link #getValue()}.
144    *
145    * @param value
146    *    The supplier of the header value.
147    *    <br>Can be <jk>null</jk>.
148    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
149    */
150   public static Upgrade of(Supplier<String[]> value) {
151      return value == null ? null : new Upgrade(value);
152   }
153
154   /**
155    * Constructor.
156    *
157    * @param value
158    *    The header value.
159    *    <br>Can be <jk>null</jk> to create a header with no value.
160    */
161   public Upgrade(String value) {
162      super(NAME, value);
163   }
164
165   /**
166    * Constructor.
167    *
168    * @param value
169    *    The header value.
170    *    <br>Can be <jk>null</jk> or empty to create a header with no value.
171    */
172   public Upgrade(String...value) {
173      super(NAME, value);
174   }
175
176   /**
177    * Constructor with delayed value.
178    *
179    * <p>
180    * Header value is re-evaluated on each call to {@link #getValue()}.
181    *
182    * @param value
183    *    The supplier of the header value.
184    *    <br>Can be <jk>null</jk> to create a header with no value.
185    */
186   public Upgrade(Supplier<String[]> value) {
187      super(NAME, value);
188   }
189}