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.*; 016import java.util.function.*; 017 018import org.apache.juneau.http.annotation.*; 019 020/** 021 * Represents a parsed <l>Upgrade</l> HTTP request header. 022 * 023 * <p> 024 * Ask the client to upgrade to another protocol. 025 * 026 * <h5 class='figure'>Example</h5> 027 * <p class='bcode w800'> 028 * Upgrade: HTTP/2.0, HTTPS/1.3, IRC/6.9, RTA/x11, websocket 029 * </p> 030 * 031 * <h5 class='topic'>RFC2616 Specification</h5> 032 * 033 * The Upgrade general-header allows the client to specify what additional communication protocols it supports and 034 * would like to use if the server finds it appropriate to switch protocols. 035 * The server MUST use the Upgrade header field within a 101 (Switching Protocols) response to indicate which 036 * protocol(s) are being switched. 037 * 038 * <p class='bcode w800'> 039 * Upgrade = "Upgrade" ":" 1#product 040 * </p> 041 * 042 * <p> 043 * For example, 044 * <p class='bcode w800'> 045 * Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 046 * </p> 047 * 048 * <p> 049 * The Upgrade header field is intended to provide a simple mechanism for transition from HTTP/1.1 to some other, 050 * incompatible protocol. 051 * It does so by allowing the client to advertise its desire to use another protocol, such as a later version of HTTP 052 * with a higher major version number, even though the current request has been made using HTTP/1.1. 053 * This eases the difficult transition between incompatible protocols by allowing the client to initiate a request in 054 * the more commonly supported protocol while indicating to the server that it would like to use a "better" protocol if 055 * available (where "better" is determined by the server, possibly according to the nature of the method and/or resource 056 * being requested). 057 * 058 * <p> 059 * The Upgrade header field only applies to switching application-layer protocols upon the existing transport-layer 060 * connection. 061 * Upgrade cannot be used to insist on a protocol change; its acceptance and use by the server is optional. 062 * The capabilities and nature of the application-layer communication after the protocol change is entirely dependent 063 * upon the new protocol chosen, although the first action after changing the protocol MUST be a response to the initial 064 * HTTP request containing the Upgrade header field. 065 * 066 * <p> 067 * The Upgrade header field only applies to the immediate connection. 068 * Therefore, the upgrade keyword MUST be supplied within a Connection header field (section 14.10) whenever Upgrade is 069 * present in an HTTP/1.1 message. 070 * 071 * <p> 072 * The Upgrade header field cannot be used to indicate a switch to a protocol on a different connection. 073 * For that purpose, it is more appropriate to use a 301, 302, 303, or 305 redirection response. 074 * 075 * <p> 076 * This specification only defines the protocol name "HTTP" for use by the family of Hypertext Transfer Protocols, as 077 * defined by the HTTP version rules of section 3.1 and future updates to this specification. 078 * Any token can be used as a protocol name; however, it will only be useful if both the client and server associate 079 * the name with the same protocol. 080 * 081 * <ul class='seealso'> 082 * <li class='extlink'>{@doc ExtRFC2616} 083 * </ul> 084 */ 085@Header("Upgrade") 086public class Upgrade extends BasicCsvArrayHeader { 087 088 private static final long serialVersionUID = 1L; 089 090 /** 091 * Convenience creator. 092 * 093 * @param value 094 * The header value. 095 * <br>Can be any of the following: 096 * <ul> 097 * <li><c>String</c> - A comma-delimited string. 098 * <li><c>String[]</c> - A pre-parsed value. 099 * <li>Any other array type - Converted to <c>String[]</c>. 100 * <li>Any {@link Collection} - Converted to <c>String[]</c>. 101 * <li>Anything else - Converted to <c>String</c>. 102 * </ul> 103 * @return The parsed <c>Upgrade</c> header, or <jk>null</jk> if the value was null. 104 */ 105 public static Upgrade of(Object value) { 106 if (value == null) 107 return null; 108 return new Upgrade(value); 109 } 110 111 /** 112 * Convenience creator using supplier. 113 * 114 * <p> 115 * Header value is re-evaluated on each call to {@link #getValue()}. 116 * 117 * @param value 118 * The header value supplier. 119 * <br>Can be any of the following: 120 * <ul> 121 * <li><c>String</c> - A comma-delimited string. 122 * <li><c>String[]</c> - A pre-parsed value. 123 * <li>Any other array type - Converted to <c>String[]</c>. 124 * <li>Any {@link Collection} - Converted to <c>String[]</c>. 125 * <li>Anything else - Converted to <c>String</c>. 126 * </ul> 127 * @return The parsed <c>Upgrade</c> header, or <jk>null</jk> if the value was null. 128 */ 129 public static Upgrade of(Supplier<?> value) { 130 if (value == null) 131 return null; 132 return new Upgrade(value); 133 } 134 135 /** 136 * Constructor. 137 * 138 * @param value 139 * The header value. 140 * <br>Can be any of the following: 141 * <ul> 142 * <li><c>String</c> - A comma-delimited string. 143 * <li><c>String[]</c> - A pre-parsed value. 144 * <li>Any other array type - Converted to <c>String[]</c>. 145 * <li>Any {@link Collection} - Converted to <c>String[]</c>. 146 * <li>Anything else - Converted to <c>String</c>. 147 * <li>A {@link Supplier} of anything on this list. 148 * </ul> 149 */ 150 public Upgrade(Object value) { 151 super("Upgrade", value); 152 } 153 154 /** 155 * Constructor 156 * 157 * @param value 158 * The header value. 159 */ 160 public Upgrade(String value) { 161 this((Object)value); 162 } 163}