javax.sip
Interface SipStack

public interface SipStack

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 SipListener interface to control the architecture and setup of the SIP stack. These methods include:

• Creation/deletion of SipProvider's that represent messaging objects that can be used by an application to send Request and Response messages statelessly or statefully via Client and Server transactions.
• Creation/deletion of ListeningPoint's that represent different ports and transports that a SipProvider can use to send and receive messages.

Architecture:
This specification mandates a single SipStack object per IP Address. There is 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 SipFactory.createSipStack(Properties) method, ensuring the SipFactory.setPathName(String) is set. Following the naming convention defined in 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	Sets the IP Address of the SipStack to the property value i.e 11.1.111.111. This property is mandatory.
javax.sip.STACK_NAME	Sets a user friendly name to identify the underlying stack implementation to the property value i.e. NISTv1.1. The stack name property should contain no spaces. This property is mandatory.
javax.sip.OUTBOUND_PROXY	Sets the outbound proxy of the SIP Stack. This property maps to the the outbound proxy parameter of the Router interface. The format of the outbound proxy parameter should be "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 before a dialog is established i.e. com.sun.javax.sip.RouteImpl. An application defined router object must implement the javax.sip.Router interface. Different routing policies may be based on opertaion mode i.e. User Agent or Proxy. 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 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.RETRANSMISSON_FILTER	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.

See Also:

SipFactory, SipProvider

Method Summary

ListeningPoint	createListeningPoint(int port, java.lang.String transport) Creates a new ListeningPoint on this SipStack on a specified port and transport, and returns a reference to the newly created ListeningPoint object.
SipProvider	createSipProvider(ListeningPoint listeningPoint) Creates a new peer SipProvider on this SipStack on a specified ListeningPoint and returns a reference to the newly created SipProvider object.
void	deleteListeningPoint(ListeningPoint listeningPoint) Deletes the specified ListeningPoint attached to this SipStack.
void	deleteSipProvider(SipProvider sipProvider) Deletes the specified peer SipProvider attached to this SipStack.
java.lang.String	getIPAddress() Gets the IP Address that identifies this SipStack instance.
java.util.Iterator	getListeningPoints() Returns an Iterator of existing ListeningPoints created by this SipStack.
Router	getRouter() Gets the Router object that identifies the default Router information of this SipStack, including the outbound proxy.
java.util.Iterator	getSipProviders() Returns an Iterator of existing SipProviders that have been created by this SipStack.
java.lang.String	getStackName() Gets the user friendly name that identifies this SipStack instance.
boolean	isRetransmissionFilterActive() This method returns the value of the retransmission filter helper function for User Agent applications.

Method Detail

createSipProvider

public SipProvider createSipProvider(ListeningPoint listeningPoint)
                              throws ObjectInUseException

Creates a new peer SipProvider on this SipStack on a specified ListeningPoint and returns a reference to the newly created SipProvider object. The newly created SipProvider is implicitly attached to this SipStack upon execution of this method, by adding the SipProvider to the list of SipProviders of this SipStack once it has been successfully created.

Parameters:

listeningPoint - the ListeningPoint the SipProvider is to be attached to in order to send and receive messages.

Returns:

the SipProvider attached to this SipStack on the specified ListeningPoint.

Throws:

ObjectInUseException - if another SipProvider is already using the ListeningPoint.

deleteSipProvider

public void deleteSipProvider(SipProvider sipProvider)
                       throws ObjectInUseException

Deletes the specified peer SipProvider attached to this SipStack. The specified SipProvider is implicitly detached from this SipStack upon execution of this method, by removing the SipProvider from the SipProviders list of this SipStack. Deletion of a SipProvider does not automatically delete the SipProvider's ListeningPoint from the SipStack.

Parameters:

sipProvider - the peer SipProvider to be deleted from this SipStack.

Throws:

ObjectInUseException - if the specified SipProvider cannot be deleted because the SipProvider is currently in use.

getSipProviders

public java.util.Iterator getSipProviders()

Returns an Iterator of existing SipProviders that have been created by this SipStack. All of the SipProviders of this SipStack will belong to the same stack vendor.

Returns:

an Iterator containing all existing SipProviders created by this SipStack. Returns an empty Iterator if no SipProviders exist.

createListeningPoint

public ListeningPoint createListeningPoint(int port,
                                           java.lang.String transport)
                                    throws TransportNotSupportedException,
                                           InvalidArgumentException

Creates a new ListeningPoint on this SipStack on a specified port and transport, and returns a reference to the newly created ListeningPoint object. The newly created ListeningPoint is implicitly attached to this SipStack upon execution of this method, by adding the ListeningPoint to the List of ListeningPoints of this SipStack once it has been successfully created.

Parameters:

port - the port of the new ListeningPoint.

transport - the transport of the new ListeningPoint.

Returns:

the ListeningPoint attached to this SipStack.

Throws:

TansportNotSupportedException - if the specified transport is not supported by this SipStack.

InvalidArgumentException - if the specified port is invalid.

TransportNotSupportedException

Since:

v1.1

deleteListeningPoint

public void deleteListeningPoint(ListeningPoint listeningPoint)
                          throws ObjectInUseException

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.

Parameters:

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.

Since:

v1.1

getListeningPoints

public java.util.Iterator getListeningPoints()

Returns an Iterator of existing ListeningPoints created by this SipStack. All of the ListeningPoints of this SipStack belong to the same stack vendor.

Returns:

an Iterator containing all existing ListeningPoints created by this SipStack. Returns an empty Iterator if no ListeningPoints exist.

getStackName

public java.lang.String getStackName()

Gets the user friendly name that identifies this SipStack instance. This value is set using the Properties object passed to the SipFactory.createSipStack(Properties) method upon creation of the SipStack object.

Returns:

a string identifing the stack instance

getIPAddress

public java.lang.String getIPAddress()

Gets the IP Address that identifies this SipStack instance. Every SipStack object must have an IP Address and only one SipStack object can service an IP Address. This value is set using the Properties object passed to the SipFactory.createSipStack(Properties) method upon creation of the SipStack object.

Returns:

a string identifing the IP Address

Since:

v1.1

getRouter

public Router getRouter()

Gets the Router object that identifies the default Router information of this SipStack, including the outbound proxy. This value is set using the Properties object passed to the SipFactory.createSipStack(Properties) method upon creation of the SipStack object.

Returns:

the Router object identifying the Router information.

Since:

v1.1

isRetransmissionFilterActive

public boolean isRetransmissionFilterActive()

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 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 Timeout.RETRANSMIT notifications encapsulated in TimeoutEvent's, however an application will be notified if the underlying transaction expires with a Timeout.TRANSACTION notification encapsulated in a TimeoutEvent.

Returns:

the value of the retransmission filter, true if the filter is set, false otherwise.

Since:

v1.1