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 : CSeqHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty
020: * 1.2 11/06/2006 Phelim O'Doherty Changed Cseq to type long
021: *
022: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
023: */package javax.sip.header;
024:
025: import javax.sip.InvalidArgumentException;
026: import java.text.ParseException;
027:
028: /**
029: * A CSeq header field in a request contains a single decimal sequence number
030: * and the request method. The CSeq header field serves to identify and order
031: * transactions within a dialog, to provide a means to uniquely identify
032: * transactions, and to differentiate between new requests and request
033: * retransmissions. Two CSeq header fields are considered equal if the
034: * sequence number and the request method are identical.
035: * <ul>
036: * <li>Method - The method part of CSeq is case-sensitive and MUST match that
037: * of the request.
038: * <li>Sequence number - The sequence number is chosen by the requesting
039: * client and is unique within a single value of Call-ID. The sequence number
040: * MUST be expressible as a 32-bit unsigned integer and MUST be less than
041: * 2**31. For non-REGISTER requests outside of a dialog, the sequence number
042: * value is arbitrary. Consecutive Requests that differ in method, headers or
043: * body, but have the same CallIdHeader must contain strictly monotonically
044: * increasing and contiguous sequence numbers; sequence numbers do not wrap
045: * around. Retransmissions of the same Request carry the same sequence number,
046: * but an INVITE Request with a different message body or different headers
047: * (a "re-invitation") acquires a new, higher sequence number. A server must
048: * echo the CSeqHeader from the Request in its Response. If the method value is
049: * missing in the received CSeqHeader, the server fills it in appropriately.
050: * ACK and CANCEL Requests must contain the same CSeqHeader sequence number
051: * (but not method) as the INVITE Request they refer to, while a BYE Request
052: * cancelling an invitation must have a higher sequence number. An user agent
053: * server must remember the highest sequence number for any INVITE Request
054: * with the same CallIdHeader. The server must respond to, and then discard,
055: * any INVITE Request with a lower sequence number.
056: * </ul>
057: * As long as a client follows the above guidelines, it may use any mechanism
058: * it would like to select CSeq header field values.
059: * <p>
060: * <b>Forked Requests:</b><br>
061: * Forked Requests must have the same CSeqHeader as there would be ambiguity
062: * otherwise between these forked Requests and later BYE Requests issued by the
063: * client user agent.
064: * <p>
065: * For Example:<br>
066: * <code>CSeq: 4711 INVITE</code>
067: *
068: * @author BEA Systems, NIST
069: * @version 1.2
070: *
071: */
072:
073: public interface CSeqHeader extends Header {
074:
075: /**
076: * Sets the method of CSeqHeader
077: *
078: * @param method - the method of the Request of this CSeqHeader
079: * @throws ParseException which signals that an error has been reached
080: * unexpectedly while parsing the method value.
081: */
082: public void setMethod(String method) throws ParseException;
083:
084: /**
085: * Gets the method of CSeqHeader
086: *
087: * @return method of CSeqHeader
088: */
089: public String getMethod();
090:
091: /**
092: * Sets the sequence number value of the CSeqHeader. The sequence number
093: * MUST be expressible as a 32-bit unsigned integer and MUST be less than
094: * 2**32 -1
095: *
096: * @param sequenceNumber - the new sequence number of this CSeqHeader
097: * @throws InvalidArgumentException if supplied value is less than zero.
098: * @since v1.1
099: *
100: * @deprecated This method is replaced with {@link #setSeqNumber(long)} with
101: * type long.
102: */
103: public void setSequenceNumber(int sequenceNumber)
104: throws InvalidArgumentException;
105:
106: /**
107: * Gets the sequence number of this CSeqHeader.
108: *
109: * @deprecated This method is replaced with {@link #getSeqNumber()} with
110: * type long.
111: * @return sequence number of the CSeqHeader
112: * @since v1.1
113: */
114: public int getSequenceNumber();
115:
116: /**
117: * Sets the sequence number value of the CSeqHeader.
118: *
119: * @param sequenceNumber - the new sequence number of this CSeqHeader
120: * @throws InvalidArgumentException if supplied value is less than zero.
121: * @since v1.2
122: */
123: public void setSeqNumber(long sequenceNumber)
124: throws InvalidArgumentException;
125:
126: /**
127: * Gets the sequence number of this CSeqHeader.
128: *
129: * @return sequence number of the CSeqHeader
130: * @since v1.2
131: */
132: public long getSeqNumber();
133:
134: /**
135: * Compare this CSeqHeader for equality with another. This method
136: * overrides the equals method in javax.sip.Header. This method specifies
137: * object equality as outlined by
138: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
139: * Two CSeq header fields are considered equal if the sequence number and
140: * the request method are identical. When comparing header fields, field names
141: * are always case-insensitive. Unless otherwise stated in the
142: * definition of a particular header field, field values, parameter names,
143: * and parameter values are case-insensitive. Tokens are always
144: * case-insensitive. Unless specified otherwise, values expressed as quoted
145: * strings are case-sensitive.
146: *
147: * @param obj the object to compare this CSeqHeader with.
148: * @return <code>true</code> if <code>obj</code> is an instance of this class
149: * representing the same CseqHeader as this, <code>false</code> otherwise.
150: * @since v1.2
151: */
152: public boolean equals(Object obj);
153:
154: /**
155: * Name of the CSeqHeader
156: */
157: public final static String NAME = "CSeq";
158:
159: }
|