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