001: /**
002: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
004: *
005: * This program is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU General Public License version
007: * 2 only, as published by the Free Software Foundation.
008: *
009: * This program is distributed in the hope that it will be useful, but
010: * WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * General Public License version 2 for more details (a copy is
013: * included at /legal/license.txt).
014: *
015: * You should have received a copy of the GNU General Public License
016: * version 2 along with this work; if not, write to the Free Software
017: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
018: * 02110-1301 USA
019: *
020: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
021: * Clara, CA 95054 or visit www.sun.com if you need additional
022: * information or have any questions.
023: *
024: *
025: * Module Name : JAIN SIP Specification
026: * File Name : Timeout.java
027: *
028: * HISTORY
029: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
030: */package gov.nist.siplite;
031:
032: import gov.nist.siplite.stack.Transaction;
033:
034: /**
035: * This class contains the enumerations that define whether a timeout has
036: * occured in the underlying implementation. The application gets
037: * informed on whether a retransmission or transaction timer has expired.
038: *
039: * There are two types of Timeout, namely:
040: * <ul>
041: * <li> {@link Timeout#RETRANSMIT} - This type is used to alert an
042: * application that
043: * the underlying retransmit timer has expired so an application can
044: * resend the message specific to a transaction. This timer is defaulted to
045: * 500ms and is doubled each time it is fired until the transaction expires
046: * {@link Timeout#TRANSACTION}. The default retransmission value can be changed
047: * per transaction using {@link Transaction#enableRetransmissionTimer(int)}. The
048: * RETRANSMIT type is exposed to the following applications as follows:
049: * <UL>
050: * <li><b>User Agent</b> - Retransmissions on Invite transactions are the
051: * responsibility of the application. This is due to the three way handshake
052: * for an INVITE Request. All other retransmissions are handled by the
053: * underlying
054: * implementation. Therefore the application will only receive this
055: * Timeout type
056: * specific to Invite transactions.
057: * <li><b>User Agent with No Retransmission</b> - an application can
058: * configure an
059: * implementation to handle all retransmissions using property characteristics
060: * of the {@link SipStack}. Therefore a Timeout
061: * of this type will not be passed to the application. The application
062: * will only get notified when the {@link Timeout#TRANSACTION} occurs.
063: * <li><b>Stateful Proxy</b> - a stateful proxy remembers transaction
064: * state about
065: * each incoming request and any requests it sends as a result of
066: * processing the incoming request. The underlying implementation
067: * will handle the retransmissions of all messages it sends and the application
068: * will not receive {@link Timeout#RETRANSMIT} events, however the application
069: * will get notified of {@link Timeout#TRANSACTION} events. As an Invite
070: * transaction is end to end a stateful proxy will not handle the
071: * retransmissions of messages on an Invite transaction, unless it decides to
072: * respond to the Invite transaction, in essence becoming an User Agent Server
073: * and as such should behave as described by the User Agent semantics above
074: * bearing in mind the retranmission property of the underlying implementation.
075: * <li><b>Stateless Proxy</b> - as a stateless proxy acts as a simple forwarding
076: * agent, i.e. it simply forwards every message it receives upstream, it
077: * keeps no transaction state for messages. The implementation does
078: * not retransmit
079: * messages, therefore an application will not receive {@link
080: * Timeout#RETRANSMIT}
081: * events on a message handled statelessly. If retransmission semantics are
082: * required by an application using a stateless method, it is the responsibility
083: * of the application to provide this feature, not the underlying
084: * implementation.
085: * </UL>
086: * <li>{@link Timeout#TRANSACTION} - This type is used to alert an application
087: * that the underlying transaction has expired. A transaction timeout typically
088: * occurs at a time 64*T1 were T1 is the initial value of the
089: * {@link Timeout#RETRANSMIT}, usually defaulted to 500ms. The
090: * TRANSACTION type is exposed to the following applications as follows:
091: * <UL>
092: * <li><b>User Agent</b> - All retransmissions except retransmissions on Invite
093: * transactions are the responsibility of the underlying implementation, i.e.
094: * Invite transactions are the responsibility of the application. Therefore the
095: * application will only recieve TRANSACTION Timeout events on
096: * transactions that
097: * are not Invite transactions.
098: * <li><b>User Agent with No Retransmission</b> - an application can
099: * configure an
100: * implementation to handle all retransmissions using property characteristics
101: * of the {@link SipStack}. Therefore a TRANSACTION Timeout will be fired to
102: * the application on any transaction that expires including an Invite
103: * transaction.
104: * <li><b>Stateful Proxy</b> - a stateful proxy remembers transaction
105: * state about
106: * each incoming request and any requests it sends as a result of
107: * processing the incoming request. The underlying implementation handles
108: * the retransmissions of all messages it sends and will notify the application
109: * of {@link Timeout#TRANSACTION} events on any of its
110: * transactions. As an Invite
111: * transaction is end to end a stateful proxy will not handle transaction
112: * timeouts on an Invite transaction, unless it decides to respond to the Invite
113: * transaction, in essence becoming an User Agent Server and as such should
114: * behave as described by the User Agent semantics above bearing in mind
115: * the retransmission property of the underlying implementation.
116: * <li><b>Stateless Proxy</b> - as a stateless proxy acts as a simple forwarding
117: * agent, i.e. it simply forwards every message it receives upstream, it
118: * keeps no transaction state of the messages. The implementation does not
119: * maintain transaction state, therefore an application will not receive
120: * {@link Timeout#TRANSACTION} events on a message handled statelessly.
121: * If transaction timeout semantics are required by an application using a
122: * stateless method, it the responsibility of the application to provide this
123: * feature, not the underlying implementation.
124: * </ul>
125: * </ul>
126: *
127: * @since 1.1
128: */
129: public final class Timeout {
130:
131: /**
132: * Constructor for the Timeout.
133: *
134: * @param timeout the integer value for the Timeout
135: */
136: private Timeout(int timeout) {
137: m_timeout = timeout;
138: m_timeoutArray[m_timeout] = this ;
139: }
140:
141: /**
142: * This method returns the object value of the Timeout.
143: *
144: * @param timeout The integer value of the Timeout
145: * @return The Timeout Object
146: */
147: public Timeout getObject(int timeout)
148: throws IllegalArgumentException {
149: if (timeout >= 0 && timeout < m_size) {
150: return m_timeoutArray[timeout];
151: } else {
152: throw new IllegalArgumentException("Invalid timeout value");
153: }
154: }
155:
156: /**
157: * This method returns the integer value of the Timeout.
158: *
159: * @return The integer value of the Timeout
160: */
161: public int getValue() {
162: return m_timeout;
163: }
164:
165: /**
166: * Returns the designated type as an alternative object to be used when
167: * writing an object to a stream.
168: *
169: * This method would be used when for example serializing Timeout.RETRANSMIT
170: * and deserializing it afterwards results again in Timeout.RETRANSMIT.
171: * If you do not implement readResolve(), you would not get
172: * Timeout.RETRANSMIT but an instance with similar content.
173: *
174: * @return the Timeout
175: * @exception ObjectStreamException
176: */
177: private Object readResolve() {
178: return m_timeoutArray[m_timeout];
179: }
180:
181: /**
182: * This method returns a string version of this class.
183: *
184: * @return The string version of the Timeout
185: */
186: public String toString() {
187: String text = "";
188: switch (m_timeout) {
189: case _RETRANSMIT:
190: text = "Retransmission Timeout";
191: break;
192: case _TRANSACTION:
193: text = "Transaction Timeout";
194: break;
195: default:
196: text = "Error while printing Timeout";
197: break;
198: }
199: return text;
200: }
201:
202: /** Current transaction timeout. */
203: private int m_timeout;
204: /** Size of timeout array. */
205: private static int m_size = 2;
206: /** Array of timeout values. */
207: private static Timeout[] m_timeoutArray = new Timeout[m_size];
208:
209: /**
210: * This constant value indicates the internal value of the Retransmit
211: * timeout.
212: * <br>This constant has an integer value of 0.
213: */
214: public final static int _RETRANSMIT = 0;
215: /**
216: * This constant value indicates the "Retransmit" timeout.
217: */
218: public final static Timeout RETRANSMIT = new Timeout(_RETRANSMIT);
219:
220: /**
221: * This constant value indicates the internal value of the Transaction
222: * timeout.
223: * <br>This constant has an integer value of 1.
224: */
225: public final static int _TRANSACTION = 1;
226:
227: /**
228: * This constant value indicates the "Transaction" timeout.
229: */
230: public final static Timeout TRANSACTION = new Timeout(_TRANSACTION);
231:
232: }
|