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.*;
020import org.apache.juneau.http.annotation.*;
021import org.apache.juneau.internal.*;
022
023/**
024 * Represents a parsed <l>Accept-Encoding</l> HTTP request header.
025 *
026 * <p>
027 * List of acceptable encodings.
028 *
029 * <h5 class='figure'>Example</h5>
030 * <p class='bcode w800'>
031 *    Accept-Encoding: gzip, deflate
032 * </p>
033 *
034 * <h5 class='topic'>RFC2616 Specification</h5>
035 *
036 * The Accept-Encoding request-header field is similar to Accept, but restricts the content-codings (section 3.5) that
037 * are acceptable in the response.
038 *
039 * <p class='bcode w800'>
040 *    Accept-Encoding  = "Accept-Encoding" ":"
041 *                       1#( codings [ ";" "q" "=" qvalue ] )
042 *    codings          = ( content-coding | "*" )
043 * </p>
044 *
045 * <p>
046 * Examples of its use are:
047 * <p class='bcode w800'>
048 *    Accept-Encoding: compress, gzip
049 *    Accept-Encoding:
050 *    Accept-Encoding: *
051 *    Accept-Encoding: compress;q=0.5, gzip;q=1.0
052 *    Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0
053 * </p>
054 *
055 * <p>
056 * A server tests whether a content-coding is acceptable, according to an Accept-Encoding field, using these rules:
057 * <ol>
058 *    <li>If the content-coding is one of the content-codings listed in the Accept-Encoding field, then it is
059 *       acceptable, unless it is accompanied by a qvalue of 0.
060 *       (As defined in section 3.9, a qvalue of 0 means "not acceptable.")
061 *    <li>The special "*" symbol in an Accept-Encoding field matches any available content-coding not explicitly listed
062 *       in the header field.
063 *    <li>If multiple content-codings are acceptable, then the acceptable content-coding with the highest non-zero
064 *       qvalue is preferred.
065 *    <li>The "identity" content-coding is always acceptable, unless specifically refused because the Accept-Encoding
066 *       field includes "identity;q=0", or because the field includes "*;q=0" and does not explicitly include the
067 *       "identity" content-coding.
068 *       If the Accept-Encoding field-value is empty, then only the "identity" encoding is acceptable.
069 * </ol>
070 *
071 * <p>
072 * If an Accept-Encoding field is present in a request, and if the server cannot send a response which is acceptable
073 * according to the Accept-Encoding header, then the server SHOULD send an error response with the 406 (Not Acceptable)
074 * status code.
075 *
076 * <p>
077 * If no Accept-Encoding field is present in a request, the server MAY assume that the client will accept any content
078 * coding.
079 * In this case, if "identity" is one of the available content-codings, then the server SHOULD use the "identity"
080 * content-coding, unless it has additional information that a different content-coding is meaningful to the client.
081 *
082 * <p>
083 * Note: If the request does not include an Accept-Encoding field, and if the "identity" content-coding is unavailable,
084 * then content-codings commonly understood by HTTP/1.0 clients (i.e.,"gzip" and "compress") are preferred; some older
085 * clients improperly display messages sent with other content-codings.
086 * The server might also make this decision based on information about the particular user-agent or client.
087 *
088 * <p>
089 * Note: Most HTTP/1.0 applications do not recognize or obey qvalues associated with content-codings.
090 * This means that qvalues will not work and are not permitted with x-gzip or x-compress.
091 *
092 * <ul class='seealso'>
093 *    <li class='extlink'>{@doc ExtRFC2616}
094 * </ul>
095 */
096@Header("Accept-Encoding")
097public class AcceptEncoding extends BasicStringRangeArrayHeader {
098
099   private static final long serialVersionUID = 1L;
100
101   private static final Cache<String,AcceptEncoding> CACHE = new Cache<>(NOCACHE, CACHE_MAX_SIZE);
102
103   /**
104    * Returns a parsed and cached header.
105    *
106    * @param value
107    *    The header value.
108    * @return A cached {@link AcceptCharset} object.
109    */
110   public static AcceptEncoding of(String value) {
111      if (value == null)
112         return null;
113      AcceptEncoding x = CACHE.get(value);
114      if (x == null)
115         x = CACHE.put(value, new AcceptEncoding(value));
116      return x;
117   }
118
119   /**
120    * Convenience creator.
121    *
122    * @param value
123    *    The header value.
124    *    <br>Can be any of the following:
125    *    <ul>
126    *       <li>{@link String} - Converted using {@link StringRanges#of(String)}.
127    *       <li><c>StringRange[]</c> - Left as-is.
128    *       <li>Anything else - Converted to <c>String</c> then parsed.
129    *    </ul>
130    * @return A new {@link AcceptEncoding} object.
131    */
132   public static AcceptEncoding of(Object value) {
133      if (value == null)
134         return null;
135      return new AcceptEncoding(value);
136   }
137
138   /**
139    * Convenience creator using supplier.
140    *
141    * <p>
142    * Header value is re-evaluated on each call to {@link #getValue()}.
143    *
144    * @param value
145    *    The header value supplier.
146    *    <br>Can be any of the following:
147    *    <ul>
148    *       <li>{@link String} - Converted using {@link StringRanges#of(String)}.
149    *       <li><c>StringRange[]</c> - Left as-is.
150    *       <li>Anything else - Converted to <c>String</c> then parsed.
151    *    </ul>
152    * @return A new {@link AcceptEncoding} object.
153    */
154   public static AcceptEncoding of(Supplier<?> value) {
155      if (value == null)
156         return null;
157      return new AcceptEncoding(value);
158   }
159
160   /**
161    * Constructor
162    *
163    * @param value
164    *    The header value.
165    *    <br>Can be any of the following:
166    *    <ul>
167    *       <li>{@link String} - Converted using {@link StringRanges#of(String)}.
168    *       <li><c>StringRange[]</c> - Left as-is.
169    *       <li>Anything else - Converted to <c>String</c> then parsed.
170    *       <li>A {@link Supplier} of anything on this list.
171    *    </ul>
172    */
173   public AcceptEncoding(Object value) {
174      super("Accept-Encoding", value);
175   }
176
177   /**
178    * Constructor
179    *
180    * @param value
181    *    The header value.
182    */
183   public AcceptEncoding(String value) {
184      this((Object)value);
185   }
186}