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>Content-Language</l> HTTP response header.
022 *
023 * <p>
024 * The natural language or languages of the intended audience for the enclosed content.
025 *
026 * <h5 class='figure'>Example</h5>
027 * <p class='bcode w800'>
028 *    Content-Language: da
029 * </p>
030 *
031 * <h5 class='topic'>RFC2616 Specification</h5>
032 *
033 * The Content-Language entity-header field describes the natural language(s) of the intended audience for the
034 * enclosed entity.
035 * Note that this might not be equivalent to all the languages used within the entity-body.
036 * <p class='bcode w800'>
037 *    Content-Language  = "Content-Language" ":" 1#language-tag
038 * </p>
039 *
040 * <p>
041 * Language tags are defined in section 3.10.
042 * The primary purpose of Content-Language is to allow a user to identify and differentiate entities according to the
043 * user's own preferred language.
044 * Thus, if the body content is intended only for a Danish-literate audience, the appropriate field is...
045 * <p class='bcode w800'>
046 *    Content-Language: da
047 * </p>
048 *
049 * <p>
050 * If no Content-Language is specified, the default is that the content is intended for all language audiences.
051 * This might mean that the sender does not consider it to be specific to any natural language, or that the sender
052 * does not know for which language it is intended.
053 *
054 * <p>
055 * Multiple languages MAY be listed for content that is intended for multiple audiences.
056 * For example, a rendition of the "Treaty of Waitangi," presented simultaneously in the original Maori and English
057 * versions, would call for...
058 * <p class='bcode w800'>
059 *    Content-Language: mi, en
060 * </p>
061 *
062 * <p>
063 * However, just because multiple languages are present within an entity does not mean that it is intended for
064 * multiple linguistic audiences.
065 * An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to
066 * be used by an English-literate audience.
067 * In this case, the Content-Language would properly only include "en".
068 *
069 * <p>
070 * Content-Language MAY be applied to any media type -- it is not limited to textual documents.
071 *
072 * <ul class='seealso'>
073 *    <li class='extlink'>{@doc ExtRFC2616}
074 * </ul>
075 */
076@Header("Content-Language")
077public class ContentLanguage extends BasicCsvArrayHeader {
078
079   private static final long serialVersionUID = 1L;
080
081   /**
082    * Convenience creator.
083    *
084    * @param value
085    *    The header value.
086    *    <br>Can be any of the following:
087    *    <ul>
088    *       <li><c>String</c> - A comma-delimited string.
089    *       <li><c>String[]</c> - A pre-parsed value.
090    *       <li>Any other array type - Converted to <c>String[]</c>.
091    *       <li>Any {@link Collection} - Converted to <c>String[]</c>.
092    *       <li>Anything else - Converted to <c>String</c>.
093    *    </ul>
094    * @return The parsed <c>Content-Language</c> header, or <jk>null</jk> if the value was null.
095    */
096   public static ContentLanguage of(Object value) {
097      if (value == null)
098         return null;
099      return new ContentLanguage(value);
100   }
101
102   /**
103    * Convenience creator using supplier.
104    *
105    * <p>
106    * Header value is re-evaluated on each call to {@link #getValue()}.
107    *
108    * @param value
109    *    The header value supplier.
110    *    <br>Can be any of the following:
111    *    <ul>
112    *       <li><c>String</c> - A comma-delimited string.
113    *       <li><c>String[]</c> - A pre-parsed value.
114    *       <li>Any other array type - Converted to <c>String[]</c>.
115    *       <li>Any {@link Collection} - Converted to <c>String[]</c>.
116    *       <li>Anything else - Converted to <c>String</c>.
117    *    </ul>
118    * @return The parsed <c>Content-Language</c> header, or <jk>null</jk> if the value was null.
119    */
120   public static ContentLanguage of(Supplier<?> value) {
121      if (value == null)
122         return null;
123      return new ContentLanguage(value);
124   }
125
126   /**
127    * Constructor.
128    *
129    * @param value
130    *    The header value.
131    *    <br>Can be any of the following:
132    *    <ul>
133    *       <li><c>String</c> - A comma-delimited string.
134    *       <li><c>String[]</c> - A pre-parsed value.
135    *       <li>Any other array type - Converted to <c>String[]</c>.
136    *       <li>Any {@link Collection} - Converted to <c>String[]</c>.
137    *       <li>Anything else - Converted to <c>String</c>.
138    *       <li>A {@link Supplier} of anything on this list.
139    *    </ul>
140    */
141   public ContentLanguage(Object value) {
142      super("Content-Language", value);
143   }
144
145   /**
146    * Constructor
147    *
148    * @param value
149    *    The header value.
150    */
151   public ContentLanguage(String value) {
152      this((Object)value);
153   }
154}