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 : ToHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty
020: * 12/15/2004 M. Ranganathan Added clarification for To header setTag()
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip.header;
023:
024: import java.text.ParseException;
025:
026: /**
027: * The To header field first and foremost specifies the desired "logical"
028: * recipient of the request, or the address-of-record of the user or resource
029: * that is the target of this request. This may or may not be the ultimate
030: * recipient of the request. Requests and Responses must contain a ToHeader,
031: * indicating the desired recipient of the Request. The UAS or redirect server
032: * copies the ToHeader into its Response.
033: * <p>
034: * The To header field MAY contain a SIP or SIPS URI, but it may also make use
035: * of other URI schemes i.e the telURL, when appropriate. All SIP
036: * implementations MUST support the SIP URI scheme. Any implementation that
037: * supports TLS MUST support the SIPS URI scheme. Like the From header field,
038: * it contains a URI and optionally a display name, encapsulated in a
039: * {@link javax.sip.address.Address}.
040: * <p>
041: * A UAC may learn how to populate the To header field for a particular request
042: * in a number of ways. Usually the user will suggest the To header field
043: * through a human interface, perhaps inputting the URI manually or selecting
044: * it from some sort of address book. Using the string to form the user part
045: * of a SIP URI implies that the User Agent wishes the name to be resolved in the
046: * domain to the right-hand side (RHS) of the at-sign in the SIP URI. Using
047: * the string to form the user part of a SIPS URI implies that the User Agent wishes to
048: * communicate securely, and that the name is to be resolved in the domain to
049: * the RHS of the at-sign. The RHS will frequently be the home domain of the
050: * requestor, which allows for the home domain to process the outgoing request.
051: * This is useful for features like "speed dial" that require interpretation of
052: * the user part in the home domain.
053: * <p>
054: * The telURL may be used when the User Agent does not wish to specify the domain that
055: * should interpret a telephone number that has been input by the user. Rather,
056: * each domain through which the request passes would be given that opportunity.
057: * As an example, a user in an airport might log in and send requests through
058: * an outbound proxy in the airport. If they enter "411" (this is the phone
059: * number for local directory assistance in the United States), that needs to
060: * be interpreted and processed by the outbound proxy in the airport, not the
061: * user's home domain. In this case, tel:411 would be the right choice.
062: * <p>
063: * Two To header fields are equivalent if their URIs match, and their
064: * parameters match. Extension parameters in one header field, not present in
065: * the other are ignored for the purposes of comparison. This means that the
066: * display name and presence or absence of angle brackets do not affect
067: * matching.
068: * <ul>
069: * <li> The "Tag" parameter - is used in the To and From header fields of SIP
070: * messages. It serves as a general mechanism to identify a dialog, which is
071: * the combination of the Call-ID along with two tags, one from each
072: * participant in the dialog. When a UA sends a request outside of a dialog,
073: * it contains a From tag only, providing "half" of the dialog ID. The dialog
074: * is completed from the response(s), each of which contributes the second half
075: * in the To header field. When a tag is generated by a UA for insertion into
076: * a request or response, it MUST be globally unique and cryptographically
077: * random with at least 32 bits of randomness. Besides the requirement for
078: * global uniqueness, the algorithm for generating a tag is implementation
079: * specific. Tags are helpful in fault tolerant systems, where a dialog is to
080: * be recovered on an alternate server after a failure. A UAS can select the
081: * tag in such a way that a backup can recognize a request as part of a dialog
082: * on the failed server, and therefore determine that it should attempt to
083: * recover the dialog and any other state associated with it.
084: * </ul>
085: * A request outside of a dialog MUST NOT contain a To tag; the tag in the To
086: * field of a request identifies the peer of the dialog. Since no dialog is
087: * established, no tag is present.
088: * <p>
089: * For Example:<br>
090: * <code>To: Carol sip:carol@jcp.org<br>
091: * To: Duke sip:duke@jcp.org;tag=287447</code>
092: *
093: * @see HeaderAddress
094: * @author BEA Systems, NIST
095: * @version 1.2
096: */
097: public interface ToHeader extends HeaderAddress, Parameters, Header {
098:
099: /**
100: * Sets the tag parameter of the ToHeader. The tag in the To field of a
101: * request identifies the peer of the dialog. If no dialog is established,
102: * no tag is present.
103: * <p>
104: * The To Header MUST contain a new "tag" parameter. When acting as a UAC
105: * the To "tag" is maintained by the SipProvider from the dialog layer,
106: * however whan acting as a UAS the To "tag" is assigned by the application.
107: * That is the tag assignment for outbound responses for messages in a
108: * dialog is only the responsibility of the application for the first
109: * outbound response. If AUTOMATIC_DIALOG_SUPPORT is set to <it>on</it>
110: * (default behavior) then, after dialog establishment, the stack will take care
111: * of the tag assignment. Null is acceptable as a tag value. Supplying null
112: * for the tag results in a header without a tag.
113: *
114: * @param tag - the new tag of the To Header
115: * @throws ParseException which signals that an error has been reached
116: * unexpectedly while parsing the Tag value.
117: */
118: public void setTag(String tag) throws ParseException;
119:
120: /**
121: * Gets tag of ToHeader. The Tag parameter identified the Peer of the
122: * dialogue.
123: *
124: * @return the tag parameter of the ToHeader. Returns null if no Tag is
125: * present, i.e no dialogue is established.
126: */
127: public String getTag();
128:
129: /**
130: * Compare this ToHeader for equality with another. This method
131: * overrides the equals method in javax.sip.Header. This method specifies
132: * object equality as outlined by
133: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
134: * Two To header fields are equivalent if their URIs match, and their
135: * parameters match. Extension parameters in one header field, not present
136: * in the other are ignored for the purposes of comparison. This means that
137: * the display name and presence or absence of angle brackets do not affect
138: * matching. When comparing header fields, field names are always
139: * case-insensitive. Unless otherwise stated in the definition of a
140: * particular header field, field values, parameter names, and parameter
141: * values are case-insensitive. Tokens are always case-insensitive. Unless
142: * specified otherwise, values expressed as quoted strings are case-sensitive.
143: *
144: * @param obj the object to compare this ToHeader with.
145: * @return <code>true</code> if <code>obj</code> is an instance of this class
146: * representing the same ToHeader as this, <code>false</code> otherwise.
147: * @since v1.2
148: */
149: public boolean equals(Object obj);
150:
151: /**
152: * Name of the ToHeader
153: */
154: public final static String NAME = "To";
155: }
|