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 w800'>
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 w800'>
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 * <ul class='seealso'>
058 *    <li class='extlink'>{@doc ExtRFC2616}
059 * </ul>
060 */
061@Header("Max-Forwards")
062public class MaxForwards extends BasicIntegerHeader {
063
064   private static final long serialVersionUID = 1L;
065
066   /**
067    * Convenience creator.
068    *
069    * @param value
070    *    The header value.
071    *    <br>Can be any of the following:
072    *    <ul>
073    *       <li>{@link Number} - Converted to an integer using {@link Number#intValue()}.
074    *       <li>{@link String} - Parsed using {@link Integer#parseInt(String)}.
075    *       <li>Anything else - Converted to <c>String</c>.
076    *    </ul>
077    * @return A new {@link BasicIntegerHeader} object.
078    */
079   public static MaxForwards of(Object value) {
080      if (value == null)
081         return null;
082      return new MaxForwards(value);
083   }
084
085   /**
086    * Convenience creator using supplier.
087    *
088    * <p>
089    * Header value is re-evaluated on each call to {@link #getValue()}.
090    *
091    * @param value
092    *    The header value supplier.
093    *    <br>Can be any of the following:
094    *    <ul>
095    *       <li>{@link Number} - Converted to an integer using {@link Number#intValue()}.
096    *       <li>{@link String} - Parsed using {@link Integer#parseInt(String)}.
097    *       <li>Anything else - Converted to <c>String</c>.
098    *    </ul>
099    * @return A new {@link BasicIntegerHeader} object.
100    */
101   public static MaxForwards of(Supplier<?> value) {
102      if (value == null)
103         return null;
104      return new MaxForwards(value);
105   }
106
107   /**
108    * Constructor.
109    *
110    * @param value
111    *    The header value.
112    *    <br>Can be any of the following:
113    *    <ul>
114    *       <li>{@link Number} - Converted to an integer using {@link Number#intValue()}.
115    *       <li>{@link String} - Parsed using {@link Integer#parseInt(String)}.
116    *       <li>Anything else - Converted to <c>String</c>.
117    *       <li>A {@link Supplier} of anything on this list.
118    *    </ul>
119    */
120   public MaxForwards(Object value) {
121      super("Max-Forwards", value);
122   }
123
124   /**
125    * Constructor
126    *
127    * @param value
128    *    The header value.
129    */
130   public MaxForwards(String value) {
131      this((Object)value);
132   }
133}