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>Max-Forwards</l> HTTP request header.
021 *
022 * <p>
023 * Limit the number of times the message can be forwarded through proxies or gateways.
024 *
025 * <h5 class='figure'>Example</h5>
026 * <p class='bcode'>
027 *    Max-Forwards: 10
028 * </p>
029 *
030 * <h5 class='topic'>RFC2616 Specification</h5>
031 *
032 * The Max-Forwards request-header field provides a mechanism with the TRACE (section 9.8) and OPTIONS (section 9.2)
033 * methods to limit the number of proxies or gateways that can forward the request to the next inbound server.
034 * This can be useful when the client is attempting to trace a request chain which appears to be failing or looping in
035 * mid-chain.
036 *
037 * <p class='bcode'>
038 *    Max-Forwards   = "Max-Forwards" ":" 1*DIGIT
039 * </p>
040 *
041 * <p>
042 * The Max-Forwards value is a decimal integer indicating the remaining number of times this request message may be
043 * forwarded.
044 *
045 * <p>
046 * Each proxy or gateway recipient of a TRACE or OPTIONS request containing a Max-Forwards header field MUST check and
047 * update its value prior to forwarding the request.
048 * If the received value is zero (0), the recipient MUST NOT forward the request; instead, it MUST respond as the final
049 * recipient.
050 * If the received Max-Forwards value is greater than zero, then the forwarded message MUST contain an updated
051 * Max-Forwards field with a value decremented by one (1).
052 *
053 * <p>
054 * The Max-Forwards header field MAY be ignored for all other methods defined by this specification and for any
055 * extension methods for which it is not explicitly referred to as part of that method definition.
056 *
057 * <h5 class='section'>See Also:</h5><ul>
058 *    <li class='link'><a class="doclink" href="../../../../../index.html#juneau-rest-common">juneau-rest-common</a>
059 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
060 * </ul>
061 *
062 * @serial exclude
063 */
064@Header("Max-Forwards")
065public class MaxForwards extends BasicIntegerHeader {
066
067   //-----------------------------------------------------------------------------------------------------------------
068   // Static
069   //-----------------------------------------------------------------------------------------------------------------
070
071   private static final long serialVersionUID = 1L;
072   private static final String NAME = "Max-Forwards";
073
074   /**
075    * Static creator.
076    *
077    * @param value
078    *    The header value.
079    *    <br>Must be parsable using {@link Integer#parseInt(String)}.
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 MaxForwards of(String value) {
084      return value == null ? null : new MaxForwards(value);
085   }
086
087   /**
088    * Static creator.
089    *
090    * @param value
091    *    The header value.
092    *    <br>Can be <jk>null</jk>.
093    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
094    */
095   public static MaxForwards of(Integer value) {
096      return value == null ? null : new MaxForwards(value);
097   }
098
099   /**
100    * Static creator with delayed value.
101    *
102    * <p>
103    * Header value is re-evaluated on each call to {@link #getValue()}.
104    *
105    * @param value
106    *    The supplier of the header value.
107    *    <br>Can be <jk>null</jk>.
108    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
109    */
110   public static MaxForwards of(Supplier<Integer> value) {
111      return value == null ? null : new MaxForwards(value);
112   }
113
114   //-----------------------------------------------------------------------------------------------------------------
115   // Instance
116   //-----------------------------------------------------------------------------------------------------------------
117
118   /**
119    * Constructor.
120    *
121    * @param value
122    *    The header value.
123    *    <br>Must be parsable using {@link Integer#parseInt(String)}.
124    *    <br>Can be <jk>null</jk>.
125    */
126   public MaxForwards(String value) {
127      super(NAME, value);
128   }
129
130   /**
131    * Constructor.
132    *
133    * @param value
134    *    The header value.
135    *    <br>Can be <jk>null</jk>.
136    */
137   public MaxForwards(Integer value) {
138      super(NAME, value);
139   }
140
141   /**
142    * Constructor with delayed value.
143    *
144    * <p>
145    * Header value is re-evaluated on each call to {@link #getValue()}.
146    *
147    * @param value
148    *    The supplier of the header value.
149    *    <br>Can be <jk>null</jk>.
150    */
151   public MaxForwards(Supplier<Integer> value) {
152      super(NAME, value);
153   }
154}