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 static org.apache.juneau.http.Constants.*; 016 017import java.util.function.*; 018 019import org.apache.juneau.http.annotation.*; 020import org.apache.juneau.internal.*; 021 022/** 023 * Represents a parsed <l>Connection</l> HTTP request header. 024 * 025 * <p> 026 * Control options for the current connection and list of hop-by-hop request fields. 027 * 028 * <h5 class='figure'>Example</h5> 029 * <p class='bcode w800'> 030 * Connection: keep-alive 031 * Connection: Upgrade 032 * </p> 033 * 034 * <h5 class='topic'>RFC2616 Specification</h5> 035 * 036 * The Connection general-header field allows the sender to specify options that are desired for that particular 037 * connection and MUST NOT be communicated by proxies over further connections. 038 * 039 * <p> 040 * The Connection header has the following grammar: 041 * <p class='bcode w800'> 042 * Connection = "Connection" ":" 1#(connection-token) 043 * connection-token = token 044 * </p> 045 * 046 * <p> 047 * HTTP/1.1 proxies MUST parse the Connection header field before a message is forwarded and, for each connection-token 048 * in this field, remove any header field(s) from the message with the same name as the connection-token. 049 * Connection options are signaled by the presence of a connection-token in the Connection header field, not by any 050 * corresponding additional header field(s), since the additional header field may not be sent if there are no 051 * parameters associated with that connection option. 052 * 053 * <p> 054 * Message headers listed in the Connection header MUST NOT include end-to-end headers, such as Cache-Control. 055 * 056 * <p> 057 * HTTP/1.1 defines the "close" connection option for the sender to signal that the connection will be closed after 058 * completion of the response. 059 * For example... 060 * <p class='bcode w800'> 061 * Connection: close 062 * </p> 063 * <p> 064 * ...in either the request or the response header fields indicates that the connection SHOULD NOT be considered 065 * `persistent' (section 8.1) after the current request/response is complete. 066 * 067 * <p> 068 * HTTP/1.1 applications that do not support persistent connections MUST include the "close" connection option in 069 * every message. 070 * 071 * <p> 072 * A system receiving an HTTP/1.0 (or lower-version) message that includes a Connection header MUST, for each 073 * connection-token in this field, remove and ignore any header field(s) from the message with the same name as the 074 * connection-token. 075 * This protects against mistaken forwarding of such header fields by pre-HTTP/1.1 proxies. 076 * See section 19.6.2. 077 * 078 * <ul class='seealso'> 079 * <li class='extlink'>{@doc ExtRFC2616} 080 * </ul> 081 */ 082@Header("Connection") 083public class Connection extends BasicStringHeader { 084 085 private static final long serialVersionUID = 1L; 086 087 private static final Cache<String,Connection> CACHE = new Cache<>(NOCACHE, CACHE_MAX_SIZE); 088 089 /** 090 * Returns a parsed and cached header. 091 * 092 * @param value 093 * The header value. 094 * @return A cached {@link Connection} object. 095 */ 096 public static Connection of(String value) { 097 if (value == null) 098 return null; 099 Connection x = CACHE.get(value); 100 if (x == null) 101 x = CACHE.put(value, new Connection(value)); 102 return x; 103 } 104 105 /** 106 * Convenience creator. 107 * 108 * @param value 109 * The header value. 110 * <br>Can be any of the following: 111 * <ul> 112 * <li>{@link String} 113 * <li>Anything else - Converted to <c>String</c> then parsed. 114 * </ul> 115 * @return A new {@link Connection} object. 116 */ 117 public static Connection of(Object value) { 118 if (value == null) 119 return null; 120 return new Connection(value); 121 } 122 123 /** 124 * Convenience creator using supplier. 125 * 126 * <p> 127 * Header value is re-evaluated on each call to {@link #getValue()}. 128 * 129 * @param value 130 * The header value supplier. 131 * <br>Can be any of the following: 132 * <ul> 133 * <li>{@link String} 134 * <li>Anything else - Converted to <c>String</c> then parsed. 135 * </ul> 136 * @return A new {@link Connection} object. 137 */ 138 public static Connection of(Supplier<?> value) { 139 if (value == null) 140 return null; 141 return new Connection(value); 142 } 143 144 /** 145 * Constructor. 146 * 147 * @param value 148 * The header value. 149 * <br>Can be any of the following: 150 * <ul> 151 * <li>{@link String} 152 * <li>Anything else - Converted to <c>String</c> then parsed. 153 * <li>A {@link Supplier} of anything on this list. 154 * </ul> 155 */ 156 public Connection(Object value) { 157 super("Connection", value); 158 } 159 160 /** 161 * Constructor 162 * 163 * @param value 164 * The header value. 165 */ 166 public Connection(String value) { 167 this((Object)value); 168 } 169 170 /** 171 * Returns <jk>true</jk> if the header value is <c>close</c>. 172 * 173 * @return <jk>true</jk> if the header value is <c>close</c>. 174 */ 175 public boolean isClose() { 176 return eqIC("close"); 177 } 178 179 /** 180 * Returns <jk>true</jk> if the header value is <c>keep-alive</c>. 181 * 182 * @return <jk>true</jk> if the header value is <c>keep-alive</c>. 183 */ 184 public boolean isKeepAlive() { 185 return eqIC("keep-alive"); 186 } 187 188 /** 189 * Returns <jk>true</jk> if the header value is <c>upgrade</c>. 190 * 191 * @return <jk>true</jk> if the header value is <c>upgrade</c>. 192 */ 193 public boolean isUpgrade() { 194 return eqIC("upgrade"); 195 } 196}