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 : SipListener.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty
020: * 1.2 02/15/2005 M. Ranganathan Added method for IO Exception
021: * 1.2 02/15/2005 M. Ranganathan Added method for TransactionTerminated
022: * propagation.
023: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
024: */package javax.sip;
025:
026: import java.util.EventListener;
027:
028: /**
029: * This interface represents the application view to a SIP stack therefore
030: * defines the application's communication channel to the SIP stack. This
031: * interface defines the methods required by an applications to receive and
032: * process Events that are emitted by an object implementing the
033: * {@link javax.sip.SipProvider}interface.
034: * <p>
035: * The Events accepted by a SipListener may be one of four types:
036: * <ul>
037: * <li>{@link RequestEvent}- these are request messages emitted as events by
038: * the SipProvider. Request events represent request messages i.e. INVITE, that
039: * are received from the network to the application via the underlying stack
040: * implementation.
041: * <li>{@link ResponseEvent}- these are response messages emitted as events by
042: * the SipProvider. Response events represent Response messages i.e. 2xx's, that
043: * are received from the network to the application via the underlying stack
044: * implementation.
045: * <li>{@link TimeoutEvent}- these are timeout notifications emitted as events
046: * by the SipProvider. Timeout events represent timers expiring in the
047: * underlying SipProvider transaction state machine. These timeout's events
048: * notify the application that a retranmission is required or a transaction has
049: * timed out.
050: * <li>{@link IOExceptionEvent}- these are IO Exception notifications emitted as
051: * events by the SipProvider. IOException events represent failure in the
052: * underlying SipProvider IO Layer. These IO Exception events notify the
053: * application that a failure has occured while accessing a socket.
054: * <li>{@link TransactionTerminatedEvent}- these are Transaction Terminated
055: * notifications emitted as events by the SipProvider. TransactionTerminated
056: * events represent a transaction termination and notify the
057: * application of the termination.
058: * <li>{@link DialogTerminatedEvent}- these are Dialog Terminated
059: * notifications emitted as events by the SipProvider. DialogTerminated
060: * events represent a Dialog termination and notify the
061: * application of the termination.
062: * </ul>
063: * <p>
064: * An application will only receive Request, Response, Timeout,
065: * TransactionTerminated, DialogTerminated and IOException
066: * events once it has registered as an EventListener of a SipProvider. The
067: * application registers with the SipProvider by invoking the
068: * {@link SipProvider#addSipListener(SipListener)}passing itself as an
069: * argument.
070: * <p>
071: * <b>Architecture: </b> <br>
072: * This specification mandates a single SipListener per SipStack,
073: * and a unicast event model i.e. a SipProvider can only have one SipListener
074: * registered with it. This specification allows multiple SipProviders per
075: * SipStack and as such a SipListener can register with multiple SipProviders
076: * i.e there is a one-to-many relationship between a SipListener and a SipProvider.
077: * <p>
078: * Note: An application that implements the SipListener interface, may act as a
079: * proxy object and pass all events to higher level core application programming
080: * logic that is outside the scope of this specification. For example a SIP
081: * Servlet, or a JSLEE implementation can implement a back to back UA or
082: * Proxy core application respectively in there respective container
083: * environments utilizing this specification to talk the SIP protocol.
084: * <p>
085: * <b>Messaging Model: </b> <br>
086: * An application can send messages by passing {@link javax.sip.message.Request}
087: * and {@link javax.sip.message.Response}messages to that the following object:
088: * <ul>
089: * <li>Request and response messages can be sent statelessly via the
090: * SipProvider using the send methods on the {@link javax.sip.SipProvider}.
091: * <li>Request messages can be sent transaction stateful via the
092: * ClientTransaction using the {@link ClientTransaction#sendRequest()}method.
093: * <li>Response messages can be sent transaction stateful via the
094: * ServerTransaction using the {@link ServerTransaction#sendResponse(Response)}
095: * method.
096: * <li>Request messages can be sent dialog stateful via the Dialog using the
097: * {@link Dialog#sendRequest(ClientTransaction)}method.
098: * </ul>
099: * Although this specification provides the capabilities to send messages both
100: * statelessly and statefully it is mandated that an application will not send
101: * the same message both statefully and statelessly.
102: * The messages sent by the application are not Event's as the event model is
103: * uni-directional from the SipProvider to the SipListener, i.e. the SipListener
104: * listens for Events from the SipProvider, but the SipProvider does not listen
105: * for Events on the SipListener. The rationale is the application knows when to
106: * initiate requests and responses i.e setup a call or respond to a network
107: * event, however an application doesn't know when it will receive a network
108: * event, hence the application must listen for these network events.
109: * <p>
110: * <b>Session Negotiation </b> <br>
111: * There are special rules for message bodies of Request and Responses that
112: * contain a session description. SIP uses an offer/answer model where one User
113: * Agent sends a session description, called the offer, which contains a
114: * proposed description of the session. The other User Agent responds with
115: * another session description, called the answer, which indicates which
116: * communications means are accepted. In this specification, offers and answers
117: * can only appear in INVITE requests and Responses, and ACK. The Session
118: * Description Protocol (SDP) <a href =
119: * "http://www.ietf.org/rfc/rfc2327.txt">RFC2327 </a> MUST be supported by all
120: * user agents as a means to describe sessions, and its usage for constructing
121: * offers and answers MUST follow the procedures defined in <a href =
122: * "http://www.ietf.org/rfc/rfc3261.txt">RFC3261 </a>. The SDP protocol is
123: * described in Java by <a href = "http://www.jcp.org/en/jsr/detail?id=141">JSR
124: * 141 </a>
125: *
126: * @see SipProvider
127: * @see RequestEvent
128: * @see ResponseEvent
129: * @see TimeoutEvent
130: * @see IOExceptionEvent
131: * @see TransactionTerminatedEvent
132: * @see DialogTerminatedEvent
133: *
134: * @author BEA Systems, NIST
135: * @version 1.2
136: */
137: public interface SipListener extends EventListener {
138:
139: /**
140: * Processes a Request received on a SipProvider upon which this SipListener
141: * is registered.
142: * <p>
143: * <b>Handling Requests: </b> <br>
144: * When the application receives a RequestEvent from the SipProvider the
145: * RequestEvent may or may not belong to an existing dialog of the
146: * application. The application can be determine if the RequestEvent belongs
147: * to an existing dialog by checking the server transaction of the
148: * RequestEvent.
149: * <ul>
150: * <li>If the server transaction equals <code>null</code> the
151: * RequestEvent does not belong to an existing dialog and the application
152: * must determine how to handle the RequestEvent. If the application decides
153: * to forward the Request statelessly no transactional support is required
154: * and it can simply pass the Request of the RequestEvent as an argument to
155: * the {@link SipProvider#sendRequest(Request)}method. However if the
156: * application determines to respond to a Request statefully it must request
157: * a new server transaction from the
158: * {@link SipProvider#getNewServerTransaction(Request)}method and use this
159: * server transaction to send the Response based on the content of the
160: * Request. If the SipProvider throws TransactionAlreadyExistsException when
161: * the application requests a new server transaction to handle a Request the
162: * current RequestEvent is a retransmission of the initial request from
163: * which the application hadn't requested a server transaction to handle it,
164: * i.e. this exception handles the race condition of an application
165: * informing the SipProvider that it will handle a Request and the receipt
166: * of a retransmission of the Request from the network to the SipProvider.
167: * <li>If the server transaction <b>does NOT </b> equal <code>null</code>
168: * the application determines its action to the RequestEvent based on the
169: * content of the Request information.
170: * </ul>
171: * <p>
172: * <b>User Agent Server (UAS) Behaviour: </b> <br>
173: * A UAS application decides whether to accept the an invitation from a UAC.
174: * The UAS application can accept the invitation by sending a 2xx response
175: * to the UAC, a 2xx response to an INVITE transaction establishes a
176: * session. For 2xx responses, the processing is done by the UAS
177: * application, to guarantee the three way handshake of an INVITE
178: * transaction. This specification defines a utility thats enables the
179: * SipProvider to handle the 2xx processing for an INVITE transaction, see
180: * the {@link SipStack#isRetransmissionFilterActive()}method. If the
181: * invitation is not accepted, a 3xx, 4xx, 5xx or 6xx response is sent by
182: * the application, depending on the reason for the rejection. Alternatively
183: * before sending a final response, the UAS can also send provisional
184: * responses (1xx) to advise the UAC of progress in contacting the called
185: * user. A UAS that receives a CANCEL request for an INVITE, but has not yet
186: * sent a final response, would "stop ringing" and then respond to the
187: * INVITE with a specific 487 Error response.
188: * <p>
189: * <b>General Proxy behaviour: </b> <br>
190: * In some circumstances, a proxy application MAY forward requests using
191: * stateful transports without being transaction stateful, i.e. using the
192: * {@link SipProvider#sendRequest(Request)}method, but using TCP as a
193: * transport. For example, a proxy application MAY forward a request from
194: * one TCP connection to another transaction statelessly as long as it
195: * places enough information in the message to be able to forward the
196: * response down the same connection the request arrived on. This is the
197: * responsibility of the application and not the SipProvider. Requests
198: * forwarded between different types of transports where the proxy
199: * application takes an active role in ensuring reliable delivery on one of
200: * the transports must be forwarded using the stateful send methods on the
201: * SipProvider.
202: * <p>
203: * <b>Stateful Proxies: </b> <br>
204: * A stateful proxy MUST create a new server transaction for each new
205: * request received, either automatically generated by the SipProvider, if
206: * the request matches an existing dialog or by the an application call on
207: * the SipProvider if it decides to respond to the request statefully. The
208: * proxy application determines where to route the request, choosing one or
209: * more next-hop locations. An outgoing request for each next-hop location
210: * is processed by its own associated client transaction. The proxy
211: * application collects the responses from the client transactions and uses
212: * them to send responses to the server transaction. When an application
213: * receives a CANCEL request that matches a server transaction, a stateful
214: * proxy cancels any pending client transactions associated with a response
215: * context. A stateful proxy responds to the CANCEL rather than simply
216: * forwarding a response it would receive from a downstream element.
217: * <p>
218: * For all new Requests, including any with unknown methods, an element
219: * intending to stateful proxy the Request determines the target(s) of the
220: * request. A stateful proxy MAY process the targets in any order. A
221: * stateful proxy must have a mechanism to maintain the target set as
222: * responses are received and associate the responses to each forwarded
223: * request with the original request. For each target, the proxy forwards
224: * the request following these steps:
225: * <ul>
226: * <li>Make a copy of the received request.
227: * <li>Update the Request-URI.
228: * <li>Update the Max-Forwards header.
229: * <li>Optionally add a Record-route header.
230: * <li>Optionally add additional headers.
231: * <li>Postprocess routing information.
232: * <li>Determine the next-hop address, port, and transport.
233: * <li>Add a Via header.
234: * <li>Add a Content-Length header if necessary.
235: * <li>Forward the new request using the
236: * {@link ClientTransaction#sendRequest()}method.
237: * <li>Process all responses recieved on the
238: * {@link SipListener#processResponse(ResponseEvent)}method.
239: * <li>NOT generate 100 (Trying) responses to non-INVITE requests.
240: * </ul>
241: * <p>
242: * A stateful proxy MAY transition to stateless operation at any time during
243: * the processing of a request, as long as it did nothing that would prevent
244: * it from being stateless initially i.e. forking or generation of a 100
245: * response. When performing such a transition, any state already stored is
246: * simply discarded.
247: * <p>
248: * <b>Forking Requests: </b> <br>
249: * A stateful proxy application MAY choose to "fork" a request, routing it
250: * to multiple destinations. Any request that is forwarded to more than one
251: * location MUST be forwarded using the stateful send methods on the
252: * SipProvider.
253: * <p>
254: * <b>Stateless Proxies: </b> <br>
255: * As a stateless proxy does not have any notion of a transaction, or of the
256: * response context used to describe stateful proxy behavior,
257: * <code>requestEvent.getServerTransaction() == null;</code> always return
258: * <var>true </var>. The transaction layer of the SipProvider implementation
259: * is by-passed. For all requests including any with unknown methods, an
260: * application intending to stateless proxy the request MUST:
261: * <ul>
262: * <li>Validate the request.
263: * <li>Preprocess routing information.
264: * <li>Determine a single target(s) for the request.
265: * <li>Forward the request to the target using the
266: * {@link SipProvider#sendRequest(Request)}method.
267: * <li>NOT perform special processing for CANCEL requests.
268: * </ul>
269: *
270: * @param requestEvent -
271: * requestEvent fired from the SipProvider to the SipListener
272: * representing a Request received from the network.
273: */
274: public void processRequest(RequestEvent requestEvent);
275:
276: /**
277: * Processes a Response received on a SipProvider upon which this
278: * SipListener is registered.
279: * <p>
280: * <b>Handling Responses: </b> <br>
281: * When the application receives a ResponseEvent from the SipProvider the
282: * ResponseEvent may or may not correlate to an existing Request of the
283: * application. The application can be determine if the ResponseEvent
284: * belongs to an existing Request by checking the client transaction of the
285: * ResponseEvent.
286: * <ul>
287: * <li>If the the client transaction equals <code>null</code> the
288: * ResponseEvent does not belong to an existing Request and the Response is
289: * considered stray, i.e. stray response can be identitied, if
290: * <code>responseEvent.getClientTransaction() == null;</code>. Handling
291: * of these "stray" responses is dependent on the application i.e. a proxy
292: * will forward them statelessly using the
293: * {@link SipProvider#sendResponse(Response)}method, while a User Agent
294: * will discard them.
295: * <li>If the client transaction <b>does NOT </b> equal <code>null</code>
296: * the application determines it action to the ResponseEvent based on the
297: * content of the Response information.
298: * </ul>
299: * <p>
300: * <b>User Agent Client (UAC) behaviour: </b> <br>
301: * After possibly receiving one or more provisional responses (1xx) to a
302: * Request, the UAC will get one or more 2xx responses or one non-2xx final
303: * response. Because of the protracted amount of time it can take to receive
304: * final responses to an INVITE, the reliability mechanisms for INVITE
305: * transactions differ from those of other requests. A UAC needs to send an
306: * ACK for every final Response it receives, however the procedure for
307: * sending the ACK depends on the type of Response. For final responses
308: * between 300 and 699, the ACK processing is done by the transaction layer
309: * i.e. handled by the implementation. For 2xx responses, the ACK processing
310: * is done by the UAC application, to guarantee the three way handshake of
311: * an INVITE transaction. This specification defines a utility thats enables
312: * the SipProvider to handle the ACK processing for an INVITE transaction,
313: * see the {@link SipStack#isRetransmissionFilterActive()}method. <br>
314: * A 2xx response to an INVITE establishes a session, and it also creates a
315: * dialog between the UAC that issued the INVITE and the UAS that generated
316: * the 2xx response. Therefore, when multiple 2xx responses are received
317: * from different remote User Agents, i.e. the INVITE forked, each 2xx
318: * establishes a different dialog and all these dialogs are part of the same
319: * call. If an INVITE client transaction returns a {@link TimeoutEvent}
320: * rather than a response the UAC acts as if a 408 (Request Timeout)
321: * response had been received from the UAS.
322: * <p>
323: * <b>Stateful Proxies: </b> <br>
324: * A proxy application that handles a response statefully must do the
325: * following processing:
326: * <ul>
327: * <li>Find the appropriate response context.
328: * <li>Remove the topmost Via header.
329: * <li>Add the response to the response context.
330: * <li>Check to determine if this response should be forwarded immediately.
331: * <li>When necessary, choose the best final response from the response
332: * context. If no final response has been forwarded after every client
333: * transaction associated with the response context has been terminated, the
334: * proxy must choose and forward the "best" response from those it has seen
335: * so far.
336: * </ul>
337: * <p>
338: * Additionally the following processing MUST be performed on each response
339: * that is forwarded.
340: * <ul>
341: * <li>Aggregate authorization header values if necessary.
342: * <li>Optionally rewrite Record-Route header values.
343: * <li>Forward the response using the
344: * {@link ServerTransaction#sendResponse(Response)}method.
345: * <li>Generate any necessary CANCEL requests.
346: * </ul>
347: * <p>
348: * <b>Stateless Proxies: </b> <br>
349: * As a stateless proxy does not have any notion of transactions, or of the
350: * response context used to describe stateful proxy behavior,
351: * <code>responseEvent.getClientTransaction == null;</code> always return
352: * <var>true </var>. Response processing does not apply, the transaction
353: * layer of the SipProvider implementation is by-passed. An application
354: * intending to stateless proxy the Response MUST:
355: * <ul>
356: * <li>Inspect the sent-by value in the first Via header.
357: * <li>If that address matches the proxy, the proxy MUST remove that header
358: * from the response.
359: * <li>Forward the resulting response to the location indicated in the next
360: * Via header using the {@link SipProvider#sendResponse(Response)}method.
361: * </ul>
362: *
363: * @param responseEvent -
364: * the responseEvent fired from the SipProvider to the
365: * SipListener representing a Response received from the network.
366: */
367: public void processResponse(ResponseEvent responseEvent);
368:
369: /**
370: * Processes a retransmit or expiration Timeout of an underlying
371: * {@link Transaction}handled by this SipListener. This Event notifies the
372: * application that a retransmission or transaction Timer expired in the
373: * SipProvider's transaction state machine. The TimeoutEvent encapsulates
374: * the specific timeout type and the transaction identifier either client or
375: * server upon which the timeout occured. The type of Timeout can by
376: * determined by:
377: * <code>timeoutType = timeoutEvent.getTimeout().getValue();</code>
378: *
379: * @param timeoutEvent -
380: * the timeoutEvent received indicating either the message
381: * retransmit or transaction timed out.
382: */
383: public void processTimeout(TimeoutEvent timeoutEvent);
384:
385: /**
386: * Process an asynchronously reported IO Exception. Asynchronous IO
387: * Exceptions may occur as a result of errors during retransmission of
388: * requests. The transaction state machine requires to report IO Exceptions
389: * to the application immediately (according to RFC 3261). This method
390: * enables an implementation to propagate the asynchronous handling of IO
391: * Exceptions to the application.
392: *
393: * @since v1.2
394: * @param exceptionEvent --
395: * The Exception event that is reported to the application.
396: */
397: public void processIOException(IOExceptionEvent exceptionEvent);
398:
399: /**
400: * Process an asynchronously reported TransactionTerminatedEvent.
401: * When a transaction transitions to the Terminated state, the stack
402: * keeps no further records of the transaction. This notification can be used by
403: * applications to clean up any auxiliary data that is being maintained
404: * for the given transaction.
405: *
406: * @param transactionTerminatedEvent -- an event that indicates that the
407: * transaction has transitioned into the terminated state.
408: * @since v1.2
409: */
410: public void processTransactionTerminated(
411: TransactionTerminatedEvent transactionTerminatedEvent);
412:
413: /**
414: * Process an asynchronously reported DialogTerminatedEvent.
415: * When a dialog transitions to the Terminated state, the stack
416: * keeps no further records of the dialog. This notification can be used by
417: * applications to clean up any auxiliary data that is being maintained
418: * for the given dialog.
419: *
420: * @param dialogTerminatedEvent -- an event that indicates that the
421: * dialog has transitioned into the terminated state.
422: * @since v1.2
423: */
424: public void processDialogTerminated(
425: DialogTerminatedEvent dialogTerminatedEvent);
426:
427: }
|