001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : MaxForwardsHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty
020: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
021: */package javax.sip.header;
022:
023: import javax.sip.InvalidArgumentException;
024:
025: /**
026:
027: * The Max-Forwards header field must be used with any SIP method to limit
028:
029: * the number of proxies or gateways that can forward the request to the next
030:
031: * downstream server. This can also be useful when the client is attempting
032:
033: * to trace a request chain that appears to be failing or looping in mid-chain.
034:
035: * <p>
036:
037: * The Max-Forwards value is an integer in the range 0-255 indicating the
038:
039: * remaining number of times this request message is allowed to be forwarded.
040:
041: * This count is decremented by each server that forwards the request. The
042:
043: * recommended initial value is 70.
044:
045: * <p>
046:
047: * This header field should be inserted by elements that can not otherwise
048:
049: * guarantee loop detection. For example, a B2BUA should insert a Max-Forwards
050:
051: * header field.
052:
053: * <p>
054:
055: * For Example:<br>
056:
057: * <code>Max-Forwards: 6</code>
058:
059: *
060: * @author BEA Systems, NIST
061: * @version 1.2
062:
063: */
064:
065: public interface MaxForwardsHeader extends Header {
066:
067: /**
068:
069: * This convenience function decrements the number of max-forwards by one.
070:
071: * This utility is useful for proxy functionality.
072:
073: *
074:
075: * @throws TooManyHopsException if implementation cannot decrement
076:
077: * max-fowards i.e. max-forwards has reached zero
078:
079: */
080:
081: public void decrementMaxForwards() throws TooManyHopsException;
082:
083: /**
084:
085: * Gets the maximum number of forwards value of this MaxForwardsHeader.
086:
087: *
088:
089: * @return the maximum number of forwards of this MaxForwardsHeader
090:
091: */
092:
093: public int getMaxForwards();
094:
095: /**
096:
097: * Sets the max-forwards argument of this MaxForwardsHeader to the supplied
098:
099: * <var>maxForwards</var> value.
100:
101: *
102:
103: * @param maxForwards - the number of max-forwards
104:
105: * @throws InvalidArgumentException if the maxForwards argument is less
106:
107: * than 0 or greater than 255.
108:
109: */
110:
111: public void setMaxForwards(int maxForwards)
112: throws InvalidArgumentException;
113:
114: /**
115: * Compare this MaxForwardsHeader for equality with another. This method
116: * overrides the equals method in javax.sip.Header. This method specifies
117: * object equality as outlined by
118: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
119: * Two MaxForwards header fields are equivalent if their max forwards
120: * integer match.
121: *
122: * @param obj the object to compare this MaxForwardsHeader with.
123: * @return <code>true</code> if <code>obj</code> is an instance of this class
124: * representing the same MaxForwardsHeader as this, <code>false</code> otherwise.
125: * @since v1.2
126: */
127: public boolean equals(Object obj);
128:
129: /**
130:
131: * Name of MaxForwardsHeader
132:
133: */
134:
135: public final static String NAME = "Max-Forwards";
136:
137: }
|