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.function.*;
016
017import org.apache.juneau.*;
018import org.apache.juneau.http.annotation.*;
019import org.apache.juneau.internal.*;
020
021
022/**
023 * Represents a parsed <l>Accept-Charset</l> HTTP request header.
024 *
025 * <p>
026 * Character sets that are acceptable.
027 *
028 * <h5 class='figure'>Example</h5>
029 * <p class='bcode'>
030 *    Accept-Charset: utf-8
031 * </p>
032 *
033 * <h5 class='topic'>RFC2616 Specification</h5>
034 *
035 * The Accept-Charset request-header field can be used to indicate what character sets are acceptable for the response.
036 *
037 * <p>
038 * This field allows clients capable of understanding more comprehensive or special- purpose character sets to signal
039 * that capability to a server which is capable of representing documents in those character sets.
040 * <p class='bcode'>
041 *    Accept-Charset = "Accept-Charset" ":"
042 *                     1#( ( charset | "*" )[ ";" "q" "=" qvalue ] )
043 * </p>
044 *
045 * <p>
046 * Character set values are described in section 3.4. Each charset MAY be given an associated quality value which
047 * represents the user's preference for that charset.
048 * The default value is q=1.
049 * An example is...
050 * <p class='bcode'>
051 *    Accept-Charset: iso-8859-5, unicode-1-1;q=0.8
052 * </p>
053 *
054 * <p>
055 * The special value "*", if present in the Accept-Charset field, matches every character set (including ISO-8859-1)
056 * which is not mentioned elsewhere in the Accept-Charset field.
057 *
058 * <p>
059 * If no "*" is present in an Accept-Charset field, then all character sets not explicitly mentioned get a quality
060 * value of 0, except for ISO-8859-1, which gets a quality value of 1 if not explicitly mentioned.
061 *
062 * <p>
063 * If no Accept-Charset header is present, the default is that any character set is acceptable.
064 *
065 * <p>
066 * If an Accept-Charset header is present, and if the server cannot send a response which is acceptable according to
067 * the Accept-Charset header, then the server SHOULD send an error response with the 406 (not acceptable) status code,
068 * though the sending of an unacceptable response is also allowed.
069 *
070 * <h5 class='section'>See Also:</h5><ul>
071 *    <li class='link'><a class="doclink" href="../../../../../index.html#juneau-rest-common">juneau-rest-common</a>
072 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
073 * </ul>
074 *
075 * @serial exclude
076 */
077@Header("Accept-Charset")
078public class AcceptCharset extends BasicStringRangesHeader {
079
080   //-----------------------------------------------------------------------------------------------------------------
081   // Static
082   //-----------------------------------------------------------------------------------------------------------------
083
084   private static final long serialVersionUID = 1L;
085   private static final String NAME = "Accept-Charset";
086
087   private static final Cache<String,AcceptCharset> CACHE = Cache.of(String.class, AcceptCharset.class).build();
088
089   /**
090    * Static creator.
091    *
092    * @param value
093    *    The header value.
094    *    <br>Must be parsable by {@link StringRanges#of(String)}.
095    *    <br>Can be <jk>null</jk>.
096    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
097    */
098   public static AcceptCharset of(String value) {
099      return value == null ? null : CACHE.get(value, ()->new AcceptCharset(value));
100   }
101
102   /**
103    * Static creator.
104    *
105    * @param value
106    *    The header value.
107    *    <br>Can be <jk>null</jk>.
108    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
109    */
110   public static AcceptCharset of(StringRanges value) {
111      return value == null ? null : new AcceptCharset(value);
112   }
113
114   /**
115    * Static creator with delayed value.
116    *
117    * <p>
118    * Header value is re-evaluated on each call to {@link #getValue()}.
119    *
120    * @param value
121    *    The supplier of the header value.
122    *    <br>Can be <jk>null</jk>.
123    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
124    */
125   public static AcceptCharset of(Supplier<StringRanges> value) {
126      return value == null ? null : new AcceptCharset(value);
127   }
128
129   //-----------------------------------------------------------------------------------------------------------------
130   // Instance
131   //-----------------------------------------------------------------------------------------------------------------
132
133   /**
134    * Constructor.
135    *
136    * @param value
137    *    The header value.
138    *    <br>Must be parsable by {@link StringRanges#of(String)}.
139    *    <br>Can be <jk>null</jk>.
140    */
141   public AcceptCharset(String value) {
142      super(NAME, value);
143   }
144
145   /**
146    * Constructor.
147    *
148    * @param value
149    *    The header value.
150    *    <br>Can be <jk>null</jk>.
151    */
152   public AcceptCharset(StringRanges value) {
153      super(NAME, value);
154   }
155
156   /**
157    * Constructor with delayed value.
158    *
159    * <p>
160    * Header value is re-evaluated on each call to {@link #getValue()}.
161    *
162    * @param value
163    *    The supplier of the header value.
164    *    <br>Can be <jk>null</jk>.
165    */
166   public AcceptCharset(Supplier<StringRanges> value) {
167      super(NAME, value);
168   }
169}