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 : Transaction.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 12/15/2004 M. Ranganathan Clarified behavior of getDialog when
021: * Phelim O'Doherty AUTOMATIC_DIALOG_SUPPORT is set to off.
022: * Added two methods - set/getApplicationData
023: * Added terminate method.
024: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
025: */package javax.sip;
026:
027: import javax.sip.Dialog;
028: import javax.sip.message.Request;
029: import java.io.Serializable;
030:
031: /**
032: * Transactions are a fundamental component of SIP. A transaction is a request
033: * sent by a client transaction to a server transaction, along with all
034: * responses to that request sent from the server transaction back to the client
035: * transactions. User agents contain a transaction layer, as do stateful proxies.
036: * Stateless proxies do not contain a transaction layer. This specification
037: * provides the capabilities to allow either the SipProvider or SipListener to
038: * handle transactional functionality.
039: * <p>
040: * This interface represents a generic transaction interface defining the methods
041: * common between client and server transactions.
042: *
043: * @see TransactionState
044: * @author BEA Systems, NIST
045: * @version 1.2
046: */
047:
048: public interface Transaction extends Serializable {
049:
050: /**
051: * Gets the dialog object of this transaction object. A dialog only
052: * exists for a transaction when a session is setup between a User Agent
053: * Client and a User Agent Server, either by a 1xx Provisional Response
054: * for an early dialog or a 200OK Response for a committed dialog.
055: *
056: * <ul>
057: * <li>If the stack is configured with the AUTOMATIC_DIALOG_SUPPORT property set to
058: * </it>ON</it> ( default behavior ) then the following behavior is defined:
059: * <ul>
060: * <li>If the transaction is associated with an existing Dialog or could result
061: * in a Dialog being created in the future (ie. the stack is configured
062: * to recognize the method as a Dialog creating method or is one of the
063: * natively supported dialog creating methods such as INVITE, SUBSCRIBE or
064: * REFER), then the implementation must either associate the transaction
065: * with the existing Dialog or create a Dialog with null state.
066: * <li>If the Transaction is neither dialog creating nor can be associated with
067: * an existing dialog, then the implementation must return null when the
068: * application issues getDialog on the transaction.
069: * </ul>
070: * <li>If the stack is configured with AUTOMATIC_DIALOG property set to </it>OFF</it>
071: * then the stack does not automatically create a Dialog for a transaction nor does
072: * it maintain an association between dialog and transaction on behalf of the
073: * application. Hence this method will return null.
074: * It is the responsibility of the application to create a Dialog and associate
075: * it with the transaction when the response is sent.
076: * </ul>
077: *
078: * @return the dialog object of this transaction object or null if no
079: * dialog exists.
080: * @see Dialog
081: */
082: public Dialog getDialog();
083:
084: /**
085: * Returns the current state of the transaction. Returns the current
086: * TransactionState of this Transaction or null if a ClientTransaction has
087: * yet been used to send a message.
088: *
089: * @return a TransactionState object determining the current state of the
090: * transaction.
091: */
092: public TransactionState getState();
093:
094: /**
095: * Returns the current value of the retransmit timer in milliseconds used
096: * to retransmit messages over unreliable transports for this transaction.
097: *
098: * @return the integer value of the retransmit timer in milliseconds.
099: * @throws UnsupportedOperationException if this method is not supported
100: * by the underlying implementation.
101: */
102: public int getRetransmitTimer()
103: throws UnsupportedOperationException;
104:
105: /**
106: * Sets the value of the retransmit timer to the newly supplied timer value.
107: * The retransmit timer is expressed in milliseconds and its default value
108: * is 500ms. This method allows the application to change the transaction
109: * retransmit behavior for different networks. For example the gateway proxy,
110: * the internal intranet is likely to be relatively uncongested
111: * and the endpoints will be relatively close. The external network is the
112: * general Internet. This functionality allows different retransmit times
113: * for either side.
114: *
115: * @param retransmitTimer - the new integer value of the retransmit timer
116: * in milliseconds.
117: * @throws UnsupportedOperationException if this method is not supported
118: * by the underlying implementation.
119: */
120: public void setRetransmitTimer(int retransmitTimer)
121: throws UnsupportedOperationException;
122:
123: /**
124: * Returns a unique branch identifer that identifies this transaction. The
125: * branch identifier is used in the ViaHeader. The uniqueness property of
126: * the branch ID parameter to facilitate its use as a transaction ID, was
127: * not part of RFC 2543. The branch ID inserted by an element compliant
128: * with the RFC3261 specification MUST always begin with the characters
129: * "z9hG4bK". These 7 characters are used as a magic cookie, so that
130: * servers receiving the request can determine that the branch ID was
131: * constructed to be globally unique. The precise format of the branch
132: * token is implementation-defined. This method should always return the
133: * same branch identifier for the same transaction.
134: *
135: * @return the new branch that uniquely identifies this transaction.
136: */
137: public String getBranchId();
138:
139: /**
140: * Returns the request that created this transaction. The transaction state
141: * machine needs to keep the Request that resulted in the creation of this
142: * transaction while the transaction is still alive. Applications also need
143: * to access this information, e.g. a forking proxy server may wish to
144: * retrieve the original Invite request to cancel branches of a fork when
145: * a final Response has been received by one branch.
146: *
147: * @return the Request message that created this transaction.
148: */
149: public Request getRequest();
150:
151: /**
152: * This method allows applications to associate application context with
153: * the transaction. This specification does not define the format of this
154: * data, this the responsibility of the application and is dependent
155: * on the application. This capability may be useful for proxy servers
156: * to associate the transaction to some application state. The context of
157: * this application data is un-interpreted by the stack.
158: *
159: * @param applicationData - un-interpreted application data.
160: * @since v1.2
161: *
162: */
163:
164: public void setApplicationData(Object applicationData);
165:
166: /**
167: * Returns the application data associated with the transaction.This
168: * specification does not define the format of this application specific
169: * data. This is the responsibility of the application.
170: *
171: * @return application data associated with the transaction by the application.
172: * @since v1.2
173: *
174: */
175: public Object getApplicationData();
176:
177: /**
178: * Terminate this transaction and immediately release all stack resources
179: * associated with it. When a transaction is terminated using this method,
180: * a transaction terminated event is sent to the listener. If the
181: * transaction is already associated with a dialog, it cannot be terminated
182: * using this method. Instead, the dialog should be deleted to remove the
183: * transaction.
184: *
185: * @throws ObjectInUseException if the transaction cannot be terminated as
186: * it is associated to a dialog.
187: * @since v1.2
188: */
189: public void terminate() throws ObjectInUseException;
190:
191: }
|