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 : SipProvider.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty Reworked
020: * 1.2 05/03/2005 M. Ranganathan getNewDialog method added.
021: * 1.2 07/07/2005 Phelim O'Doherty Added add/removeListeningPoint methods
022: * Added getListeningPoints method
023: * Removed restriction that a SipProvider
024: * can only have a single ListeningPoint
025: * 1.2 09/07/2005 M. Ranganathan Added getListeningPoint( String transport)
026: *
027: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
028: */package javax.sip;
029:
030: import java.util.*;
031: import javax.sip.message.*;
032: import javax.sip.header.*;
033:
034: /**
035: * This interface represents the messaging entity of a SIP stack and as
036: * such is the interface that defines the messaging and transactional
037: * component view of the SIP stack. It must be implemented by any object
038: * representing a SIP stack compliant to this specification that interacts
039: * directly with a proprietary implementation of a SIP stack.
040: * This interface defines the methods that enable any registered
041: * application implementing the {@link javax.sip.SipListener} interface to:
042: * <ul>
043: * <li> Register a {@link javax.sip.SipListener} to the SipProvider. Once
044: * the SipListener is registered with the SipProvider it will get notified
045: * of Events representing either Request, Response, Timeout messages, Network
046: * errors and Transaction termination.
047: * <li> De-register a {@link javax.sip.SipListener} from the SipProvider.
048: * Once a SipListener is de-registered, it will no longer receive any Events
049: * from that SipProvider.
050: * <li> Send {@link javax.sip.message.Request}'s statelessly.
051: * <li> Send {@link javax.sip.message.Response}'s statelessly.
052: * <li> Client and Server Transaction creation methods.
053: * <li> Listening Point manipulation methods.
054: * <li> New CallIdHeader accessor method.
055: * <li> SipStack object accessor method.
056: * </ul>
057: * <p>
058: * <b>Architecture:</b><br>
059: * This specification defines a many-to-one relationship between a SipProvider
060: * and a SipStack, a one-to-many relationship between a SipProvider and a
061: * ListeningPoint and a many-to-one relationship between a SipProvider
062: * and a SipListener.
063: * <p>
064: * Each SipProvider can be related to zero or more ListeningPoints. However,
065: * the SipProvider can have only one ListeningPoint for each transport type.
066: * For example, a single SipProvider can have one TCP ListeningPoint and one UDP
067: * ListeningPoint but cannot have two UDP ListeningPoints. Applications that wish
068: * to have multiple ListeningPoints with the same transport must use a separate
069: * SipProvider for each such ListeningPoint.
070: * <p>
071: * The ListeningPoints of the SipProvider specify the local address from where request
072: * messages will be sent.
073: * When the application sends a request directly from a SipProvider or from an object
074: * that the SipProvider created (Dialog or Transaction) the application might not know
075: * in advance the transport that this request will use. The transport is often
076: * resolved using a DNS server. In the process of sending the request, the remote
077: * transport will be resolved. The provider will then be able to send the request
078: * from a suitable ListeningPoint according to the resolved transport. If the resolved
079: * transport is UDP, the Provider's UDP ListeningPoint will be used. If the resolved address is
080: * TCP, the Providers's TCP ListeningPoint will be used.
081: * <p>
082: * If the application creates a SipProvider with a single ListeningPoint, let's say
083: * UDP, it means that UDP requests will be sent from the specific UDP ListeningPoint,
084: * and that the application does not care from where TCP requests will be sent.
085: * This is left for the SipStack decision.
086: * <p>
087: * Since the transport might not be known in advance, the application might find it
088: * difficult to specify the transport in the Via header. The
089: * SipProvider is responsible for fixing the Via header transport if needed. If the
090: * application set a sent-by identifier to the ListeningPoint that is different then
091: * the sent-by parameter in the message, the sent-by parameter of the message will be
092: * updated.
093: * <p>
094: * If the application created a provider with zero ListeningPoint, it must have only
095: * a single SipProvider per SipStack.
096: * <p>
097: *
098: * A SipProvider has the capability to behave transaction statefully, dialog
099: * statefully and statelessly. The transaction stateful methods are defined
100: * on the ClientTransaction and ServerTransaction respectfully. The transaction
101: * stateful method defined specifically for UAC and stateful proxy
102: * applications is:
103: * <ul>
104: * <li> {@link ClientTransaction#sendRequest()}
105: * </ul>
106: * <p>
107: * The stateful (transactional) convenience method defined specifically for
108: * UAS and stateful proxy applications is:
109: * <ul>
110: * <li> {@link ServerTransaction#sendResponse(Response)}
111: * </ul>
112: * <p>
113: * The dialog stateful methods defined specifically for UAC and stateful
114: * proxy applications are:
115: * <ul>
116: * <li> {@link Dialog#sendRequest(ClientTransaction)}
117: * <li> {@link Dialog#sendAck(Request)}
118: * </ul>
119: * <p>
120: * The stateless methods (non-transactional) defined on the SipProvider
121: * are:
122: * <ul>
123: * <li> {@link SipProvider#sendResponse(Response)}
124: * <li> {@link SipProvider#sendRequest(Request)}
125: * </ul>
126: * <p>
127: * <b>Transaction Model:</b><br>
128: * This specification supports stateful and stateless applications on a per
129: * message basis, hence transactional semantics are not mandated for all
130: * messages. This specification defines two types of transactions, server
131: * transactions and client transactions. A stateless proxy does not contain a
132: * client or server transaction, stateless proxies are effectively transparent
133: * with respect to transactions.
134: * <p>
135: * Client Transaction:<br>
136: * A client transaction exists between a UAC and a UAS specific to Request
137: * messages and a server transaction exists between a UAS and a UAC specific
138: * to Response messages. A transaction either server or client identifies
139: * messages sent between two SIP entities. The purpose of a client transaction
140: * is to identify a Request sent by an application that will reliably deliver
141: * the Request to a server transaction on
142: * the responding SIP entity. The purpose of a server transaction is to
143: * identify a Response sent by an application that will reliably deliver the
144: * Response to the request initiator.
145: * <p>
146: * Server Transaction:<br>
147: * A new server transaction is required for each response that an application
148: * decides to respond to statefully, as follows:
149: * <ul>
150: * <li>Dialog-Creating Requests: A server transaction is not automatically
151: * generated by a SipProvider implementation upon receipt of every
152: * Dialog-Creating Request i.e. INVITE. Instead the
153: * server transaction is set to <code>null</code> in the RequestEvent and
154: * the RequestEvent also containing the Request is passed to the application.
155: * It is then the responsibility of the application to decide to handle the
156: * Dialog-Creating Request statefully or statelessly, using the appropriate
157: * send methods on the SipProvider and the ServerTransaction. If a
158: * retransmission of the initial Request request is recieved by the SipProvider
159: * the following procedures should be adhered to:
160: * <ul>
161: * <li>Determine if an exisiting transaction is already handling this Request.
162: * <li>If a transaction exists do not pass the Request to the application via a
163: * RequestEvent.
164: * <li>If a transaction doesn't exist pass the retransmitted request to the
165: * application as a RequestEvent.
166: * </ul>
167: * <li>Non-Dialog-Creating Requests - When the SipProvider receives a
168: * Non-Dialog-Creating Request upon which this application has already
169: * responded to the Dialog-Creating Request of the same dialogue the server
170: * transaction is automatically placed to the RequestEvent and passed up to
171: * the application upon which it can respond. Note that the server transaction
172: * may be null in a stateful implementation if the incoming request does not
173: * match any dialog but must be part of one. That is for requests that must
174: * have state but for which the stack cannot find that state, the application
175: * can still handle these requests statelessly. The application cannot create
176: * a new server transaction for such requests.
177: * </ul>
178: * <p>
179: * <b>Sending Requests:</b><br>
180: * The client side of the transport layer is responsible for sending the
181: * request. The application passes the the Request to the ClientTransaction
182: * Dialog or the SipProvider that will send the Request over one of the SipProvider's
183: * ListeningPoints. The SipProvider will choose a ListeningPoint
184: * that has the same transport as the destination. For example, a Request that is going
185: * to be sent over TCP will use a TCP ListeningPoint. See section 18.1.1 of
186: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
187: * <p>
188: * <b>Sending Responses:</b><br>
189: * The server side of the transport layer is responsible for sending the
190: * responses. The application passes the Response to the ServerTransaction
191: * or the SipProvider that will send the Response over one of its ListeningPoints.
192: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>. The response
193: * must be sent from the same ListeningPoint on which the request was received.
194: * <p>
195: * <b>Receiving Requests:</b><br>
196: * A SipProvider should be prepared to receive requests on any IP address,
197: * port and transport encapsulated in one of its ListeningPoints.
198: * When the SipProvider receives a request over any transport, it
199: * must examine the value of the "sent-by" parameter in the top Via
200: * header. If the host portion of the "sent-by" parameter contains a
201: * domain name, or if it contains an IP address that differs
202: * from the packet source address, the server must add a "received"
203: * parameter to that Via header field value. This parameter must
204: * contain the source address from which the packet was received. This
205: * is to assist the SipProvider in sending the response, since it must
206: * be sent to the source IP address from which the request came.
207: * Next, the SipProvider attempts to match the request to a server
208: * transaction. If there are any server transactions in existence, the server
209: * transport uses the matching procedures of Chapter 17 of
210: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a> to attempt to
211: * match the response to an existing transaction. If a matching server
212: * transaction is found, the request is passed to that transaction, encapsulated
213: * into a RequestEvent and fired to the application for processing. If no match
214: * is found, the request is passed to the application, which may decide to
215: * construct a new server transaction for that request.
216: * <p>
217: * <b>Receiving Responses</b><br>
218: * Responses are first processed by the transport layer and then passed
219: * up to the transaction layer. The transaction layer performs its
220: * processing and then passes the response up to the application.
221: * When a response is received, the SipProvider examines the top
222: * Via header. If the value of the "sent-by" parameter in that header field
223: * value does not correspond to a value that the client transport is configured
224: * to insert into requests, the response MUST be silently discarded. If there
225: * are any client transactions in existence, the client transport uses the
226: * matching procedures of Chapter 17 of
227: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a> to attempt to
228: * match the response to an existing transaction. If there is a
229: * match, the response must be passed to that transaction, encapsulated into a
230: * ResponseEvent and fired to the application. Otherwise, the response is stray
231: * and must be passed to the application to determine its outcome i.e. a proxy
232: * will forward them, while a User Agent will discard.
233: *
234: * @see SipListener
235: * @see SipStack
236: *
237: * @author BEA Systems, NIST
238: * @version 1.2
239: */
240: public interface SipProvider {
241:
242: /**
243: * This method registers the SipListener object to this SipProvider, once
244: * registered the SIP Listener recieve events emitted from the SipProvider.
245: * This specification restricts a unicast Listener model, that is only one
246: * Listener may be registered on the SipProvider. If an
247: * attempt is made to re-register the existing registered SipListener this
248: * method returns silently.
249: *
250: * @param sipListener the SipListener to be registered with the SipProvider.
251: * @throws TooManyListenersException when a new SipListener attempts to
252: * register with the SipProvider when another SipListener is already
253: * registered with this SipProvider.
254: */
255: public void addSipListener(SipListener sipListener)
256: throws TooManyListenersException;
257:
258: /**
259: * Removes the specified SipListener from this SipProvider. This method
260: * returns silently if the SipListener is not registered with the SipProvider.
261: *
262: * @param sipListener the SipListener to be removed from this SipProvider.
263: */
264: public void removeSipListener(SipListener sipListener);
265:
266: /**
267: * Returns the SipStack that created this SipProvider. A SipProvider
268: * can only be attached to a single SipStack object that belongs to the same
269: * implementation as this SipProvider.
270: *
271: * @see SipStack
272: * @return the SipStack that created this SipProvider.
273: */
274: public SipStack getSipStack();
275:
276: /**
277: * Returns the ListeningPoint of this SipProvider. A SipProvider has a
278: * single Listening Point at any specific point in time.
279: *
280: * @deprecated Since v1.2. Note that in v1.1 a SipProvider could only be
281: * associated to a single listening point, this restriction has been lifted to allow
282: * a SipProvider to have a specific ListeningPoints for each transport.
283: * For backwards compatibility, this method will return the first
284: * ListeningPoint of the list of ListeningPoints associated with the
285: * SipProvider. This method has been replaced with
286: * {@link SipProvider#getListeningPoints()}.
287: *
288: */
289: public ListeningPoint getListeningPoint();
290:
291: /**
292: * Returns all the ListeningPoints of this SipProvider. A SipProvider may have
293: * a Listening Point for each specific transport type at any specific point
294: * in time. A SipProvider must use the same transport for
295: * sending responses that was used for sending the outbound request.
296: *
297: * @return an array of ListeningPoints associated to this SipProvider.
298: * @since 1.2
299: */
300: public ListeningPoint[] getListeningPoints();
301:
302: /**
303: * This method sets the ListeningPoint of the SipProvider.
304: *
305: * @deprecated Since v1.2. Note that in v1.1 a SipProvider could only
306: * be associated to a single listening point, this restriction has been lifted
307: * to allow a SipProvider to have a specific ListeningPoints for each transport.
308: * For backwards compatibility, this method will add the ListeningPoint to
309: * the list of ListeningPoints associated with the SipProvider. This method
310: * has been replaced with {@link SipProvider#addListeningPoint(ListeningPoint)},
311: * the same semantics apply to this method.
312: */
313: public void setListeningPoint(ListeningPoint listeningPoint)
314: throws ObjectInUseException;
315:
316: /**
317: * This method adds the supplied ListeningPoint to the list of
318: * ListeningPoints associated to this SipProvider. A SipProvider can only
319: * have a single ListeningPoint for each transport type at any specific time.
320: * Multiple SipProviders are prohibited to listen on the same ListeningPoints.
321: * This method returns silently if the same ListeningPoint argument is re-set on
322: * the SipProvider. If there is a ListeningPoint with the same transport but
323: * different IP or port, the implementation is expected to throw
324: * an exception.
325: *
326: * @param listeningPoint - the listening point to add to this ListeningPoint
327: * @throws ObjectInUseException if the supplied ListeningPoint is being used
328: * by another SipProvider or if there is already a ListeningPoint for the given transport.
329: * @throws TransportAlreadySupportedException if there is already a
330: * ListeningPoint associated to this SipProvider with the same transport of
331: * the ListeningPoint.
332: *
333: * @since 1.2
334: */
335: public void addListeningPoint(ListeningPoint listeningPoint)
336: throws ObjectInUseException,
337: TransportAlreadySupportedException;
338:
339: /**
340: * Get the listening point for a given transport. Null is returned if there is no
341: * listening point for that transport.
342: * @param transport -- the transport for the listening point
343: *
344: * @since 1.2
345: */
346:
347: public ListeningPoint getListeningPoint(String transport);
348:
349: /**
350: * Removes the specified ListeningPoint from this SipProvider. This method
351: * returns silently if the ListeningPoint is not associated to this
352: * SipProvider. A SipProvider must have at least a single ListeningPoint at
353: * all times. When the ListeningPoint is removed the SipProvider no further
354: * requests will be sent out over this ListeningPoint.
355: *
356: * @param listeningPoint the ListenPoint to be removed from this SipProvider.
357: * @throws ObjectInUseException if the ListeningPoint is already in use or
358: * is the last ListeningPoint associated with this SipProvider.
359: * @since 1.2
360: */
361: public void removeListeningPoint(ListeningPoint listeningPoint)
362: throws ObjectInUseException;
363:
364: /**
365: * Returns a unique CallIdHeader for identifying dialogues between two
366: * SIP applications.
367: *
368: * @return the new CallIdHeader unique within the SipProvider.
369: */
370: public CallIdHeader getNewCallId();
371:
372: /**
373: * Before an application can send a new request it must first request
374: * a new client transaction to handle that Request. This method is called
375: * by the application to create the new client transaction befores it sends
376: * the Request on that transaction. This methods returns
377: * a new unique client transaction that can be passed to send Requests
378: * statefully.
379: *
380: * @param request the new Request message that is to handled statefully by
381: * the ClientTransaction.
382: * @return a new unique client transaction.
383: * @throws TransactionUnavailableException if a new transaction can not be created, for example
384: * the next hop of the request can not be determined or the method is "ACK"
385: * @see ClientTransaction
386: *
387: * @note Do ~not~ call this method for ACK requests
388: */
389: public ClientTransaction getNewClientTransaction(Request request)
390: throws TransactionUnavailableException;
391:
392: /**
393: * An application has the responsibility of deciding to respond to a
394: * Request that does not match an existing server transaction. This method
395: * is called by an application that decides to respond to an unmatched
396: * Request statefully. This methods return a new unique server transaction
397: * that can be used to respond to the request statefully.
398: *
399: * @param request the Request message that the doesn't match an existing
400: * transaction that the application decides to handle statefully.
401: * @return a new unique server transaction.
402: * @throws TransactionAlreadyExistsException if a transaction already exists
403: * that is already handling this Request. This may happen if the application
404: * gets retransmits of the same request before the initial transaction is
405: * allocated.
406: * @throws TransactionUnavailableException if a new transaction can not be created, for example
407: * the next hop of the request can not be determined or the method is "ACK"
408: * @see ServerTransaction
409: *
410: * @note Do ~not~ call this method for ACK requests
411: */
412: public ServerTransaction getNewServerTransaction(Request request)
413: throws TransactionAlreadyExistsException,
414: TransactionUnavailableException;
415:
416: /**
417: * Sends the Request statelessly, that is no transaction record is
418: * associated with this action. This method implies that the application is
419: * functioning as a stateless proxy, hence the underlying SipProvider acts
420: * statelessly. A stateless proxy simply forwards every request it receives
421: * downstream and discards information about the Request message once the
422: * message has been forwarded. A stateless proxy does not have any notion
423: * of a transaction.
424: * <p>
425: * Once the Request message has been passed to this method, the SipProvider
426: * will forget about this Request. No transaction semantics will be
427: * associated with the Request and the SipProvider will not handle
428: * retranmissions for the Request. If these semantics are required it is the
429: * responsibility of the application not the SipProvider.
430: *
431: * @see Request
432: * @param request the Request message to send statelessly
433: * @throws SipException if the SipProvider cannot send the Request for any
434: * reason.
435: */
436: public void sendRequest(Request request) throws SipException;
437:
438: /**
439: * Sends the Response statelessly, that is no transaction record is
440: * associated with this action. This method implies that the application is
441: * functioning as either a stateless proxy or a stateless UAS.
442: * <ul>
443: * <li> Stateless proxy - A stateless proxy simply forwards every response
444: * it receives upstream and discards information about the response message
445: * once the message has been forwarded. A stateless proxy does not
446: * have any notion of a transaction.
447: * <li>Stateless UAS - A stateless UAS does not maintain
448: * transaction state. It replies to requests normally, but discards
449: * any state that would ordinarily be retained by a UAS after a response
450: * has been sent. If a stateless UAS receives a retransmission of a
451: * request, it regenerates the response and resends it, just as if it
452: * were replying to the first instance of the request. A UAS cannot be
453: * stateless unless the request processing for that method would always
454: * result in the same response if the requests are identical. Stateless
455: * UAS's do not use a transaction layer; they receive requests directly
456: * from the transport layer and send responses directly to the transport
457: * layer.
458: * </ul>
459: *
460: * @see Response
461: * @param response the Response to send statelessly.
462: * @throws SipException if the SipProvider cannot send the Response for any
463: * reason.
464: * @see Response
465: */
466: public void sendResponse(Response response) throws SipException;
467:
468: /**
469: * Create a dialog for the given transaction. This method is only called when
470: * AUTOMATIC_DIALOG_SUPPORT is off. This method is invoked when the
471: * application wants to explicitly manage the association between transaction
472: * and dialog. This must may only be called on a dialog-creating transaction.
473: * Dialogs are created in advance, before any responses are sent or received,
474: * using the initial client or server transaction. The Dialog state is
475: * set to null when the dialog is created.
476: * The server side of a dialog calls this method before sending out the
477: * response to a dialog creating request. The client side of the dialog
478: * calls this method before sending out the initial request via the dialog
479: * creating transaction. The caller is required to set up the tags and other
480: * information in the request/response before calling this method.
481: *
482: * <p> For UAC's Forked calls are handled as follows: The response
483: * of a forked call that completes the initially created dialog will use the
484: * original dialog that is associated with the transaction. Subsequent
485: * responses that correspond to other branches of the fork ( ie. with the
486: * same From header tag, and Call ID but different To header tags)
487: * result in the creation of additional dialogs that are associated with these
488: * responses. The created dialog is made available to the UAC ( Listener )
489: * via the method ResponseEvent.getDialog
490: *
491: * <p> Transactions that belong to the Dialog are
492: * automatically associated with the Dialog by the stack and can be retrieved
493: * with Transaction.getDialog().
494: *
495: *
496: *
497: * @param transaction - transaction that is used to extract the relevant
498: * information to create the dialog.
499: *
500: * @throws SipException if one or more of the following is true: <br/>
501: *<ol>
502: * <li>The Method of the Request is not a Dialog creating </li>
503: * <li>There is missing required information such as From header Tag
504: * in the Request </li>
505: * <li>This method is called after the response
506: * recieved on the client side </li>
507: * <li>This method is called after the
508: * response is sent out on the server side of the dialog. </li>
509: *</ol>
510: *
511: * @since 1.2
512: */
513: public Dialog getNewDialog(Transaction transaction)
514: throws SipException;
515:
516: /**
517: * Enable or disable automatic dialog creation for this Provider. By
518: * default, each provider inherits the automatic dialog support property
519: * from the stack(i.e. the value implied by the stack configuration property
520: * javax.sip.AUTOMATIC_DIALOG_SUPPORT) . This method allows for selective
521: * overriding of the stack-wide property on a per provider basis. This is
522: * useful for applications that need to support both user agent and proxy
523: * functionality in a single stack such as IMS applications and 3rd party
524: * call control. Provider instances that need to proxy requests while
525: * functioning transaction statefully should turn this property off.
526: * Provider instances that need to at as user agents can turn this support
527: * on and get the benifit of automatic dialog creation. If this support is
528: * enabled, then Dialog creating Transactions (i.e. INVITE) that are
529: * associated with this Provider automatically create a Dialog when the
530: * Transaction is created. If this support is disabled, then Transactions
531: * associated with this Provider do not result in the automatic creation of
532: * an associated Dialog at the time of Transaction creation.
533: *
534: * @param flag - enables or disables automatic dialog support for this provider.
535: *
536: * @see SipStack
537: * @since v1.2
538: *
539: */
540: public void setAutomaticDialogSupportEnabled(boolean flag);
541:
542: }
|