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.http.annotation.*;
018
019/**
020 * Represents a parsed <l>Content-Length</l> HTTP request/response header.
021 *
022 * <p>
023 * The length of the response body in octets (8-bit bytes).
024 *
025 * <h5 class='figure'>Example</h5>
026 * <p class='bcode w800'>
027 *    Content-Length: 348
028 * </p>
029 *
030 * <h5 class='topic'>RFC2616 Specification</h5>
031 *
032 * The Content-Length entity-header field indicates the size of the entity-body, in decimal number of OCTETs, sent to
033 * the recipient or, in the case of the HEAD method, the size of the entity-body that would have been sent had the
034 * request been a GET.
035 * <p class='bcode w800'>
036 *    Content-Length    = "Content-Length" ":" 1*DIGIT
037 * </p>
038 *
039 * <p>
040 * An example is...
041 * <p class='bcode w800'>
042 *    Content-Length: 3495
043 * </p>
044 *
045 * <p>
046 * Applications SHOULD use this field to indicate the transfer-length of the message-body, unless this is prohibited by
047 * the rules in section 4.4.
048 *
049 * <p>
050 * Any Content-Length greater than or equal to zero is a valid value.
051 * Section 4.4 describes how to determine the length of a message-body if a Content-Length is not given.
052 *
053 * <p>
054 * Note that the meaning of this field is significantly different from the corresponding definition in MIME, where it is
055 * an optional field used within the "message/external-body" content-type.
056 * In HTTP, it SHOULD be sent whenever the message's length can be determined prior to being transferred, unless this is
057 * prohibited by the rules in section 4.4.
058 *
059 * <ul class='seealso'>
060 *    <li class='extlink'>{@doc ExtRFC2616}
061 * </ul>
062 */
063@Header("Content-Length")
064public class ContentLength extends BasicLongHeader {
065
066   private static final long serialVersionUID = 1L;
067
068   /**
069    * Convenience creator.
070    *
071    * @param value
072    *    The header value.
073    *    <br>Can be any of the following:
074    *    <ul>
075    *       <li>{@link Number} - Converted to a long using {@link Number#longValue()}.
076    *       <li>{@link String} - Parsed using {@link Long#parseLong(String)}.
077    *       <li>Anything else - Converted to <c>String</c>.
078    *    </ul>
079    * @return A new {@link ContentLength} object.
080    */
081   public static ContentLength of(Object value) {
082      if (value == null)
083         return null;
084      return new ContentLength(value);
085   }
086
087   /**
088    * Convenience creator using supplier.
089    *
090    * <p>
091    * Header value is re-evaluated on each call to {@link #getValue()}.
092    *
093    * @param value
094    *    The header value supplier.
095    *    <br>Can be any of the following:
096    *    <ul>
097    *       <li>{@link Number} - Converted to a long using {@link Number#longValue()}.
098    *       <li>{@link String} - Parsed using {@link Long#parseLong(String)}.
099    *       <li>Anything else - Converted to <c>String</c>.
100    *    </ul>
101    * @return A new {@link ContentLength} object.
102    */
103   public static ContentLength of(Supplier<?> value) {
104      if (value == null)
105         return null;
106      return new ContentLength(value);
107   }
108
109   /**
110    * Constructor.
111    *
112    * @param value
113    *    The header value.
114    *    <br>Can be any of the following:
115    *    <ul>
116    *       <li>{@link Number} - Converted to a long using {@link Number#longValue()}.
117    *       <li>{@link String} - Parsed using {@link Long#parseLong(String)}.
118    *       <li>Anything else - Converted to <c>String</c>.
119    *       <li>A {@link Supplier} of anything on this list.
120    *    </ul>
121    */
122   public ContentLength(Object value) {
123      super("Content-Length", value);
124   }
125
126   /**
127    * Constructor
128    *
129    * @param value
130    *    The header value.
131    */
132   public ContentLength(String value) {
133      this((Object)value);
134   }
135}