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 : ResponseEvent.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 Added getDialog method
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip;
023:
024: import java.util.*;
025: import javax.sip.message.Response;
026:
027: /**
028: * This class represents a Response event that is passed from a SipProvider to
029: * its SipListener. This specification handles the passing of Response messages
030: * to the application with the event model. An application (SipListener)
031: * registers with the SIP protocol stack (SipProvider) and listens for Response
032: * events from the SipProvider.
033: * <p>
034: * This specification defines a single Response event object to handle all
035: * Response messages. The Response event encapsulates the Response message
036: * that can be retrieved from {@link javax.sip.ResponseEvent#getResponse()}.
037: * Therefore the event type of a Response event can be determined as follows:
038: * <p>
039: * <i>eventType == ResponseEvent.getResponse().getStatusCode();</i>
040: * <p>
041: * A Response event also encapsulates the client transaction upon which the
042: * Response is correlated, i.e. the client transaction of the Request
043: * message upon which this is a Response.
044: * <p>
045: * ResponseEvent contains the following elements:
046: * <ul>
047: * <li>source - the source of the event i.e. the SipProvider sending the
048: * ResponseEvent.
049: * <li>clientTransaction - the client transaction this ResponseEvent is
050: * associated with.
051: * <li>Response - the Response message received on the SipProvider
052: * that needs passed to the application encapsulated in a ResponseEvent.
053: * </ul>
054: *
055: * @author BEA Systems, NIST
056: * @version 1.2
057: */
058: public class ResponseEvent extends EventObject {
059:
060: /**
061: * Constructs a ResponseEvent encapsulating the Response that has been received
062: * by the underlying SipProvider. This ResponseEvent once created is passed to
063: * {@link SipListener#processResponse(ResponseEvent)} method of the SipListener
064: * for application processing.
065: *
066: * @param source - the source of ResponseEvent i.e. the SipProvider
067: * @param clientTransaction - client transaction upon which
068: * this Response was sent
069: * @param response - the Response message received by the SipProvider
070: */
071: public ResponseEvent(Object source,
072: ClientTransaction clientTransaction, Dialog dialog,
073: Response response) {
074: super (source);
075: m_response = response;
076: m_transaction = clientTransaction;
077: m_dialog = dialog;
078: }
079:
080: /**
081: * Gets the client transaction associated with this ResponseEvent
082: *
083: * @return client transaction associated with this ResponseEvent
084: */
085: public ClientTransaction getClientTransaction() {
086: return m_transaction;
087: }
088:
089: /**
090: * Gets the Response message encapsulated in this ResponseEvent.
091: *
092: * @return the response associated with this ResponseEvent.
093: */
094: public Response getResponse() {
095: return m_response;
096: }
097:
098: /**
099: * Gets the Dialog associated with the event or null if no dialog exists.
100: * This method separates transaction support from dialog support. This
101: * enables application developers to access the dialog associated to this
102: * event without having to query the transaction associated to the event.
103: * For example the transaction associated with the event may return 'null'
104: * because the final response for the transaction has already been received
105: * and the stack has no more record of the transaction. This situation can
106: * occur when a UAC sends requests out through a forking proxy. Responses
107: * that all refer to the same transaction may be sent by the targets of the
108: * fork but each response may be stamped with a different To tag, thus
109: * referring to different Dialogs on the UAC. The first final response
110: * terminates the transaction but the UAC may want to create a Dialog on
111: * a subsequent response.
112: *
113: * @return the dialog associated with the response event or null if there is no dialog.
114: * @since v1.2
115: */
116: public Dialog getDialog() {
117: return m_dialog;
118: }
119:
120: // internal variables
121: private Response m_response;
122: private ClientTransaction m_transaction;
123: private Dialog m_dialog;
124: }
|