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   private static final long serialVersionUID = 1L;
073   private static final String NAME = "Content-Length";
074
075   /**
076    * Static creator.
077    *
078    * @param value
079    *    The header value.
080    *    <br>Can be <jk>null</jk>.
081    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
082    */
083   public static ContentLength of(Long value) {
084      return value == null ? null : new ContentLength(value);
085   }
086
087   /**
088    * Static creator.
089    *
090    * @param value
091    *    The header value.
092    *    <br>Must be parsable using {@link Long#parseLong(String)}.
093    *    <br>Can be <jk>null</jk>.
094    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
095    */
096   public static ContentLength of(String value) {
097      return value == null ? null : new ContentLength(value);
098   }
099
100   /**
101    * Static creator with delayed value.
102    *
103    * <p>
104    * Header value is re-evaluated on each call to {@link #getValue()}.
105    *
106    * @param value
107    *    The supplier of the header value.
108    *    <br>Can be <jk>null</jk>.
109    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
110    */
111   public static ContentLength of(Supplier<Long> value) {
112      return value == null ? null : new ContentLength(value);
113   }
114
115   /**
116    * Constructor.
117    *
118    * @param value
119    *    The header value.
120    *    <br>Can be <jk>null</jk>.
121    */
122   public ContentLength(Long value) {
123      super(NAME, value);
124   }
125
126   /**
127    * Constructor.
128    *
129    * @param value
130    *    The header value.
131    *    <br>Must be parsable using {@link Long#parseLong(String)}.
132    *    <br>Can be <jk>null</jk>.
133    */
134   public ContentLength(String value) {
135      super(NAME, value);
136   }
137
138   /**
139    * Constructor with delayed value.
140    *
141    * <p>
142    * Header value is re-evaluated on each call to {@link #getValue()}.
143    *
144    * @param value
145    *    The supplier of the header value.
146    *    <br>Can be <jk>null</jk>.
147    */
148   public ContentLength(Supplier<Long> value) {
149      super(NAME, value);
150   }
151}