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 : Timeout.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
020: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
021: */package javax.sip;
022:
023: import java.io.*;
024:
025: /**
026: * This class contains the enumerations that define whether a timeout has
027: * occured in the underlying implementation. The application gets
028: * informed on whether a retransmission or transaction timer has expired.
029: *
030: * There are two types of Timeout, namely:
031: * <ul>
032: * <li> {@link Timeout#RETRANSMIT} - This type is used to alert an application that
033: * the underlying retransmit timer has expired so an application can
034: * resend the message specific to a transaction. This timer is defaulted to
035: * 500ms and is doubled each time it is fired until the transaction expires
036: * {@link Timeout#TRANSACTION}. The default retransmission value can be changed
037: * per transaction using {@link Transaction#setRetransmitTimer(int)}. The
038: * RETRANSMIT type is exposed to the following applications as follows:
039: * <UL>
040: * <li><b>User Agent</b> - Retransmissions on Invite transactions are the
041: * responsibility of the application. This is due to the three way handshake
042: * for an INVITE Request. All other retransmissions are handled by the underlying
043: * implementation. Therefore the application will only receive this Timeout type
044: * specific to Invite transactions.
045: * <li><b>User Agent with No Retransmission</b> - an application can configure an
046: * implementation to handle all retransmissions using property characteristics
047: * of the {@link SipStack}. Therefore a Timeout
048: * of this type will not be passed to the application. The application
049: * will only get notified when the {@link Timeout#TRANSACTION} occurs.
050: * <li><b>Stateful Proxy</b> - a stateful proxy remembers transaction state about
051: * each incoming request and any requests it sends as a result of
052: * processing the incoming request. The underlying implementation
053: * will handle the retransmissions of all messages it sends and the application
054: * will not receive {@link Timeout#RETRANSMIT} events, however the application
055: * will get notified of {@link Timeout#TRANSACTION} events. As an Invite
056: * transaction is end to end a stateful proxy will not handle the
057: * retransmissions of messages on an Invite transaction, unless it decides to
058: * respond to the Invite transaction, in essence becoming an User Agent Server
059: * and as such should behave as described by the User Agent semantics above
060: * bearing in mind the retranmission property of the underlying implementation.
061: * <li><b>Stateless Proxy</b> - as a stateless proxy acts as a simple forwarding
062: * agent, i.e. it simply forwards every message it receives upstream, it
063: * keeps no transaction state for messages. The implementation does not retransmit
064: * messages, therefore an application will not receive {@link Timeout#RETRANSMIT}
065: * events on a message handled statelessly. If retransmission semantics are
066: * required by an application using a stateless method, it is the responsibility
067: * of the application to provide this feature, not the underlying implementation.
068: * </UL>
069: * <li>{@link Timeout#TRANSACTION} - This type is used to alert an application
070: * that the underlying transaction has expired. A transaction timeout typically
071: * occurs at a time 64*T1 were T1 is the initial value of the
072: * {@link Timeout#RETRANSMIT}, usually defaulted to 500ms. The
073: * TRANSACTION type is exposed to the following applications as follows:
074: * <UL>
075: * <li><b>User Agent</b> - All retransmissions except retransmissions on Invite
076: * transactions are the responsibility of the underlying implementation, i.e.
077: * Invite transactions are the responsibility of the application. Therefore the
078: * application will only recieve TRANSACTION Timeout events on transactions that
079: * are not Invite transactions.
080: * <li><b>User Agent with No Retransmission</b> - an application can configure an
081: * implementation to handle all retransmissions using property characteristics
082: * of the {@link SipStack}. Therefore a TRANSACTION Timeout will be fired to
083: * the application on any transaction that expires including an Invite
084: * transaction.
085: * <li><b>Stateful Proxy</b> - a stateful proxy remembers transaction state about
086: * each incoming request and any requests it sends as a result of
087: * processing the incoming request. The underlying implementation handles
088: * the retransmissions of all messages it sends and will notify the application
089: * of {@link Timeout#TRANSACTION} events on any of its transactions. As an Invite
090: * transaction is end to end a stateful proxy will not handle transaction
091: * timeouts on an Invite transaction, unless it decides to respond to the Invite
092: * transaction, in essence becoming an User Agent Server and as such should
093: * behave as described by the User Agent semantics above bearing in mind
094: * the retransmission property of the underlying implementation.
095: * <li><b>Stateless Proxy</b> - as a stateless proxy acts as a simple forwarding
096: * agent, i.e. it simply forwards every message it receives upstream, it
097: * keeps no transaction state of the messages. The implementation does not
098: * maintain transaction state, therefore an application will not receive
099: * {@link Timeout#TRANSACTION} events on a message handled statelessly.
100: * If transaction timeout semantics are required by an application using a
101: * stateless method, it the responsibility of the application to provide this
102: * feature, not the underlying implementation.
103: * </ul>
104: * </ul>
105: *
106: * @author BEA Systems, NIST
107: * @version 1.2
108: */
109: public final class Timeout implements Serializable {
110:
111: /**
112: * Constructor for the Timeout
113: *
114: * @param timeout the integer value for the Timeout
115: */
116: private Timeout(int timeout) {
117: m_timeout = timeout;
118: m_timeoutArray[m_timeout] = this ;
119: }
120:
121: /**
122: * This method returns the object value of the Timeout
123: *
124: * @return The Timeout Object
125: * @param timeout The integer value of the Timeout
126: */
127: public Timeout getObject(int timeout) {
128: if (timeout >= 0 && timeout < m_size) {
129: return m_timeoutArray[timeout];
130: } else {
131: throw new IllegalArgumentException("Invalid timeout value");
132: }
133: }
134:
135: /**
136: * This method returns the integer value of the Timeout
137: *
138: * @return The integer value of the Timeout
139: */
140: public int getValue() {
141: return m_timeout;
142: }
143:
144: /**
145: * Returns the designated type as an alternative object to be used when
146: * writing an object to a stream.
147: *
148: * This method would be used when for example serializing Timeout.RETRANSMIT
149: * and deserializing it afterwards results again in Timeout.RETRANSMIT.
150: * If you do not implement readResolve(), you would not get
151: * Timeout.RETRANSMIT but an instance with similar content.
152: *
153: * @return the Timeout
154: * @exception ObjectStreamException
155: */
156: private Object readResolve() throws ObjectStreamException {
157: return m_timeoutArray[m_timeout];
158: }
159:
160: /**
161: * This method returns a string version of this class.
162: *
163: * @return The string version of the Timeout
164: */
165: public String toString() {
166: String text = "";
167: switch (m_timeout) {
168: case _RETRANSMIT:
169: text = "Retransmission Timeout";
170: break;
171:
172: case _TRANSACTION:
173: text = "Transaction Timeout";
174: break;
175: default:
176: text = "Error while printing Timeout";
177: break;
178: }
179: return text;
180: }
181:
182: // internal variables
183: private int m_timeout;
184: private static int m_size = 2;
185: private static Timeout[] m_timeoutArray = new Timeout[m_size];
186:
187: /**
188: * This constant value indicates the internal value of the Retransmit
189: * timeout.
190: * <br>This constant has an integer value of 0.
191: */
192: public final static int _RETRANSMIT = 0;
193: /**
194: * This constant value indicates the "Retransmit" timeout.
195: */
196: public final static Timeout RETRANSMIT = new Timeout(_RETRANSMIT);
197:
198: /**
199: * This constant value indicates the internal value of the Transaction
200: * timeout.
201: * <br>This constant has an integer value of 1.
202: */
203: public final static int _TRANSACTION = 1;
204:
205: /**
206: * This constant value indicates the "Transaction" timeout.
207: */
208: public final static Timeout TRANSACTION = new Timeout(_TRANSACTION);
209:
210: }
|