sip.header.Header Maven / Gradle / Ivy

/**
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Unpublished - rights reserved under the Copyright Laws of the United States.
 * Copyright ? 2003 Sun Microsystems, Inc. All rights reserved.
 * Copyright ? 2005 BEA Systems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * This distribution may include materials developed by third parties. 
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 * Module Name   : JSIP Specification
 * File Name     : Header.java
 * Author        : Phelim O'Doherty
 *
 *  HISTORY
 *  Version   Date      Author              Comments
 *  1.1     08/10/2002  Phelim O'Doherty    
 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */
package javax.sip.header;

import java.io.Serializable;

/**
 * This interface is the super interface of all SIP headers supported explicitly
 * by this specification. Extension Headers can be supported by this specification as required 
 * by extending the {@link ExtensionHeader} assuming other endpoints understand 
 * the Header. This specification supports the following headers not defined in 
 * RFC3261 documented in 
 * the following standards track RFCs:
 * 
 *  RAckHeader - this header is specific to the reliability of provisional 
 * Responses. This functionality is defined in RFC3262.
 * 
 RSeqHeader - this header is specific to the reliability of provisional 
 * Responses. This functionality is defined in RFC3262.
 * 
 AllowEventsHeader - this header is specific to the event notification
 * framework. This functionality is defined in RFC3265.
 * 
 EventHeader - this header is specific to the event notification
 * framework. This functionality is defined in RFC3265.
 * 
 SubscriptionStateHeader - this header is specific to the event notification
 * framework. This functionality is defined in RFC3265.
 * 
 ReasonHeader - The Reason Header provides information on why a SIP 
 * request was issued, often useful when creating services and used to 
 * encapsulate a final status code in a provisional response. This functionality 
 * is defined in RFC3326.
 * 
 * SIP header fields are similar to HTTP header fields in both syntax and
 * semantics.  Some header fields only make sense in requests or responses. 
 * These are called request header fields and response header fields, respectively. If a
 * header field appears in a message not matching its category (such as a
 * request header field in a response), it MUST be ignored.
 * 
 *Header Handling:

 * Any SIP header whose grammar is of the form:
 * 

 * 
header  =  "header-name" HCOLON header-value *(COMMA header-value)
 * 
 * 

 * allows for combining header fields of the same name into a comma-separated
 * list. In this specification each Header object has a single value or attribute pair. 
 * For example a Header whose grammer is of the form:
 * 
 
 * Allow: Invite, Bye;
 * 

 * would be represented in a SIP message with two AllowHeader objects each 
 * containing a single attribute, Invite and Bye respectively. Implementations 
 * MUST be able to parse multiple header field rows with the same name in any 
 * combination of the single-value-per-line or comma-separated value forms and 
 * translate them into the relevent Header objects defined in this specification.
 *  
 * The relative order of header objects within messages is not significant. 
 * However, it is RECOMMENDED that required header and headers which are needed
 * for proxy processing (Via, Route, Record-Route, Proxy-Require, Max-Forwards,
 * and Proxy-Authorization, for example) appear towards the top of the message
 * to facilitate rapid parsing.
 * 

 * The relative order of header objects with the same field name is important. 
 * Multiple headers with the same name MAY be present in a message if and only if 
 * the entire field-value for that header field can be defined as a 
 * comma-separated list as defined by RFC 3261. The exceptions to this rule are 
 * the WWW-Authenticate, Authorization, Proxy-Authenticate, and 
 * Proxy-Authorization header fields. Multiple header objects with these
 * names MAY be present in a message, but since their grammar does not follow
 * the general form listed above, they MUST NOT be combined into a single
 * header field row when sent over the network. 
 * 

 * Even though an arbitrary number of parameter pairs may be attached to a 
 * header object, any given parameter-name MUST NOT appear more than once.
 * 
 * @author BEA Systems, NIST
 * @version 1.2
 */

public interface Header extends Cloneable, Serializable {


    /**
     * Gets the unique string name of this Header. A name constant is defined in
     * each individual Header identifying each Header.
     *
     * @return the name of this specific Header
     */
    public String getName();

    /**
     * Compare this SIP Header for equality with another. This method overrides
     * the equals method in java.lang.Object. This method is over-ridden further 
     * for each required header (To, From, CSeq, Call-ID, Max-Forwards, and Via) 
     * which object equality is outlined as specified by  
     * RFC3261. All optional 
     * headers are compared using object equality that is each field in the 
     * header is used for comparision. When comparing header fields, field names 
     * are always case-insensitive. Unless otherwise stated in the
     * definition of a particular header field, field values, parameter names,
     * and parameter values are case-insensitive. Tokens are always
     * case-insensitive. Unless specified otherwise, values expressed as quoted
     * strings are case-sensitive.
     *
     * @param obj the object to compare this Header with.
     * @return true if obj is an instance of this class
     * representing the same SIP Header as this, false otherwise.
     */
    public boolean equals(Object obj);

    /**
     * Creates and returns a deep copy of the Header. This methods must ensure a
     * deep copy of the Header, so that when a message is cloned the Header can
     * be modified without effecting the original Header in the message. This
     * provides useful functionality for proxying Requests and Responses, for
     * example:
     * 

     * Recieve a message.
     * 
Create a deep clone of the message and headers.
     * 
Modify necessary headers.
     * 
Proxy the message using the send methods on the SipProvider.
     * 
     * This method overrides the clone method in java.lang.Object.
     *
     * @return a deep copy of Header
     */
    public Object clone();
    
    /**
     * Gets a integer hashcode representation of the Header. This method 
     * overrides the hashcode method in java.lang.Object.
     *
     * @return integer representation of Header hashcode
     * @since v1.2
     */
    public int hashCode();
    
    /**
     * Gets a string representation of the Header. This method overrides the
     * toString method in java.lang.Object.
     *
     * @return string representation of Header
     */
    public String toString();

}