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 : TransactionState.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: * 1.2 19/05/2005 Phelim O'Doherty Added equals and hashcode method
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip;
023:
024: import java.io.*;
025:
026: /**
027:
028: * This class contains the enumerations that define the underlying state of an
029: * existing transaction. SIP defines four types of
030:
031: * transactions, these are Invite Client transactions, Invite Server transactions,
032:
033: * Non-Invite Client transactions and Non-Invite Server transactions.
034:
035: *
036:
037: * There are six explicit states for the various transactions, namely:
038:
039: * <ul>
040:
041: * <li> <b>Calling:</b>
042:
043: * <ul>
044:
045: * <li> Invite Client transaction: The initial state, "calling", MUST be entered
046:
047: * when the application initiates a new client transaction with an INVITE request.
048:
049: * </ul>
050:
051: * <li> <b>Trying:</b>
052:
053: * <ul>
054:
055: * <li> Non-Invite Client transaction: The initial state "Trying" is entered
056:
057: * when the application initiates a new client transaction with a request.
058:
059: * <li> Non-Invite Server transaction: The initial state "Trying" is entered
060:
061: * when the application is passed a request other than INVITE or ACK.
062:
063: * </ul>
064:
065: * <li> <b>Proceeding:</b>
066:
067: * <ul>
068:
069: * <li> Invite Client transaction: If the client transaction receives a
070:
071: * provisional response while in the "Calling" state, it transitions to the
072:
073: * "Proceeding" state.
074:
075: * <li> Non-Invite Client transaction: If a provisional response is received
076:
077: * while in the "Trying" state, the client transaction SHOULD move to the
078:
079: * "Proceeding" state.
080:
081: * <li> Invite Server transaction: When a server transaction is constructed for
082:
083: * a request, it enters the initial state "Proceeding".
084:
085: * <li> Non-Invite Server transaction: While in the "Trying" state, if the
086:
087: * application passes a provisional response to the server transaction, the
088:
089: * server transaction MUST enter the "Proceeding" state.
090:
091: * </ul>
092:
093: * <li> <b>Completed:</b> The "Completed" state exists to buffer any additional
094:
095: * response retransmissions that may be received, which is why the client
096:
097: * transaction remains there only for unreliable transports.
098:
099: * <ul>
100:
101: * <li> Invite Client transaction: When in either the "Calling" or "Proceeding"
102:
103: * states, reception of a response with status code from 300-699 MUST cause the
104:
105: * client transaction to transition to "Completed".
106:
107: * <li> Non-Invite Client transaction: If a final response (status codes
108:
109: * 200-699) is received while in the "Trying" or "Proceeding" state, the client
110:
111: * transaction MUST transition to the "Completed" state.
112:
113: * <li> Invite Server transaction: While in the "Proceeding" state, if the
114:
115: * application passes a response with status code from 300 to 699 to the server
116:
117: * transaction, the state machine MUST enter the "Completed" state.
118:
119: * <li>Non-Invite Server transaction: If the application passes a final response
120:
121: * (status codes 200-699) to the server while in the "Proceeding" state, the
122:
123: * transaction MUST enter the "Completed" state.
124:
125: * </ul>
126:
127: * <li> <b>Confirmed:</b> The purpose of the "Confirmed" state is to absorb any
128:
129: * additional ACK messages that arrive, triggered from retransmissions of the
130:
131: * final response. Once this time expires the server MUST transition to the
132:
133: * "Terminated" state.
134:
135: * <ul>
136:
137: * <li> Invite Server transaction: If an ACK is received while the server
138:
139: * transaction is in the "Completed" state, the server transaction MUST
140:
141: * transition to the "Confirmed" state.
142:
143: * </ul>
144:
145: * <li> <b>Terminated:</b> The transaction MUST be available for garbage collection
146:
147: * the instant it enters the "Terminated" state.
148:
149: * <ul>
150:
151: * <li> Invite Client transaction: When in either the "Calling" or "Proceeding"
152:
153: * states, reception of a 2xx response MUST cause the client transaction to
154:
155: * enter the "Terminated" state. If amount of time that the server transaction
156:
157: * can remain in the "Completed" state when unreliable transports are used
158:
159: * expires while the client transaction is in the "Completed" state, the client
160:
161: * transaction MUST move to the "Terminated" state.
162:
163: * <li> Non-Invite Client transaction: If the transaction times out while the
164:
165: * client transaction is still in the "Trying" or "Proceeding" state, the client
166:
167: * transaction SHOULD inform the application about the timeout, and then it
168:
169: * SHOULD enter the "Terminated" state. If the response retransmissions buffer
170:
171: * expires while in the "Completed" state, the client transaction MUST transition
172:
173: * to the "Terminated" state.
174:
175: * <li> Invite Server transaction: If in the "Proceeding" state, and the application
176:
177: * passes a 2xx response to the server transaction, the server transaction MUST
178:
179: * transition to the "Terminated" state. When the server transaction abandons
180:
181: * retransmitting the response while in the "Completed" state, it implies that
182:
183: * the ACK was never received. In this case, the server transaction MUST
184:
185: * transition to the "Terminated" state, and MUST indicate to the TU that a
186:
187: * transaction failure has occurred.
188:
189: * <li> Non-Invite Server transaction: If the request retransmissions buffer
190:
191: * expires while in the "Completed" state, the server transaction MUST transition
192:
193: * to the "Terminated" state.
194:
195: * </ul>
196:
197: * </ul>
198:
199: *
200:
201: * For each specific transaction state machine, refer to
202:
203: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
204:
205: *
206:
207: * @author BEA Systems, NIST
208: * @version 1.2
209:
210: */
211:
212: public final class TransactionState implements Serializable {
213:
214: /**
215:
216: * Constructor for the TransactionState
217:
218: *
219:
220: * @param transactionState The integer value for the TransactionState
221:
222: */
223:
224: private TransactionState(int transactionState) {
225:
226: m_transactionState = transactionState;
227:
228: m_transStateArray[m_transactionState] = this ;
229:
230: }
231:
232: /**
233:
234: * This method returns the object value of the TransactionState
235:
236: *
237:
238: * @return The TransactionState Object
239:
240: * @param transactionState The integer value of the TransactionState
241:
242: */
243:
244: public static TransactionState getObject(int transactionState) {
245:
246: if (transactionState >= 0 && transactionState < m_size) {
247:
248: return m_transStateArray[transactionState];
249:
250: } else {
251:
252: throw new IllegalArgumentException(
253: "Invalid transactionState value");
254:
255: }
256:
257: }
258:
259: /**
260:
261: * This method returns the integer value of the TransactionState
262:
263: *
264:
265: * @return The integer value of the TransactionState
266:
267: */
268:
269: public int getValue() {
270:
271: return m_transactionState;
272:
273: }
274:
275: /**
276:
277: * Returns the designated type as an alternative object to be used when
278:
279: * writing an object to a stream.
280:
281: *
282:
283: * This method would be used when for example serializing TransactionState.EARLY
284:
285: * and deserializing it afterwards results again in TransactionState.EARLY.
286:
287: * If you do not implement readResolve(), you would not get
288:
289: * TransactionState.EARLY but an instance with similar content.
290:
291: *
292:
293: * @return the TransactionState
294:
295: * @exception ObjectStreamException
296:
297: */
298:
299: private Object readResolve() throws ObjectStreamException {
300:
301: return m_transStateArray[m_transactionState];
302:
303: }
304:
305: /**
306: * Compare this transaction state for equality with another.
307: *
308: * @since 1.2
309: * @param obj the object to compare this with.
310: * @return <code>true</code> if <code>obj</code> is an instance of this class
311: * representing the same transaction state as this, <code>false</code> otherwise.
312: */
313: public boolean equals(Object obj) {
314: if (obj == this )
315: return true;
316:
317: return (obj instanceof TransactionState)
318: && ((TransactionState) obj).m_transactionState == m_transactionState;
319: }
320:
321: /**
322: * Get a hash code value for this transaction state.
323: *
324: * @since 1.2
325: * @return a hash code value.
326: */
327: public int hashCode() {
328: return m_transactionState;
329: }
330:
331: /*
332: * This method returns a string version of this class.
333: *
334: * @return The string version of the TransactionState
335: */
336:
337: public String toString() {
338:
339: String text = "";
340:
341: switch (m_transactionState) {
342:
343: case _CALLING:
344:
345: text = "Calling Transaction";
346:
347: break;
348:
349: case _TRYING:
350:
351: text = "Trying Transaction";
352:
353: break;
354:
355: case _PROCEEDING:
356:
357: text = "Proceeding Transaction";
358:
359: break;
360:
361: case _COMPLETED:
362:
363: text = "Completed Transaction";
364:
365: break;
366:
367: case _CONFIRMED:
368:
369: text = "Confirmed Transaction";
370:
371: break;
372:
373: case _TERMINATED:
374:
375: text = "Terminated Transaction";
376:
377: break;
378:
379: default:
380:
381: text = "Error while printing Transaction State";
382:
383: break;
384:
385: }
386:
387: return text;
388:
389: }
390:
391: // internal variables
392: private int m_transactionState;
393: private static int m_size = 6;
394: private static TransactionState[] m_transStateArray = new TransactionState[m_size];
395:
396: /**
397: * This constant value indicates the internal value of the "Calling" constant.
398: * <br>This constant has an integer value of 0.
399: */
400: public static final int _CALLING = 0;
401: /**
402: * This constant value indicates that the transaction state is "Calling".
403: */
404: public final static TransactionState CALLING = new TransactionState(
405: _CALLING);
406:
407: /**
408: * This constant value indicates the internal value of the "Trying" constant.
409: * This constant has an integer value of 1.
410: */
411: public static final int _TRYING = 1;
412: /**
413: * This constant value indicates that the transaction state is "Trying".
414: */
415: public final static TransactionState TRYING = new TransactionState(
416: _TRYING);
417:
418: /**
419: * This constant value indicates the internal value of the "Proceeding"
420: * constant.
421: * <br>This constant has an integer value of 2.
422: */
423: public static final int _PROCEEDING = 2;
424: /**
425: * This constant value indicates that the transaction state is "Proceeding".
426: */
427: public final static TransactionState PROCEEDING = new TransactionState(
428: _PROCEEDING);
429:
430: /**
431: * This constant value indicates the internal value of the "Completed"
432: * constant.
433: * <br>This constant has an integer value of 3.
434: */
435: public static final int _COMPLETED = 3;
436: /**
437: * This constant value indicates that the transaction state is "Completed".
438: */
439: public final static TransactionState COMPLETED = new TransactionState(
440: _COMPLETED);
441:
442: /**
443: * This constant value indicates the internal value of the "Confirmed"
444: * constant.
445: * <br>This constant has an integer value of 4.
446: */
447: public static final int _CONFIRMED = 4;
448: /**
449: * This constant value indicates that the transaction state is "Confirmed".
450: */
451: public final static TransactionState CONFIRMED = new TransactionState(
452: _CONFIRMED);
453:
454: /**
455: * This constant value indicates the internal value of the "Terminated"
456: * constant.
457: * <br>This constant has an integer value of 5.
458: */
459: public static final int _TERMINATED = 5;
460: /**
461: * This constant value indicates that the transaction state is "Terminated".
462: */
463: public final static TransactionState TERMINATED = new TransactionState(
464: _TERMINATED);
465:
466: }
|