sip.SipStack Maven / Gradle / Ivy
/**
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Unpublished - rights reserved under the Copyright Laws of the United States.
* Copyright ? 2003 Sun Microsystems, Inc. All rights reserved.
* Copyright ? 2005 BEA Systems, Inc. All rights reserved.
*
* Use is subject to license terms.
*
* This distribution may include materials developed by third parties.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Module Name : JSIP Specification
* File Name : SipStack.java
* Author : Phelim O'Doherty
*
* HISTORY
* Version Date Author Comments
* 1.1 08/10/2002 Phelim O'Doherty Reworked
* 1.2 19/05/2005 Phelim O'Doherty Added new new config parameters
* Added new createListeningPoint
* method with IP address
* Added start and stop stack methods
* M. Ranganathan Fixed documentation.
*
*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
package javax.sip;
import javax.sip.address.Router;
import java.util.*;
/**
* This interface represents the management interface of a SIP stack
* implementing this specification and as such is the interface that defines the
* management/architectural view of the SIP stack. It defines the methods
* required to represent and provision a proprietary SIP protocol stack.
*
* This SipStack interface defines the methods that are be used by an
* application implementing the {@link javax.sip.SipListener} interface to
* control the architecture and setup of the SIP stack. These methods include:
*
* - Creation/deletion of {@link javax.sip.SipProvider}'s that represent
* messaging objects that can be used by an application to send
* {@link javax.sip.message.Request}and {@link javax.sip.message.Response}
* messages statelessly or statefully via Client and Server transactions.
*
- Creation/deletion of {@link javax.sip.ListeningPoint}'s that represent
* different ports and transports that a SipProvider can use to send and receive
* messages.
*
* Architecture:
* This specification mandates a one-to-many relationship between a SipStack
* and a SipProvider. There is a one-to-many relationship between a SipStack
* and a ListeningPoint.
*
* SipStack Creation
* An application must create a SipStack by invoking the
* {@link SipFactory#createSipStack(Properties)}method, ensuring the
* {@link SipFactory#setPathName(String)}is set. Following the naming
* convention defined in {@link javax.sip.SipFactory}, the implementation of
* the SipStack interface must be called SipStackImpl. This specification also
* defines a stack configuration mechanism using java.util.Properties, therefore
* this constructor must also accept a properties argument:
*
*
public SipStackImpl(Properties properties) {}
*
* The following table documents the static configuration properties which can
* be set for an implementation of a SipStack. This specification doesn't
* preclude additional values within a configuration properties object if
* understood by the underlying implementation. In order to change these
* properties after a SipStack has been initialized the SipStack must be deleted
* and recreated:
*
*
*
*
*
*
*
* SipStack Property
*
*
* Description
*
*
*
*
*
*
*
* javax.sip.IP_ADDRESS
*
*
*
*
* Deprecated v1.2. It is recommended in this specification that the IP
* Address should be set using the enhanced ListeningPoint architecture,
* therefore this property is no longer mandatory. When this parameter is
* specified as null, a singleton stack instance will be created and returned
* by the SipFactory and the IP Address attributes can be managed via the
* {@link SipStack#createListeningPoint(String, int, String)} method. For
* backwards compatability if this flag is set the SipFactory will return a new
* SipStack instance each time a SipStack is created with a new IP Address.
* This configuration parameter will become the default IP address of the
* SipStack. The SIP Factory will return any any existing instance of SipStack
* that already exist for this IP Address.
*
*
*
*
*
*
* javax.sip.STACK_NAME
*
*
*
*
* Sets a user friendly name to identify the underlying stack implementation to
* the property value i.e. NISTv1.2. The stack name property should contain no
* spaces. This property is mandatory.
*
*
*
*
*
*
* javax.sip.OUTBOUND_PROXY
*
*
*
*
* Sets the outbound proxy of the SIP Stack. The fromat
* for this string is "ipaddress:port/transport" i.e.
* 129.1.22.333:5060/UDP. This property is optional.
*
*
*
*
*
*
*
* javax.sip.ROUTER_PATH
*
*
*
*
* Sets the fully qualified classpath to the application supplied Router object
* that determines how to route messages when the stack cannot make a routing
* decision ( ie. non-sip URIs). In version 1.2 of this specification,
* out of Dialog SIP URIs are routed by the Routing algorithm defined in RFC 3261
* which is implemented internally by the stack provided that
* javax.sip.USE_ROUTER_FOR_ALL_URIS is set to false. In this case,
* the installed Router object is consulted for routing decisions pertaining to
* non-SIP URIs. An application defined Router object must implement the javax.sip.Router interface.
* This property is optional.
*
*
*
*
*
*
* javax.sip.EXTENSION_METHODS
*
*
*
*
* This configuration value informs the underlying implementation of supported
* extension methods that create new dialog's. This list must not include methods
* that are natively supported by this specification such as INVITE, SUBSCRIBE and REFER.
* This configuration flag should
* only be used for dialog creating extension methods, other extension methods
* that don't create dialogs can be used using the method parameter on Request
* assuming the implementation understands the method. If more than one method
* is supported in this property each extension should be seprated with a colon
* for example "FOO:BAR". This property is optional.
*
*
*
*
*
*
* javax.sip.RETRANSMISSION_FILTER
*
*
* Deprecated v1.2. Applications can request
* retransmission alerts from the
* {@link ServerTransaction#enableRetransmissionAlerts()}.
*
* The default retransmission behaviour of this
* specification is dependent on the application core and is defined
* as follows:
*
* - User Agent Client: Retransmissions of ACK Requests are the
* responsibility of the application. All other retansmissions are
* handled by the SipProvider.
*
- User Agent Server: Retransmissions of 1xx, 2xx Responses are the
* responsibility of the application. All other retansmissions are
* handled by the SipProvider.
*
- Stateful Proxy: As stateful proxies have no Invite
* transactions all retransmissions are handled by the SipProvider.
*
- Stateless Proxy: As stateless proxies are not transactional
* all retransmissions are the responsibility of the application
* and will not be handled the SipProvider.
*
* This filter can be viewed as a helper function for User Agents
* that can be set by an application to prevent the application
* from handling retransmission of ACK Requests, 1xx and 2xx
* Responses for INVITE transactions, i.e. the SipProvider will
* handle the retransmissions. This utility is useful for hiding
* protocol retransmission semantics from higher level
* programming environments. The acceptable values are ON/OFF. This
* property is optional, therefore if not supplied the default is
* OFF.
*
*
*
*
*
*
* javax.sip.AUTOMATIC_DIALOG_SUPPORT
*
*
* This property specifies the defined values
* 'ON' and 'OFF'. The default value is 'ON'. The default behavior represents a
* common mode of stack operation and allows the construction of simple user
* agents. This property is optional. This is summarized as:
*
* - A dialog gets created on a dialog creating transaction.
* - The first respose having both a From and a To tag creates the transaction.
*
- The first 2xx response to the transaction will drive the dialog to the
* CONFIRMED state.
*
*
* The ability to turn of dialog support is motivated by dialog free
* servers (such as proxy servers) that do not want to pay the overhead of the
* dialog layer and user agents that may want to create multiple dialogs for a
* single INVITE (as a result of forking by proxy servers). The following
* behavior is defined when the configuration parameter is set to 'OFF'.
*
* - The application is responsible to create the Dialog if desired.
* - The application may create a Dialog and associate it with a response
* (provisional or final) of a dialog creating request.
*
*
* Since v1.2.
*
*
*
*
*
*
* javax.sip.FORKABLE_EVENTS
*
*
*
*
* Comma separated list of events for which the implementation should expect forked
* SUBSCRIBE dialogs. Each element of this list must have the syntax packagename.eventname
*
* This configuration parameter is provided in order to support the following behavior ( defined
* in RFC 3265):
*
* Successful SUBSCRIBE requests will normally receive only
* one 200-class response; however, due to forking, the subscription may
* have been accepted by multiple nodes. The subscriber MUST therefore
* be prepared to receive NOTIFY requests with "From:" tags which differ
* from the "To:" tag received in the SUBSCRIBE 200-class response.
*
* If multiple NOTIFY messages are received in different dialogs in
* response to a single SUBSCRIBE message, each dialog represents a
* different destination to which the SUBSCRIBE request was forked.
*
* Each event package MUST specify whether forked SUBSCRIBE requests are
* allowed to install multiple subscriptions.If such behavior is not allowed,
* the first potential dialog-establishing message will create a dialog.
* All subsequent NOTIFY messages which correspond to the SUBSCRIBE message
* (i.e., match "To","From", "From" header "tag" parameter, "Call-ID", "CSeq", "Event",
* and "Event" header "id" parameter) but which do not match the dialog
* would be rejected with a 481 response. This property is optional.
*
* Since v1.2
*
*
*
*
*
*
*
* javax.sip.USE_ROUTER_FOR_ALL_URIS
*
*
*
*
* If set to true then the application installed
* Router is consulted for ALL routing decisions (ie. both out of dialog SIP and non-SIP request
* URI's -- identitcal to the behavior supported in v1.1 of this specification). If set to
* false the user installed router will only be consulted for routing of Non-SIP URIs.
* Implementations may thus provide support for sophisticated operations such as DNS lookup
* for SIP URI's using the proceedures defined in RFC 3263
* (support for RFC 3263 is not mandatory for this specification). This property is optional.
* The default value for this parameter is true .
*
* Since v1.2.
*
*
*
*
TransportNotSupportedException
* if the Properties specified during stack creation do not include an IP Address.
*/
public ListeningPoint createListeningPoint(int port, String transport)
throws TransportNotSupportedException, InvalidArgumentException;
/**
* Creates a ListeningPoint a given IP address, port and transport. If this
* method is used, the IP address of the stack is ignored and a listening
* point is created with the given parameters. This support is useful for
* multi-homed hosts which may have to listen at multiple IP addresses and
* have different dialogs for each IP address.
*
* @return ListeningPoint that uses the IP address port and transport.
* @throws SipException if the Listening point cannot be created for any reason or if the
* stack has specified a default IP address that differs from the IP address specified
* for this method.
* @throws InvalidArgumentException
* @since 1.2
*/
public ListeningPoint createListeningPoint(String ipAddress, int port,
String transport) throws TransportNotSupportedException, InvalidArgumentException;
/**
* Deletes the specified ListeningPoint attached to this SipStack. The
* specified ListeningPoint is implicitly detached from this SipStack upon
* execution of this method, by removing the ListeningPoint from the
* ListeningPoints list of this SipStack.
*
* @param listeningPoint
* the SipProvider to be deleted from this SipStack.
* @throws ObjectInUseException
* if the specified ListeningPoint cannot be deleted because the
* ListeningPoint is currently in use.
*/
public void deleteListeningPoint(ListeningPoint listeningPoint)
throws ObjectInUseException;
/**
* Returns an Iterator of existing ListeningPoints created by this SipStack.
* All of the ListeningPoints of this SipStack belong to the same stack
* vendor.
*
* @return an Iterator containing all existing ListeningPoints created by
* this SipStack. Returns an empty Iterator if no ListeningPoints
* exist.
*/
public Iterator getListeningPoints();
// Configuration methods
/**
* Gets the user friendly name that identifies this SipStack instance. This
* value is set using the Properties object passed to the
* {@link SipFactory#createSipStack(Properties)}method upon creation of the
* SipStack object.
*
* @return a string identifing the stack instance
*/
public String getStackName();
/**
* Gets the IP Address that identifies this SipStack instance. Every
* SipStack object may have an IP Address. This specification recommends
* associating the IP address with the {@link ListeningPoint}.
* For backwards compatability if an IP address is specified in the
* Properties object passed to the
* {@link SipFactory#createSipStack(Properties)} method upon creation of
* the SipStack object then this becomes the default IP address of the
* SipStack object, ListeningPoints can then be created on this IP Address.
*
* @return a string identifing the IP Address. Null if there is no default
* IP address associated with the stack instance.
*/
public String getIPAddress();
/**
* Gets the Router object that identifies the default Router information of
* this SipStack. This value is set using the Properties object passed to
* the {@link SipFactory#createSipStack(Properties)}method upon creation of
* the SipStack object.
*
* @return the Router object identifying the Router information.
*/
public Router getRouter();
/**
* This methods initiates the shutdown of the stack. The stack will
* terminate all ongoing transactions, without providing
* notificatin to the listener, close all listening points and release all
* resources associated with this stack. Note that this is a hard stop and
* should be used with care. The application may build graceful stop
* measures if needed, however the implementation is expected to
* immediately release any resources such as threads sockets and buffers
* that are allocated to this stack.
*
* @since 1.2
*/
public void stop();
/**
* This method initiates the active processing of the stack. This method is
* used to start the stack after the necessary SipProviders have been
* created. After calling this method, the stack can handle incoming
* requests and responses on the ListeningPoints associated to the
* SipProviders.
*
* @throws SipException if the stack cannot be started due to some system
* level failure.
*
* @since 1.2
*/
public void start() throws SipException;
/**
* This method returns the value of the retransmission filter helper
* function for User Agent applications. This value is set using the
* Properties object passed to the
* {@link SipFactory#createSipStack(Properties)}method upon creation of the
* SipStack object.
*
* The default value of the retransmission filter boolean is false
* . When this value is set to true, retransmissions
* of ACK's and 2xx responses to an INVITE transaction are handled by the
* SipProvider, hence the application will not receive
* {@link Timeout#RETRANSMIT}notifications encapsulated in
* {@link javax.sip.TimeoutEvent}'s, however an application will be
* notified if the underlying transaction expires with a
* {@link Timeout#TRANSACTION}notification encapsulated in a TimeoutEvent.
*
* @deprecated Since v1.2. This retransmission filter property has been deprecated
* as a SIP Stack property. Applications can enable retransmission alerts by using the
* {@link ServerTransaction#enableRetransmissionAlerts()} method.
*
* @return the value of the retransmission filter, true if
* the filter is set, false otherwise.
*/
public boolean isRetransmissionFilterActive();
}