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 : Header.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 java.io.Serializable;
024:
025: /**
026: * This interface is the super interface of all SIP headers supported explicitly
027: * by this specification. Extension Headers can be supported by this specification as required
028: * by extending the {@link ExtensionHeader} assuming other endpoints understand
029: * the Header. This specification supports the following headers not defined in
030: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a> documented in
031: * the following standards track RFCs:
032: * <ul>
033: * <li> RAckHeader - this header is specific to the reliability of provisional
034: * Responses. This functionality is defined in <a href = "http://www.ietf.org/rfc/rfc3262.txt">RFC3262</a>.
035: * <li> RSeqHeader - this header is specific to the reliability of provisional
036: * Responses. This functionality is defined in <a href = "http://www.ietf.org/rfc/rfc3262.txt">RFC3262</a>.
037: * <li> AllowEventsHeader - this header is specific to the event notification
038: * framework. This functionality is defined in <a href = "http://www.ietf.org/rfc/rfc3265.txt">RFC3265</a>.
039: * <li> EventHeader - this header is specific to the event notification
040: * framework. This functionality is defined in <a href = "http://www.ietf.org/rfc/rfc3265.txt">RFC3265</a>.
041: * <li> SubscriptionStateHeader - this header is specific to the event notification
042: * framework. This functionality is defined in <a href = "http://www.ietf.org/rfc/rfc3265.txt">RFC3265</a>.
043: * <li> ReasonHeader - The Reason Header provides information on why a SIP
044: * request was issued, often useful when creating services and used to
045: * encapsulate a final status code in a provisional response. This functionality
046: * is defined in <a href = "http://www.ietf.org/rfc/rfc3326.txt">RFC3326</a>.
047: * </ul>
048: * SIP header fields are similar to HTTP header fields in both syntax and
049: * semantics. Some header fields only make sense in requests or responses.
050: * These are called request header fields and response header fields, respectively. If a
051: * header field appears in a message not matching its category (such as a
052: * request header field in a response), it MUST be ignored.
053: * <p>
054: *<b>Header Handling</b>:<br>
055: * Any SIP header whose grammar is of the form:
056: * <br>
057: * <center>header = "header-name" HCOLON header-value *(COMMA header-value)
058: * </center>
059: * <br>
060: * allows for combining header fields of the same name into a comma-separated
061: * list. In this specification each Header object has a single value or attribute pair.
062: * For example a Header whose grammer is of the form:
063: * <br>
064: * <center>Allow: Invite, Bye;</center>
065: * <br>
066: * would be represented in a SIP message with two AllowHeader objects each
067: * containing a single attribute, Invite and Bye respectively. Implementations
068: * MUST be able to parse multiple header field rows with the same name in any
069: * combination of the single-value-per-line or comma-separated value forms and
070: * translate them into the relevent Header objects defined in this specification.
071: * <p>
072: * The relative order of header objects within messages is not significant.
073: * However, it is RECOMMENDED that required header and headers which are needed
074: * for proxy processing (Via, Route, Record-Route, Proxy-Require, Max-Forwards,
075: * and Proxy-Authorization, for example) appear towards the top of the message
076: * to facilitate rapid parsing.
077: * <p>
078: * The relative order of header objects with the same field name is important.
079: * Multiple headers with the same name MAY be present in a message if and only if
080: * the entire field-value for that header field can be defined as a
081: * comma-separated list as defined by RFC 3261. The exceptions to this rule are
082: * the WWW-Authenticate, Authorization, Proxy-Authenticate, and
083: * Proxy-Authorization header fields. Multiple header objects with these
084: * names MAY be present in a message, but since their grammar does not follow
085: * the general form listed above, they MUST NOT be combined into a single
086: * header field row when sent over the network.
087: * <p>
088: * Even though an arbitrary number of parameter pairs may be attached to a
089: * header object, any given parameter-name MUST NOT appear more than once.
090: *
091: * @author BEA Systems, NIST
092: * @version 1.2
093: */
094:
095: public interface Header extends Cloneable, Serializable {
096:
097: /**
098: * Gets the unique string name of this Header. A name constant is defined in
099: * each individual Header identifying each Header.
100: *
101: * @return the name of this specific Header
102: */
103: public String getName();
104:
105: /**
106: * Compare this SIP Header for equality with another. This method overrides
107: * the equals method in java.lang.Object. This method is over-ridden further
108: * for each required header (To, From, CSeq, Call-ID, Max-Forwards, and Via)
109: * which object equality is outlined as specified by
110: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>. All optional
111: * headers are compared using object equality that is each field in the
112: * header is used for comparision. When comparing header fields, field names
113: * are always case-insensitive. Unless otherwise stated in the
114: * definition of a particular header field, field values, parameter names,
115: * and parameter values are case-insensitive. Tokens are always
116: * case-insensitive. Unless specified otherwise, values expressed as quoted
117: * strings are case-sensitive.
118: *
119: * @param obj the object to compare this Header with.
120: * @return <code>true</code> if <code>obj</code> is an instance of this class
121: * representing the same SIP Header as this, <code>false</code> otherwise.
122: */
123: public boolean equals(Object obj);
124:
125: /**
126: * Creates and returns a deep copy of the Header. This methods must ensure a
127: * deep copy of the Header, so that when a message is cloned the Header can
128: * be modified without effecting the original Header in the message. This
129: * provides useful functionality for proxying Requests and Responses, for
130: * example:
131: * <ul>
132: * <li>Recieve a message.
133: * <li>Create a deep clone of the message and headers.
134: * <li>Modify necessary headers.
135: * <li>Proxy the message using the send methods on the SipProvider.
136: * </ul>
137: * This method overrides the clone method in java.lang.Object.
138: *
139: * @return a deep copy of Header
140: */
141: public Object clone();
142:
143: /**
144: * Gets a integer hashcode representation of the Header. This method
145: * overrides the hashcode method in java.lang.Object.
146: *
147: * @return integer representation of Header hashcode
148: * @since v1.2
149: */
150: public int hashCode();
151:
152: /**
153: * Gets a string representation of the Header. This method overrides the
154: * toString method in java.lang.Object.
155: *
156: * @return string representation of Header
157: */
158: public String toString();
159:
160: }
|