001: /*
002: * Portions Copyright 2000-2007 Sun Microsystems, Inc. All Rights
003: * Reserved. Use is subject to license terms.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025: package gov.nist.siplite;
026:
027: import gov.nist.siplite.stack.Transaction;
028: import gov.nist.siplite.stack.ClientTransaction;
029: import gov.nist.siplite.stack.ServerTransaction;
030:
031: /**
032: * This interface represents the application view to a SIP stack
033: * therefore defines the application's communication channel to the SIP stack.
034: * This is patterened on the JAIN-SIP SIP-Listener ( but it is not identical
035: * to it).
036: *
037: * @see SipProvider
038: * @see RequestEvent
039: * @see ResponseEvent
040: * @see TimeoutEvent
041: *
042: * @version 1.1
043: */
044: public interface SipListener {
045:
046: /**
047: * Processes a Request received on a SipProvider upon which this SipListener
048: * is registered.
049: * <p>
050: * <b>Handling Requests:</b><br>
051: * When the application receives a RequestEvent from the SipProvider the
052: * RequestEvent may or may not belong to an existing dialog of the
053: * application.
054: * The application can be determine if the RequestEvent belongs to an
055: * existing dialog by checking the server transaction of the RequestEvent.
056: * <ul>
057: * <li>If the server transaction equals <code>null</code> the
058: * RequestEvent does
059: * not belong to an existing dialog and the application must determine how
060: * to handle the RequestEvent. If the application decides to forward the
061: * Request statelessly no transactional support is required and it
062: * can simply
063: * pass the Request of the RequestEvent as an argument to the
064: * {@link SipProvider#sendRequest(Request)} method. However if the
065: * application determines to respond to a Request statefully it must request
066: * a new server transaction from the
067: * {@link SipProvider#getNewServerTransaction(Request)} method and use this
068: * server transaction to send the Response based on the content of
069: * the Request.
070: * If the SipProvider throws TransactionAlreadyExistsException when the
071: * application requests a new server transaction to handle a Request the
072: * current RequestEvent is a retransmission of the initial request
073: * from which
074: * the application hadn't requested a server transaction to handle it, i.e.
075: * this exception handles the race condition of an application
076: * informing the
077: * SipProvider that it will handle a Request and the receipt of a
078: * retransmission of the Request from the network to the SipProvider.
079: * <li>If the server transaction <b>does NOT</b> equal
080: * <code>null</code> the
081: * application determines its action to the RequestEvent based on
082: * the content of the Request information.
083: * </ul>
084: * <p>
085: * <b>User Agent Server (UAS) Behaviour:</b><br>
086: * A UAS application decides whether to accept the an invitation from a
087: * UAC. The UAS application can accept the invitation by sending a 2xx
088: * response to the UAC, a 2xx response to an INVITE transaction establishes
089: * a session. For 2xx responses, the processing is done by the UAS
090: * application, to guarantee the three way handshake of an INVITE
091: * transaction. This specification defines a utility thats enables the
092: * SipProvider to handle the 2XX processing for an INVITE transaction, see
093: * the {@link SipStack#isRetransmissionFilterActive()} method. If the
094: * invitation is not accepted, a 3xx, 4xx, 5xx or 6xx response is sent by
095: * the application, depending on the reason for
096: * the rejection. Alternatively before sending a final response, the UAS
097: * can also send provisional responses (1xx) to advise the UAC of progress
098: * in contacting the called user. A UAS that receives a CANCEL request for
099: * an INVITE, but has not yet sent a final response, would "stop ringing"
100: * and then respond to the INVITE with a specific 487 Error response.
101: * <p>
102: * <b>General Proxy behaviour:</b><br>
103: * In some circumstances, a proxy application MAY forward requests using
104: * stateful transports without being transaction stateful,
105: * i.e. using the {@link SipProvider#sendRequest(Request)} method,
106: * but using TCP as a transport. For example, a proxy application MAY
107: * forward a request from one TCP connection to another transaction
108: * statelessly as long as it places enough information in the message to be
109: * able to forward the response down the same connection the request arrived
110: * on. This is the responsibility of the application and not the
111: * SipProvider.
112: * Requests forwarded between different types of transports where the
113: * proxy application takes an active role in ensuring reliable delivery on
114: * one of the transports must be forwarded using the stateful send methods
115: * on the SipProvider.
116: * <p>
117: * <b>Stateful Proxies:</b><br>
118: * A stateful proxy MUST create a new server transaction for each new
119: * request received, either automatically generated by the SipProvider,
120: * if the request matches an existing dialog or by the an
121: * application call on the SipProvider if it decides to respond to the
122: * request statefully. The proxy application determines where to
123: * route the request, choosing one or more next-hop locations. An outgoing
124: * request for each next-hop location is processed by its own associated
125: * client transaction. The proxy application collects the responses from
126: * the client transactions and uses them to send responses to the server
127: * transaction. When an application receives a CANCEL request that matches
128: * a server transaction, a stateful proxy cancels any pending client
129: * transactions associated with a response context. A stateful proxy
130: * responds to the CANCEL rather than simply forwarding a response it would
131: * receive from a downstream element.
132: * <p>
133: * For all new Requests, including any with unknown methods, an element
134: * intending to stateful proxy the Request determines the target(s) of the
135: * request. A stateful proxy MAY process the targets in any order.
136: * A stateful proxy must have a mechanism to maintain the target set as
137: * responses are received and associate the responses to each forwarded
138: * request with the original request. For each target, the proxy forwards
139: * the request following these steps:
140: * <ul>
141: * <li>Make a copy of the received request.
142: * <li>Update the Request-URI.
143: * <li>Update the Max-Forwards header.
144: * <li>Optionally add a Record-route header.
145: * <li>Optionally add additional headers.
146: * <li>Postprocess routing information.
147: * <li>Determine the next-hop address, port, and transport.
148: * <li>Add a Via header.
149: * <li>Add a Content-Length header if necessary.
150: * <li>Forward the new request using the
151: * {@link ClientTransaction#sendRequest()} method.
152: * <li>Process all responses recieved on the
153: * {@link SipListener#processResponse(ResponseEvent)} method.
154: * <li>NOT generate 100 (Trying) responses to non-INVITE requests.
155: * </ul>
156: * <p>
157: * A stateful proxy MAY transition to stateless operation at any time
158: * during the processing of a request, as long as it did nothing that
159: * would prevent it from being stateless initially i.e. forking or
160: * generation of a 100 response. When performing such a transition, any
161: * state already stored is simply discarded.
162: * <p>
163: * <b>Forking Requests:</b><br>
164: * A stateful proxy application MAY choose to "fork" a request, routing it
165: * to multiple destinations. Any request that is forwarded to more than
166: * one location MUST be forwarded using the stateful send methods on the
167: * SipProvider.
168: * <p>
169: * <b>Stateless Proxies:</b><br>
170: * As a stateless proxy does not have any notion of a transaction, or of
171: * the response context used to describe stateful proxy behavior,
172: * <code>requestEvent.getServerTransaction() == null;</code>
173: * always return <var>true</var>. The transaction layer of the SipProvider
174: * implementation is by-passed. For all requests including any with
175: * unknown methods, an application intending to stateless proxy the request
176: * MUST:
177: * <ul>
178: * <li>Validate the request.
179: * <li>Preprocess routing information.
180: * <li>Determine a single target(s) for the request.
181: * <li>Forward the request to the target using the
182: * {@link SipProvider#sendRequest(Request)} method.
183: * <li>NOT perform special processing for CANCEL requests.
184: * </ul>
185: *
186: * @since v1.1
187: * @param requestEvent - requestEvent fired from the SipProvider to
188: * the SipListener representing a Request received from the network.
189: */
190: public void processRequest(RequestEvent requestEvent);
191:
192: /**
193: * Processes a Response received on a SipProvider upon which this
194: * SipListener is registered.
195: * <p>
196: * <b>Handling Responses:</b><br>
197: * When the application receives a ResponseEvent from the SipProvider the
198: * ResponseEvent may or may not correlate to an existing Request of the
199: * application. The application can be determine if the
200: * ResponseEvent belongs
201: * to an existing Request by checking the client transaction of the
202: * ResponseEvent.
203: * <ul>
204: * <li>If the the client transaction equals <code>null</code> the
205: * ResponseEvent does not belong to an existing Request and the Response is
206: * considered stray, i.e. stray response can be identitied, if
207: * <code>responseEvent.getClientTransaction() == null;</code>. Handling of
208: * these "stray" responses is dependent on the application i.e. a
209: * proxy will forward them statelessly using the
210: * {@link SipProvider#sendResponse(Response)} method, while a User
211: * Agent will discard them.
212: * <li>If the client transaction <b>does NOT</b> equal
213: * <code>null</code> the
214: * application determines it action to the ResponseEvent based on the
215: * content of the Response information.
216: * </ul>
217: * <p>
218: * <b>User Agent Client (UAC) behaviour:</b><br>
219: * After possibly receiving one or more provisional responses (1xx) to a
220: * Request, the UAC will get one or more 2xx responses or one non-2xx final
221: * response. Because of the protracted amount of time it can take
222: * to receive
223: * final responses to an INVITE, the reliability mechanisms for INVITE
224: * transactions differ from those of other requests.
225: * A UAC needs to send an ACK for every final Response it receives, however
226: * the procedure for sending the ACK depends on the type of Response. For
227: * final responses between 300 and 699, the ACK processing is done by the
228: * transaction layer i.e. handled by the implementation. For 2xx
229: * responses, the
230: * ACK processing is done by the UAC application, to guarantee the
231: * three way
232: * handshake of an INVITE transaction. This specification defines a utility
233: * thats enables the SipProvider to handle the ACK processing for an INVITE
234: * transaction, see the {@link
235: * SipStack#isRetransmissionFilterActive()} method.
236: * <br>
237: * A 2xx response to an INVITE establishes a session, and it also
238: * creates a dialog between the UAC that issued the INVITE and the UAS
239: * that generated the 2xx response. Therefore, when multiple 2xx responses
240: * are received from different remote User Agents, i.e. the INVITE forked,
241: * each 2xx establishes a different dialog and all these dialogs
242: * are part of
243: * the same call. If an INVITE client transaction returns a {@link
244: * TimeoutEvent}
245: * rather than a response the UAC acts as if a 408 (Request Timeout)
246: * response had been received from the UAS.
247: * <p>
248: * <b>Stateful Proxies:</b><br>
249: * A proxy application that handles a response statefully must do the
250: * following processing:
251: * <ul>
252: * <li>Find the appropriate response context.
253: * <li>Remove the topmost Via header.
254: * <li>Add the response to the response context.
255: * <li>Check to determine if this response should be forwarded immediately.
256: * <li>When necessary, choose the best final response from the
257: * response context. If no final response has been forwarded after every
258: * client transaction associated with the response context has been
259: * terminated, the proxy must choose and forward the "best" response
260: * from those it has seen so far.
261: * </ul>
262: * <p>
263: * Additionally the following processing MUST be performed on each response
264: * that is forwarded.
265: * <ul>
266: * <li>Aggregate authorization header values if necessary.
267: * <li>Optionally rewrite Record-Route header values.
268: * <li>Forward the response using the
269: * {@link ServerTransaction#sendResponse(Response)} method.
270: * <li>Generate any necessary CANCEL requests.
271: * </ul>
272: * <p>
273: * <b>Stateless Proxies:</b><br>
274: * As a stateless proxy does not have any notion of transactions, or of
275: * the response context used to describe stateful proxy behavior,
276: * <code>responseEvent.getClientTransaction == null;</code>
277: * always return <var>true</var>. Response processing does not apply, the
278: * transaction layer of the SipProvider implementation is by-passed. An
279: * application intending to stateless proxy the Response MUST:
280: * <ul>
281: * <li>Inspect the sent-by value in the first Via header.
282: * <li>If that address matches the proxy, the proxy MUST remove that header
283: * from the response.
284: * <li>Forward the resulting response to the location indicated in the
285: * next Via header using the
286: * {@link SipProvider#sendResponse(Response)} method.
287: * </ul>
288: *
289: * @since v1.1
290: * @param responseEvent - the responseEvent fired from the SipProvider to
291: * the SipListener representing a Response received from the network.
292: */
293: public void processResponse(ResponseEvent responseEvent);
294:
295: /**
296: * Processes a retransmit or expiration Timeout of an underlying
297: * {@link Transaction} handled by this SipListener. This Event notifies the
298: * application that a retransmission or transaction Timer expired in the
299: * SipProvider's transaction state machine. The TimeoutEvent encapsulates
300: * the specific timeout type and the transaction identifier either client
301: * or server upon which the timeout occured. The type of Timeout can by
302: * determined by:
303: * <code>timeoutType = timeoutEvent.getTimeout().getValue();</code>
304: *
305: * @param timeoutEvent - the timeoutEvent received indicating either the
306: * message retransmit or transaction timed out.
307: */
308: public void processTimeout(TimeoutEvent timeoutEvent);
309:
310: }
|