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 : ClientTransaction.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 16/06/2005 Phelim O'Doherty Deprecated createAck method.
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip;
023:
024: import javax.sip.message.Request;
025:
026: /**
027: * A client transaction is used by a User Agent Client application to send
028: * Request messages to a User Agent Server application.
029: * The client transaction is also used to match Responses from the User Agent
030: * Server to fire Response events to the SipListener for a specific client
031: * transaction. This interfaces enables an application to send a
032: * {@link javax.sip.message.Request}'s statefully. A new client transaction
033: * is generated by the application calling the
034: * {@link SipProvider#getNewClientTransaction(Request)} method.
035: * <p>
036: * A client transaction of the transaction layer is represented by a finite
037: * state machine that is constructed to process a particular request under
038: * the covers of a stateful SipProvider. The transaction layer handles
039: * application-layer retransmissions, matching of responses to requests, and
040: * application-layer timeouts. Any task that a User Agent Client
041: * accomplishes takes place using a series of transactions.
042: * <p>
043: * The client transaction must be unique within the underlying
044: * implementation. A common way to create this value is to compute a
045: * cryptographic hash of the To tag, From tag, Call-ID header field, the
046: * Request-URI of the request received (before translation), the topmost Via
047: * header, and the sequence number from the CSeq header field, in addition to
048: * any Proxy-Require and Proxy-Authorization header fields that may be present.
049: * The algorithm used to compute the hash is implementation-dependent.
050: * <p>
051: * For the detailed client transaction state machines refer to Chapter
052: * 17 of <a href="http://www.ietf.org/rfc/rfc3261.txt">RFC 3261</a>, the
053: * allowable transitions are summarized below:
054: * <p>
055: * <b>Invite Transaction:</b><br>
056: * Calling --> Proceeding --> Completed --> Terminated
057: * <p>
058: * <b>Non-Invite Transaction:</b><br>
059: * Trying --> Proceeding --> Completed --> Terminated
060: *
061: * @author BEA Systems, NIST
062: * @version 1.2
063: */
064: public interface ClientTransaction extends Transaction {
065:
066: /**
067: * Sends the Request which created this ClientTransaction. When an
068: * application wishes to send a Request message, it creates a Request from
069: * the {@link javax.sip.message.MessageFactory} and then creates a new
070: * ClientTransaction from
071: * {@link SipProvider#getNewClientTransaction(Request)}. Calling this method
072: * on the ClientTransaction sends the Request onto the network. The Request
073: * message gets sent via the ListeningPoint information of the SipProvider
074: * that is associated to this ClientTransaction.
075: * <p>
076: * This method assumes that the Request is sent out of Dialog. It uses
077: * the Router to determine the next hop. If the Router returns a empty
078: * iterator, and a Dialog is associated with the outgoing request of the
079: * Transaction then the Dialog route set is used to send the outgoing
080: * request.
081: * <p>
082: * This method implies that the application is functioning as either a UAC
083: * or a stateful proxy, hence the underlying implementation acts statefully.
084: *
085: * @throws SipException if the SipProvider cannot send the Request for any
086: * reason.
087: * @see Request
088: */
089: public void sendRequest() throws SipException;
090:
091: /**
092: * Creates a new Cancel message from the Request associated with this client
093: * transaction. The CANCEL request, is used to cancel the previous request
094: * sent by this client transaction. Specifically, it asks the UAS to cease
095: * processing the request and to generate an error response to that request.
096: * A CANCEL request constitutes its own transaction, but also references
097: * the transaction to be cancelled. CANCEL has no effect on a request to
098: * which a UAS has already given a final response.
099: * <p>
100: * Note that both the transaction corresponding to the original request and
101: * the CANCEL transaction will complete independently. However, a UAC
102: * canceling a request cannot rely on receiving a 487 (Request Terminated)
103: * response for the original request, as an RFC 2543 compliant UAS will
104: * not generate such a response. Therefore if there is no final response for
105: * the original request the application will receieve a TimeoutEvent with
106: * {@link javax.sip.Timeout#TRANSACTION} and the client should then consider the
107: * original transaction cancelled.
108: * <ul>
109: * <li> UAC - A UAC should not send a CANCEL request to any request explicitly
110: * supported by this specification other than INVITE request. The reason
111: * being requests other than INVITE are responded to immediately and sending
112: * a CANCEL for a non-INVITE request would always create a race condition.
113: * CANCELs are useful as a UAC can not send a BYE request on a dialog
114: * until receipt of 2xx final response to the INVITE request. The CANCEL
115: * attempts to force a non-2xx response to the INVITE, therefore if a UAC
116: * wishes to give up on its call attempt entirely it can send a CANCEL.
117: * <li>Stateful proxies - A stateful proxy may generate CANCEL requests
118: * for:
119: * <ul>
120: * <li>INVITE Requests - A CANCEL can be sent on pending INVITE client
121: * transactions based on the period specified in the INVITE's Expires
122: * header field elapsing. However, this is generally unnecessary since
123: * the endpoints involved will take care of signaling the end of the
124: * transaction.
125: * <li> Other Requests - An implementation of this specification does
126: * not need to support CANCELing non-INVITE transactions.
127: * </ul>
128: * </ul>
129: *
130: * @return the new cancel Request specific to the Request of this client
131: * transaction.
132: * @throws SipException if this method is called to cancel a request that
133: * can't be cancelled i.e. ACK.
134: */
135: public Request createCancel() throws SipException;
136:
137: /**
138: * Creates a new Ack message from the Request associated with this client
139: * transaction. This ACK can be used to acknowledge the 2xx response to the
140: * request sent by this transaction.
141: *
142: * @return the new ACK Request specific to the Request of this client
143: * transaction.
144: * @throws SipException if this method is called before a final response
145: * is received for the transaction.
146: * @deprecated Since v1.2. As a transaction that received
147: * a 2xx response terminates immediately, it cannot be used for creating
148: * the corresponding ACK. If this transaction created a dialog, the
149: * {@link Dialog#createAck(long)} method
150: * should be used. Otherwise the stack will automatically create and
151: * send the ACK for non-2xx responses that need to be acknowledged.
152: * That is the application should never need to use this method.
153: */
154: public Request createAck() throws SipException;
155:
156: }
|