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 : ReasonHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty Initial version, optional header to
020: * support RFC3326.
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip.header;
023:
024: import java.text.ParseException;
025: import javax.sip.InvalidArgumentException;
026:
027: /**
028: * This interface represents the Reason header, as defined by
029: * <a href = "http://www.ietf.org/rfc/rfc3326.txt">RFC3326</a>, this header is
030: * not part of RFC3261.
031: * <p>
032: * The ReasonHeader provides information on why a SIP request was issued, often
033: * useful when creating services and also used to encapsulate a final status code in
034: * a provisional response, which is needed to resolve the "Heterogeneous Error
035: * Response Forking Problem".
036: * <p>
037: * The Reason header field appears to be most useful for BYE and CANCEL requests,
038: * but it can appear in any request within a dialog, in any CANCEL request and
039: * in 155 (Update Requested) responses. When used in requests, clients and
040: * servers are free to ignore this header field. It has no impact on protocol
041: * processing.
042: * <p>
043: * Examples of the ReasonHeader usage are:
044: * <ul>
045: * <li> A SIP CANCEL request can be issued if the call has completed on another
046: * branch or was abandoned before answer. While the protocol and system behavior
047: * is the same in both cases, namely, alerting will cease, the user interface
048: * may well differ. In the second case, the call may be logged as a missed call,
049: * while this would not be appropriate if the call was picked up elsewhere.
050: * <li> Third party call controllers sometimes generate a SIP request upon
051: * reception of a SIP response from another dialog. Gateways generate SIP
052: * requests after receiving messages from a different protocol than SIP. In
053: * both cases the client may be interested in knowing what triggered the SIP
054: * request.
055: * <li> An INVITE can sometimes be rejected not because the session initiation
056: * was declined, but because some aspect of the request was not acceptable. If
057: * the INVITE forked and resulted in a rejection, the error response may never
058: * be forwarded to the client unless all the other branches also reject the
059: * request. This problem is known as the "Heterogeneous Error Response Forking
060: * Problem". The header field defined in this draft allows encapsulating the
061: * final error response in a 155 (Update Requested) provisional response.
062: * </ul>
063: * A server must ignore Headers that it does not understand. A proxy must not
064: * remove or modify Headers that it does not understand.
065: *
066: * @author BEA Systems, NIST
067: * @version 1.2
068: */
069:
070: public interface ReasonHeader extends Parameters, Header {
071:
072: /**
073: * Gets the cause value of the ReasonHeader
074: *
075: * @return the integer value of the cause of the ReasonHeader
076: */
077: public int getCause();
078:
079: /**
080: * Sets the cause value of the ReasonHeader. Any SIP status code MAY
081: * appear in the Reason header field of a request, assuming the protocol
082: * field of the ReasonHeader is SIP.
083: *
084: * @param cause - the new integer value of the cause of the ReasonHeader
085: * @throws InvalidArgumentException if the cause value is less than zero.
086: */
087: public void setCause(int cause) throws InvalidArgumentException;
088:
089: /**
090: * Sets the protocol of the ReasonHeader, for example SIP or Q.850.
091: *
092: * @param protocol - the new string value of the protocol of the ReasonHeader
093: * @throws ParseException which signals that an error has been reached
094: * unexpectedly while parsing the protocol value.
095: */
096: public void setProtocol(String protocol) throws ParseException;
097:
098: /**
099: * Gets the protocol value of the ReasonHeader
100: *
101: * @return the string value of the protocol of the ReasonHeader
102: */
103: public String getProtocol();
104:
105: /**
106: * Sets the text value of the ReasonHeader.
107: *
108: * @param text - the new string value of the text of the ReasonHeader
109: * @throws ParseException which signals that an error has been reached
110: * unexpectedly while parsing the text value.
111: */
112: public void setText(String text) throws ParseException;
113:
114: /**
115: * Gets the text value of the ReasonHeader
116: *
117: * @return the string value of the text of the ReasonHeader
118: */
119: public String getText();
120:
121: /**
122: * Name of ReasonHeader
123: */
124: public final static String NAME = "Reason";
125:
126: }
|