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.annotation.*;
022import org.apache.juneau.http.annotation.*;
023
024/**
025 * Represents a parsed <l>Content-Encoding</l> HTTP response header.
026 *
027 * <p>
028 * The type of encoding used on the data.
029 *
030 * <h5 class='figure'>Example</h5>
031 * <p class='bcode'>
032 *    Content-Encoding: gzip
033 * </p>
034 *
035 * <h5 class='topic'>RFC2616 Specification</h5>
036 *
037 * The Content-Encoding entity-header field is used as a modifier to the media-type.
038 * When present, its value indicates what additional content codings have been applied to the entity-body, and thus
039 * what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header
040 * field.
041 * Content-Encoding is primarily used to allow a document to be compressed without losing the identity of its
042 * underlying media type.
043 * <p class='bcode'>
044 *    Content-Encoding  = "Content-Encoding" ":" 1#content-coding
045 * </p>
046 *
047 * <p>
048 * Content codings are defined in section 3.5. An example of its use is...
049 * <p class='bcode'>
050 *    Content-Encoding: gzip
051 * </p>
052 *
053 * <p>
054 * The content-coding is a characteristic of the entity identified by the Request-URI.
055 * Typically, the entity-body is stored with this encoding and is only decoded before rendering or analogous usage.
056 * However, a non-transparent proxy MAY modify the content-coding if the new coding is known to be acceptable to the
057 * recipient, unless the "no-transform" cache-control directive is present in the message.
058 *
059 * <p>
060 * If the content-coding of an entity is not "identity", then the response MUST include a Content-Encoding
061 * entity-header (section 14.11) that lists the non-identity content-coding(s) used.
062 *
063 * <p>
064 * If the content-coding of an entity in a request message is not acceptable to the origin server, the server SHOULD
065 * respond with a status code of 415 (Unsupported Media Type).
066 *
067 * <p>
068 * If multiple encodings have been applied to an entity, the content codings MUST be listed in the order in which they
069 * were applied.
070 * Additional information about the encoding parameters MAY be provided.
071 *
072 * <h5 class='section'>See Also:</h5><ul>
073 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommonBasics">juneau-rest-common Basics</a>
074 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
075 * </ul>
076 *
077 * @serial exclude
078 */
079@Header("Content-Encoding")
080@Schema(_enum={"gzip","compress","deflate","identity","other"})
081public class ContentEncoding extends BasicStringHeader {
082
083   //-----------------------------------------------------------------------------------------------------------------
084   // Static
085   //-----------------------------------------------------------------------------------------------------------------
086
087   private static final long serialVersionUID = 1L;
088   private static final String NAME = "Content-Encoding";
089
090   /**
091    * Static creator.
092    *
093    * @param value
094    *    The header value.
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 ContentEncoding of(String value) {
099      return value == null ? null : new ContentEncoding(value);
100   }
101
102   /**
103    * Static creator with delayed value.
104    *
105    * <p>
106    * Header value is re-evaluated on each call to {@link #getValue()}.
107    *
108    * @param value
109    *    The supplier of the header value.
110    *    <br>Can be <jk>null</jk>.
111    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
112    */
113   public static ContentEncoding of(Supplier<String> value) {
114      return value == null ? null : new ContentEncoding(value);
115   }
116
117   //-----------------------------------------------------------------------------------------------------------------
118   // Instance
119   //-----------------------------------------------------------------------------------------------------------------
120
121   /**
122    * Constructor.
123    *
124    * @param value
125    *    The header value.
126    *    <br>Can be <jk>null</jk>.
127    */
128   public ContentEncoding(String value) {
129      super(NAME, value);
130   }
131
132   /**
133    * Constructor with delayed value.
134    *
135    * <p>
136    * Header value is re-evaluated on each call to {@link #getValue()}.
137    *
138    * @param value
139    *    The supplier of the header value.
140    *    <br>Can be <jk>null</jk>.
141    */
142   public ContentEncoding(Supplier<String> value) {
143      super(NAME, value);
144   }
145}