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.*;
022
023/**
024 * Represents a parsed <l>Content-Length</l> HTTP request/response header.
025 *
026 * <p>
027 * The length of the response body in octets (8-bit bytes).
028 *
029 * <h5 class='figure'>Example</h5>
030 * <p class='bcode'>
031 *    Content-Length: 348
032 * </p>
033 *
034 * <h5 class='topic'>RFC2616 Specification</h5>
035 *
036 * The Content-Length entity-header field indicates the size of the entity-body, in decimal number of OCTETs, sent to
037 * the recipient or, in the case of the HEAD method, the size of the entity-body that would have been sent had the
038 * request been a GET.
039 * <p class='bcode'>
040 *    Content-Length    = "Content-Length" ":" 1*DIGIT
041 * </p>
042 *
043 * <p>
044 * An example is...
045 * <p class='bcode'>
046 *    Content-Length: 3495
047 * </p>
048 *
049 * <p>
050 * Applications SHOULD use this field to indicate the transfer-length of the message-body, unless this is prohibited by
051 * the rules in section 4.4.
052 *
053 * <p>
054 * Any Content-Length greater than or equal to zero is a valid value.
055 * Section 4.4 describes how to determine the length of a message-body if a Content-Length is not given.
056 *
057 * <p>
058 * Note that the meaning of this field is significantly different from the corresponding definition in MIME, where it is
059 * an optional field used within the "message/external-body" content-type.
060 * In HTTP, it SHOULD be sent whenever the message's length can be determined prior to being transferred, unless this is
061 * prohibited by the rules in section 4.4.
062 *
063 * <h5 class='section'>See Also:</h5><ul>
064 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommonBasics">juneau-rest-common Basics</a>
065 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
066 * </ul>
067 *
068 * @serial exclude
069 */
070@Header("Content-Length")
071public class ContentLength extends BasicLongHeader {
072
073   //-----------------------------------------------------------------------------------------------------------------
074   // Static
075   //-----------------------------------------------------------------------------------------------------------------
076
077   private static final long serialVersionUID = 1L;
078   private static final String NAME = "Content-Length";
079
080   /**
081    * Static creator.
082    *
083    * @param value
084    *    The header value.
085    *    <br>Must be parsable using {@link Long#parseLong(String)}.
086    *    <br>Can be <jk>null</jk>.
087    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
088    */
089   public static ContentLength of(String value) {
090      return value == null ? null : new ContentLength(value);
091   }
092
093   /**
094    * Static creator.
095    *
096    * @param value
097    *    The header value.
098    *    <br>Can be <jk>null</jk>.
099    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
100    */
101   public static ContentLength of(Long value) {
102      return value == null ? null : new ContentLength(value);
103   }
104
105   /**
106    * Static creator with delayed value.
107    *
108    * <p>
109    * Header value is re-evaluated on each call to {@link #getValue()}.
110    *
111    * @param value
112    *    The supplier of the header value.
113    *    <br>Can be <jk>null</jk>.
114    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
115    */
116   public static ContentLength of(Supplier<Long> value) {
117      return value == null ? null : new ContentLength(value);
118   }
119
120   //-----------------------------------------------------------------------------------------------------------------
121   // Instance
122   //-----------------------------------------------------------------------------------------------------------------
123
124   /**
125    * Constructor.
126    *
127    * @param value
128    *    The header value.
129    *    <br>Must be parsable using {@link Long#parseLong(String)}.
130    *    <br>Can be <jk>null</jk>.
131    */
132   public ContentLength(String value) {
133      super(NAME, value);
134   }
135
136   /**
137    * Constructor.
138    *
139    * @param value
140    *    The header value.
141    *    <br>Can be <jk>null</jk>.
142    */
143   public ContentLength(Long value) {
144      super(NAME, value);
145   }
146
147   /**
148    * Constructor with delayed value.
149    *
150    * <p>
151    * Header value is re-evaluated on each call to {@link #getValue()}.
152    *
153    * @param value
154    *    The supplier of the header value.
155    *    <br>Can be <jk>null</jk>.
156    */
157   public ContentLength(Supplier<Long> value) {
158      super(NAME, value);
159   }
160}