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 : ServerTransaction.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 javax.sip.message.Response;
024:
025: /**
026: * A server transaction is used by a SipProvider to handle incoming Request
027: * messages to fire Request events to the SipListener on a specific server
028: * transaction and by a User Agent Server application to send Response
029: * messages to a User Agent Client application. This interfaces enables an
030: * application to send a {@link javax.sip.message.Response} to a recently
031: * received Request in a transaction stateful way.
032: * <p>
033: * A new server transaction is generated in the following ways:
034: * <ul>
035: * <li> By the application by invoking the
036: * {@link SipProvider#getNewServerTransaction(Request)} for Requests that the
037: * application wishes to handle.
038: * <li> By the SipProvider by automatically populating the server transaction
039: * of a RequestEvent for Incoming Requests that match an existing Dialog. Note
040: * that a dialog-stateful application is automatically transaction
041: * stateful too
042: * </ul>
043: * A server transaction of the transaction layer is represented by a finite
044: * state machine that is constructed to process a particular request under
045: * the covers of a stateful SipProvider. The transaction layer handles
046: * application-layer retransmissions, matching of responses to requests, and
047: * application-layer timeouts.
048: * <p>
049: * The server transaction Id must be unique within the underlying
050: * implementation. This Id is commonly taken from the branch parameter in the
051: * topmost Via header (for RFC3261 compliant clients), but may also be computed as a
052: * cryptographic hash of the To tag, From tag, Call-ID header field, the
053: * Request-URI of the request received (before translation), the topmost Via
054: * header, and the sequence number from the CSeq header field, in addition to
055: * any Proxy-Require and Proxy-Authorization header fields that may be present.
056: * The algorithm used to determine the id is implementation-dependent.
057: * <p>
058: * For the detailed server transaction state machines refer to Chapter
059: * 17 of <a href="http://www.ietf.org/rfc/rfc3261.txt">RFC 3261</a>, the
060: * allowable transitions are summarized below:
061: * <p>
062: * <b>Invite Transaction:</b><br>
063: * Proceeding --> Completed --> Confirmed --> Terminated
064: * <p>
065: * <b>Non-Invite Transaction:</b><br>
066: * Trying --> Proceeding --> Completed --> Terminated
067: *
068: * @author BEA Systems, NIST
069: * @version 1.2
070: */
071: public interface ServerTransaction extends Transaction {
072:
073: /**
074: * Sends the Response to a Request which is associated with this
075: * ServerTransaction. When an application wishes to send a Response, it
076: * creates a Response using the {@link javax.sip.message.MessageFactory} and
077: * then passes that Response to this method. The Response message gets sent out on
078: * the network via the ListeningPoint information that is associated with
079: * the SipProvider of this ServerTransaction.
080: * <p>
081: * This method implies that the application is functioning as either a UAS
082: * or a stateful proxy, hence the underlying implementation acts statefully.
083: * When a UAS sends a 2xx response to an INVITE, the server transaction is
084: * transitions to the TerminatedState. The implementation may delay physically
085: * removing ServerTransaction record from memory to catch retransmissions
086: * of the INVITE in accordance with the reccomendation of
087: * <a href="http://bugs.sipit.net/show_bug.cgi?id=769"> http://bugs.sipit.net/show_bug.cgi?id=769 </a>.
088: *
089: *
090: * <p><b>ACK Processing and final response retransmission:</b> <br/>
091: * If a Dialog is associated
092: * with the ServerTransaction then when the UAC sends the ACK ( the typical case for User Agents),
093: * the Application ( i.e. Listener )
094: * will see a ServerTransaction corresponding to the ACK and the corresponding
095: * {@link Dialog} presented to it. The ACK will be presented to the Listener only
096: * once in this case. Retransmissions of the OK and filtering of ACK retransmission
097: * are the responsibility of the Dialog layer of this specification. However
098: * if no {@link Dialog} is associated with the INVITE Transaction, the ACK will be presented
099: * to the Application with a null Dialog in the {@link RequestEvent} and there will be
100: * no Dialog associated with the ACK Transaction
101: * (i.e. {@link Transaction#getDialog()} returns null).
102: * In this case (when there is no Dialog associated with the original INVITE or ACK)
103: * the Application is responsible for retransmission
104: * of the OK for the INVITE if necessary (i.e. if it wants to manage its own dialog layer and
105: * function as a User Agent) and for dealing with retransmissions of the ACK. This
106: * requires that the three way handshake of an INVITE is managed by the UAS
107: * application and not the implementation of this specification.
108: *
109: * <p>
110: * Note that Responses created via {@link Dialog#createReliableProvisionalResponse(int)}
111: * should be sent using {@link Dialog#sendReliableProvisionalResponse(Response)}
112: *
113: * @param response the Response to send to the Request.
114: * @throws SipException if the SipProvider cannot send the Response for any
115: * other reason.
116: * @throws InvalidArgumentException if the Response is created by
117: * {@link Dialog#createReliableProvisionalResponse(int)} and
118: * the application attempts to use this method to send the response.
119: * @see Response
120: */
121: public void sendResponse(Response response) throws SipException,
122: InvalidArgumentException;
123:
124: /**
125: * Enable the timeout retransmit notifications for the ServerTransaction. This method is
126: * invoked by UAs that do want to be alerted by the
127: * stack to retransmit 2XX responses but that do NOT want to associate a Dialog.
128: * The Default operation is to disable retransmission alerts for the Server Transaction
129: * when no Dialog is associated with the Server Transaction, as is common
130: * for a Proxy server.
131: * When this method is called, the stack will continue to generate {@link Timeout#RETRANSMIT}
132: * until the application calls {@link Transaction#terminate()} or a
133: * the listener receives a {@link SipListener#processTransactionTerminated(TransactionTerminatedEvent) } callback.
134: * Note that the stack calls
135: * {@link SipListener#processTransactionTerminated(TransactionTerminatedEvent)}asynchronously
136: * after it removes the transaction some time after the Transaction state is set to
137: * {@link TransactionState#TERMINATED } ;
138: * after which, it maintains no record of the Transaction.
139: *
140: * @throws SipException if a Dialog is already associated with the ServerTransaction
141: * when the method is called.
142: *
143: * @since 1.2
144: */
145: public void enableRetransmissionAlerts() throws SipException;
146:
147: }
|