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 : SipStack.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 19/05/2005 Phelim O'Doherty Added new new config parameters
021: * Added new createListeningPoint
022: * method with IP address
023: * Added start and stop stack methods
024: * M. Ranganathan Fixed documentation.
025: *
026: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
027: */package javax.sip;
028:
029: import javax.sip.address.Router;
030: import java.util.*;
031:
032: /**
033: * This interface represents the management interface of a SIP stack
034: * implementing this specification and as such is the interface that defines the
035: * management/architectural view of the SIP stack. It defines the methods
036: * required to represent and provision a proprietary SIP protocol stack.
037: * <p>
038: * This SipStack interface defines the methods that are be used by an
039: * application implementing the {@link javax.sip.SipListener} interface to
040: * control the architecture and setup of the SIP stack. These methods include:
041: * <ul>
042: * <li>Creation/deletion of {@link javax.sip.SipProvider}'s that represent
043: * messaging objects that can be used by an application to send
044: * {@link javax.sip.message.Request}and {@link javax.sip.message.Response}
045: * messages statelessly or statefully via Client and Server transactions.
046: * <li>Creation/deletion of {@link javax.sip.ListeningPoint}'s that represent
047: * different ports and transports that a SipProvider can use to send and receive
048: * messages.
049: * </ul>
050: * <b>Architecture: </b> <br>
051: * This specification mandates a one-to-many relationship between a SipStack
052: * and a SipProvider. There is a one-to-many relationship between a SipStack
053: * and a ListeningPoint.
054: * <p>
055: * <b>SipStack Creation </b> <br>
056: * An application must create a SipStack by invoking the
057: * {@link SipFactory#createSipStack(Properties)}method, ensuring the
058: * {@link SipFactory#setPathName(String)}is set. Following the naming
059: * convention defined in {@link javax.sip.SipFactory}, the implementation of
060: * the SipStack interface must be called SipStackImpl. This specification also
061: * defines a stack configuration mechanism using java.util.Properties, therefore
062: * this constructor must also accept a properties argument:
063: * <p>
064: * <center>public SipStackImpl(Properties properties) {} </center>
065: * <p>
066: * The following table documents the static configuration properties which can
067: * be set for an implementation of a SipStack. This specification doesn't
068: * preclude additional values within a configuration properties object if
069: * understood by the underlying implementation. In order to change these
070: * properties after a SipStack has been initialized the SipStack must be deleted
071: * and recreated:
072: * <p>
073: * <center><table border="1" bordercolorlight="#FFFFFF"
074: * bordercolordark="#000000" width="98%" cellpadding="3" cellspacing="0">
075: * <p class="title">
076: * </p>
077: * <tr bgcolor="#CCCCCC">
078: * <th align="left" valign="top">
079: * <p class="table">
080: * <strong><strong>SipStack Property </strong> </strong></th>
081: * <th align="left" valign="top"></a>
082: * <p class="table">
083: * <strong>Description </strong>
084: * </p>
085: * </th>
086: * </tr>
087: *
088: * <tr>
089: * <td align="left" valign="top">
090: * <p class="table">
091: * javax.sip.IP_ADDRESS
092: * </p>
093: * </td>
094: * <td align="left" valign="top">
095: * <p class="table">
096: * <b>Deprecated v1.2.</b> It is recommended in this specification that the IP
097: * Address should be set using the enhanced ListeningPoint architecture,
098: * therefore this property is no longer mandatory. When this parameter is
099: * specified as null, a singleton stack instance will be created and returned
100: * by the SipFactory and the IP Address attributes can be managed via the
101: * {@link SipStack#createListeningPoint(String, int, String)} method. For
102: * backwards compatability if this flag is set the SipFactory will return a new
103: * SipStack instance each time a SipStack is created with a new IP Address.
104: * This configuration parameter will become the default IP address of the
105: * SipStack. The SIP Factory will return any any existing instance of SipStack
106: * that already exist for this IP Address.
107: * </td>
108: * </tr>
109: *
110: * <tr>
111: * <td align="left" valign="top">
112: * <p class="table">
113: * javax.sip.STACK_NAME
114: * </p>
115: * </td>
116: * <td align="left" valign="top">
117: * <p class="table">
118: * Sets a user friendly name to identify the underlying stack implementation to
119: * the property value i.e. NISTv1.2. The stack name property should contain no
120: * spaces. This property is mandatory.
121: * </p>
122: * </td>
123: * </tr>
124: * <tr>
125: * <td align="left" valign="top">
126: * <p class="table">
127: * javax.sip.OUTBOUND_PROXY
128: * </p>
129: * </td>
130: * <td align="left" valign="top">
131: * <p class="table">
132: * Sets the outbound proxy of the SIP Stack. The fromat
133: * for this string is "ipaddress:port/transport" i.e.
134: * 129.1.22.333:5060/UDP. This property is optional.
135: * </p>
136: * </td>
137: * </tr>
138: *
139: * <tr>
140: * <td align="left" valign="top">
141: * <p class="table">
142: * javax.sip.ROUTER_PATH
143: * </p>
144: * </td>
145: * <td align="left" valign="top">
146: * <p class="table">
147: * Sets the fully qualified classpath to the application supplied Router object
148: * that determines how to route messages when the stack cannot make a routing
149: * decision ( ie. non-sip URIs). In version 1.2 of this specification,
150: * out of Dialog SIP URIs are routed by the Routing algorithm defined in RFC 3261
151: * which is implemented internally by the stack provided that
152: * javax.sip.USE_ROUTER_FOR_ALL_URIS is set to false. In this case,
153: * the installed Router object is consulted for routing decisions pertaining to
154: * non-SIP URIs. An application defined Router object must implement the javax.sip.Router interface.
155: * This property is optional.
156: * </td>
157: * </tr>
158: *
159: * <tr>
160: * <td align="left" valign="top">
161: * <p class="table">
162: * javax.sip.EXTENSION_METHODS
163: * </p>
164: * </td>
165: * <td align="left" valign="top">
166: * <p class="table">
167: * This configuration value informs the underlying implementation of supported
168: * extension methods that create new dialog's. This list must not include methods
169: * that are natively supported by this specification such as INVITE, SUBSCRIBE and REFER.
170: * This configuration flag should
171: * only be used for dialog creating extension methods, other extension methods
172: * that don't create dialogs can be used using the method parameter on Request
173: * assuming the implementation understands the method. If more than one method
174: * is supported in this property each extension should be seprated with a colon
175: * for example "FOO:BAR". This property is optional.
176: * </p>
177: * </td>
178: * </tr>
179: *
180: * <tr>
181: * <td align="left" valign="top">
182: * <p class="table">javax.sip.RETRANSMISSION_FILTER</p>
183: * </td>
184: * <td align="left" valign="top">
185: * <p class="table"><b>Deprecated v1.2.</b> Applications can request
186: * retransmission alerts from the
187: * {@link ServerTransaction#enableRetransmissionAlerts()}.
188: * <p>
189: * The default retransmission behaviour of this
190: * specification is dependent on the application core and is defined
191: * as follows:
192: * <ul>
193: * <li>User Agent Client: Retransmissions of ACK Requests are the
194: * responsibility of the application. All other retansmissions are
195: * handled by the SipProvider.
196: * <li>User Agent Server: Retransmissions of 1xx, 2xx Responses are the
197: * responsibility of the application. All other retansmissions are
198: * handled by the SipProvider.
199: * <li>Stateful Proxy: As stateful proxies have no Invite
200: * transactions all retransmissions are handled by the SipProvider.
201: * <li>Stateless Proxy: As stateless proxies are not transactional
202: * all retransmissions are the responsibility of the application
203: * and will not be handled the SipProvider.
204: * </ul>
205: * This filter can be viewed as a helper function for User Agents
206: * that can be set by an application to prevent the application
207: * from handling retransmission of ACK Requests, 1xx and 2xx
208: * Responses for INVITE transactions, i.e. the SipProvider will
209: * handle the retransmissions. This utility is useful for hiding
210: * protocol retransmission semantics from higher level
211: * programming environments. The acceptable values are ON/OFF. This
212: * property is optional, therefore if not supplied the default is
213: * OFF.
214: * </td>
215: * </tr>
216: *
217: * <tr>
218: * <td align="left" valign="top">
219: * <p class="table">
220: * javax.sip.AUTOMATIC_DIALOG_SUPPORT
221: * </p>
222: * </td>
223: * <td align="left" valign="top">This property specifies the defined values
224: * 'ON' and 'OFF'. The default value is 'ON'. The default behavior represents a
225: * common mode of stack operation and allows the construction of simple user
226: * agents. This property is optional. This is summarized as:</li>
227: * <ul>
228: * <li>A dialog gets created on a dialog creating transaction.</li>
229: * <li> The first respose having both a From and a To tag creates the transaction.
230: * <li>The first 2xx response to the transaction will drive the dialog to the
231: * CONFIRMED state.</li>
232: * </ul>
233: * </ul>
234: * <blockquote>The ability to turn of dialog support is motivated by dialog free
235: * servers (such as proxy servers) that do not want to pay the overhead of the
236: * dialog layer and user agents that may want to create multiple dialogs for a
237: * single INVITE (as a result of forking by proxy servers). The following
238: * behavior is defined when the configuration parameter is set to 'OFF'.
239: * <ul type="circle">
240: * <li>The application is responsible to create the Dialog if desired.</li>
241: * <li>The application may create a Dialog and associate it with a response
242: * (provisional or final) of a dialog creating request. </li>
243: * </ul>
244: * </blockquote>
245: * <b>Since v1.2.</b>
246: * </td>
247: * </tr>
248: *
249: * <tr>
250: * <td align="left" valign="top">
251: * <p class="table">
252: * javax.sip.FORKABLE_EVENTS
253: * </p>
254: * </td>
255: * <td align="left" valign="top">
256: * <p class="table">
257: * Comma separated list of events for which the implementation should expect forked
258: * SUBSCRIBE dialogs. Each element of this list must have the syntax packagename.eventname
259: *
260: * This configuration parameter is provided in order to support the following behavior ( defined
261: * in RFC 3265):
262: *
263: * Successful SUBSCRIBE requests will normally receive only
264: * one 200-class response; however, due to forking, the subscription may
265: * have been accepted by multiple nodes. The subscriber MUST therefore
266: * be prepared to receive NOTIFY requests with "From:" tags which differ
267: * from the "To:" tag received in the SUBSCRIBE 200-class response.
268: *
269: * If multiple NOTIFY messages are received in different dialogs in
270: * response to a single SUBSCRIBE message, each dialog represents a
271: * different destination to which the SUBSCRIBE request was forked.
272: *
273: * Each event package MUST specify whether forked SUBSCRIBE requests are
274: * allowed to install multiple subscriptions.If such behavior is not allowed,
275: * the first potential dialog-establishing message will create a dialog.
276: * All subsequent NOTIFY messages which correspond to the SUBSCRIBE message
277: * (i.e., match "To","From", "From" header "tag" parameter, "Call-ID", "CSeq", "Event",
278: * and "Event" header "id" parameter) but which do not match the dialog
279: * would be rejected with a 481 response. This property is optional.
280: * <p>
281: * <b>Since v1.2</b>
282: * </p>
283: * </td>
284: * </tr>
285: *
286: * <tr>
287: * <td align="left" valign="top">
288: * <p class="table">
289: * javax.sip.USE_ROUTER_FOR_ALL_URIS
290: * </p>
291: * </td>
292: * <td align="left" valign="top">
293: * <p class="table">
294: * If set to <it>true</it> then the application installed
295: * Router is consulted for ALL routing decisions (ie. both out of dialog SIP and non-SIP request
296: * URI's -- identitcal to the behavior supported in v1.1 of this specification). If set to
297: * <it>false</it> the user installed router will only be consulted for routing of Non-SIP URIs.
298: * Implementations may thus provide support for sophisticated operations such as DNS lookup
299: * for SIP URI's using the proceedures defined in RFC 3263
300: * (support for RFC 3263 is not mandatory for this specification). This property is optional.
301: * The default value for this parameter is <it>true</it>.
302: * <p>
303: * <b>Since v1.2.</b>
304: * </td>
305: * </tr>
306: *
307: * </table> </center>
308: *
309: * @see SipFactory
310: * @see SipProvider
311: *
312: * @author BEA Systems, NIST
313: * @version 1.2
314: *
315: */
316:
317: public interface SipStack {
318:
319: /**
320: * Creates a new peer SipProvider on this SipStack on a specified
321: * ListeningPoint and returns a reference to the newly created SipProvider
322: * object. The newly created SipProvider is implicitly attached to this
323: * SipListener upon execution of this method, by adding the SipProvider to
324: * the list of SipProviders of this SipStack once it has been successfully
325: * created.
326: *
327: * @param listeningPoint listening point for this SipProvider.
328: * @throws ObjectInUseException if another SipProvider is already associated
329: * with this ListeningPoint.
330: * @return the newly created SipProvider been started.
331: */
332: public SipProvider createSipProvider(ListeningPoint listeningPoint)
333: throws ObjectInUseException;
334:
335: /**
336: * Deletes the specified peer SipProvider attached to this SipStack. The
337: * specified SipProvider is implicitly detached from this SipStack upon
338: * execution of this method, by removing the SipProvider from the
339: * SipProviders list of this SipStack. Deletion of a SipProvider does not
340: * automatically delete the SipProvider's ListeningPoint from the SipStack.
341: *
342: * @param sipProvider the peer SipProvider to be deleted from this
343: * SipStack.
344: * @throws ObjectInUseException if the specified SipProvider cannot be
345: * deleted because the SipProvider is currently in use.
346: *
347: */
348: public void deleteSipProvider(SipProvider sipProvider)
349: throws ObjectInUseException;
350:
351: /**
352: * Returns an Iterator of existing SipProviders that have been created by
353: * this SipStack. All of the SipProviders of this SipStack will belong to
354: * the same stack vendor.
355: *
356: * @return the list of Providers attached to this Sipstack.
357: */
358: public Iterator getSipProviders();
359:
360: /**
361: * Creates a new ListeningPoint on this SipStack on a specified port and
362: * transport and the default IP address of this stack as specified by the
363: * SipStack IP address configuration parameter, and returns a reference to
364: * the newly created ListeningPoint object. The newly created ListeningPoint
365: * is implicitly attached to this SipStack upon execution of this method, by
366: * adding the ListeningPoint to the List of ListeningPoints of this SipStack
367: * once it has been successfully created.
368: *
369: * @return the ListeningPoint attached to this SipStack.
370: * @param port
371: * the port of the new ListeningPoint.
372: * @param transport
373: * the transport of the new ListeningPoint.
374: * @throws TansportNotSupportedException
375: * if the specified transport is not supported by this SipStack.
376: * @throws InvalidArgumentException
377: * if the specified port is invalid.
378: *
379: * @deprecated Since v1.2. This has been replaced by
380: * {@link SipStack#createListeningPoint(String, int, String) }
381: * For backwards compatibility with v1.1 implementations should support this method.
382: * Implementations should throw <it>TransportNotSupportedException</it>
383: * if the Properties specified during stack creation do not include an IP Address.
384: */
385: public ListeningPoint createListeningPoint(int port,
386: String transport) throws TransportNotSupportedException,
387: InvalidArgumentException;
388:
389: /**
390: * Creates a ListeningPoint a given IP address, port and transport. If this
391: * method is used, the IP address of the stack is ignored and a listening
392: * point is created with the given parameters. This support is useful for
393: * multi-homed hosts which may have to listen at multiple IP addresses and
394: * have different dialogs for each IP address.
395: *
396: * @return ListeningPoint that uses the IP address port and transport.
397: * @throws SipException if the Listening point cannot be created for any reason or if the
398: * stack has specified a default IP address that differs from the IP address specified
399: * for this method.
400: * @throws InvalidArgumentException
401: * @since 1.2
402: */
403: public ListeningPoint createListeningPoint(String ipAddress,
404: int port, String transport)
405: throws TransportNotSupportedException,
406: InvalidArgumentException;
407:
408: /**
409: * Deletes the specified ListeningPoint attached to this SipStack. The
410: * specified ListeningPoint is implicitly detached from this SipStack upon
411: * execution of this method, by removing the ListeningPoint from the
412: * ListeningPoints list of this SipStack.
413: *
414: * @param listeningPoint
415: * the SipProvider to be deleted from this SipStack.
416: * @throws ObjectInUseException
417: * if the specified ListeningPoint cannot be deleted because the
418: * ListeningPoint is currently in use.
419: */
420: public void deleteListeningPoint(ListeningPoint listeningPoint)
421: throws ObjectInUseException;
422:
423: /**
424: * Returns an Iterator of existing ListeningPoints created by this SipStack.
425: * All of the ListeningPoints of this SipStack belong to the same stack
426: * vendor.
427: *
428: * @return an Iterator containing all existing ListeningPoints created by
429: * this SipStack. Returns an empty Iterator if no ListeningPoints
430: * exist.
431: */
432: public Iterator getListeningPoints();
433:
434: // Configuration methods
435:
436: /**
437: * Gets the user friendly name that identifies this SipStack instance. This
438: * value is set using the Properties object passed to the
439: * {@link SipFactory#createSipStack(Properties)}method upon creation of the
440: * SipStack object.
441: *
442: * @return a string identifing the stack instance
443: */
444: public String getStackName();
445:
446: /**
447: * Gets the IP Address that identifies this SipStack instance. Every
448: * SipStack object may have an IP Address. This specification recommends
449: * associating the IP address with the {@link ListeningPoint}.
450: * For backwards compatability if an IP address is specified in the
451: * Properties object passed to the
452: * {@link SipFactory#createSipStack(Properties)} method upon creation of
453: * the SipStack object then this becomes the default IP address of the
454: * SipStack object, ListeningPoints can then be created on this IP Address.
455: *
456: * @return a string identifing the IP Address. Null if there is no default
457: * IP address associated with the stack instance.
458: */
459: public String getIPAddress();
460:
461: /**
462: * Gets the Router object that identifies the default Router information of
463: * this SipStack. This value is set using the Properties object passed to
464: * the {@link SipFactory#createSipStack(Properties)}method upon creation of
465: * the SipStack object.
466: *
467: * @return the Router object identifying the Router information.
468: */
469: public Router getRouter();
470:
471: /**
472: * This methods initiates the shutdown of the stack. The stack will
473: * terminate all ongoing transactions, without providing
474: * notificatin to the listener, close all listening points and release all
475: * resources associated with this stack. Note that this is a hard stop and
476: * should be used with care. The application may build graceful stop
477: * measures if needed, however the implementation is expected to
478: * immediately release any resources such as threads sockets and buffers
479: * that are allocated to this stack.
480: *
481: * @since 1.2
482: */
483: public void stop();
484:
485: /**
486: * This method initiates the active processing of the stack. This method is
487: * used to start the stack after the necessary SipProviders have been
488: * created. After calling this method, the stack can handle incoming
489: * requests and responses on the ListeningPoints associated to the
490: * SipProviders.
491: *
492: * @throws SipException if the stack cannot be started due to some system
493: * level failure.
494: *
495: * @since 1.2
496: */
497: public void start() throws SipException;
498:
499: /**
500: * This method returns the value of the retransmission filter helper
501: * function for User Agent applications. This value is set using the
502: * Properties object passed to the
503: * {@link SipFactory#createSipStack(Properties)}method upon creation of the
504: * SipStack object.
505: * <p>
506: * The default value of the retransmission filter boolean is <var>false
507: * </var>. When this value is set to <code>true</code>, retransmissions
508: * of ACK's and 2xx responses to an INVITE transaction are handled by the
509: * SipProvider, hence the application will not receive
510: * {@link Timeout#RETRANSMIT}notifications encapsulated in
511: * {@link javax.sip.TimeoutEvent}'s, however an application will be
512: * notified if the underlying transaction expires with a
513: * {@link Timeout#TRANSACTION}notification encapsulated in a TimeoutEvent.
514: *
515: * @deprecated Since v1.2. This retransmission filter property has been deprecated
516: * as a SIP Stack property. Applications can enable retransmission alerts by using the
517: * {@link ServerTransaction#enableRetransmissionAlerts()} method.
518: *
519: * @return the value of the retransmission filter, <code>true</code> if
520: * the filter is set, <code>false</code> otherwise.
521: */
522: public boolean isRetransmissionFilterActive();
523:
524: }
|