| javax.sip.SipStack
| SipStack | | public interface SipStack (Code) | | 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
javax.sip.SipListener interface to
control the architecture and setup of the SIP stack. These methods include:
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
SipFactory.createSipStack(Properties) method, ensuring the
SipFactory.setPathName(String) is set. Following the naming
convention defined in
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
SipStack.createListeningPoint(StringintString) 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
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.
|
See Also: SipFactory
See Also: SipProvider
author:
BEA Systems, NIST
version:
1.2 |
| Method Summary | |
| public ListeningPoint | createListeningPoint(int port, String transport)
Creates a new ListeningPoint on this SipStack on a specified port and
transport and the default IP address of this stack as specified by the
SipStack IP address configuration parameter, and returns a reference to
the newly created ListeningPoint object. | | public ListeningPoint | createListeningPoint(String ipAddress, int port, String transport)
Creates a ListeningPoint a given IP address, port and transport. | | public 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. | | public void | deleteListeningPoint(ListeningPoint listeningPoint)
Deletes the specified ListeningPoint attached to this SipStack. | | public void | deleteSipProvider(SipProvider sipProvider)
Deletes the specified peer SipProvider attached to this SipStack. | | public String | getIPAddress()
Gets the IP Address that identifies this SipStack instance. | | public 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.
an Iterator containing all existing ListeningPoints created bythis SipStack. | | public Router | getRouter()
Gets the Router object that identifies the default Router information of
this SipStack. | | public Iterator | getSipProviders()
Returns an Iterator of existing SipProviders that have been created by
this SipStack. | | public String | getStackName()
Gets the user friendly name that identifies this SipStack instance. | | public boolean | isRetransmissionFilterActive()
This method returns the value of the retransmission filter helper
function for User Agent applications. | | public void | start()
This method initiates the active processing of the stack. | | public void | stop()
This methods initiates the shutdown of the stack. |
| createListeningPoint | | public ListeningPoint createListeningPoint(int port, String transport) throws TransportNotSupportedException, InvalidArgumentException(Code) | | Creates a new ListeningPoint on this SipStack on a specified port and
transport and the default IP address of this stack as specified by the
SipStack IP address configuration parameter, 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.
the ListeningPoint attached to this SipStack.
Parameters:
port - the port of the new ListeningPoint.
Parameters:
transport - the transport of the new ListeningPoint.
throws:
TansportNotSupportedException - if the specified transport is not supported by this SipStack.
throws:
InvalidArgumentException - if the specified port is invalid.SipStack.createListeningPoint(StringintString) |
| createListeningPoint | | public ListeningPoint createListeningPoint(String ipAddress, int port, String transport) throws TransportNotSupportedException, InvalidArgumentException(Code) | | 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.
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 |
| createSipProvider | | public SipProvider createSipProvider(ListeningPoint listeningPoint) throws ObjectInUseException(Code) | | 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
SipListener 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 - listening point for this SipProvider.
throws:
ObjectInUseException - if another SipProvider is already associated with this ListeningPoint. the newly created SipProvider been started. |
| deleteListeningPoint | | public void deleteListeningPoint(ListeningPoint listeningPoint) throws ObjectInUseException(Code) | | 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 theListeningPoint is currently in use. |
| deleteSipProvider | | public void deleteSipProvider(SipProvider sipProvider) throws ObjectInUseException(Code) | | 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. |
| getIPAddress | | public String getIPAddress()(Code) | | 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
ListeningPoint .
For backwards compatability if an IP address is specified in the
Properties object passed to the
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.
a string identifing the IP Address. Null if there is no default IP address associated with the stack instance. |
| getListeningPoints | | public Iterator getListeningPoints()(Code) | | Returns an Iterator of existing ListeningPoints created by this SipStack.
All of the ListeningPoints of this SipStack belong to the same stack
vendor.
an Iterator containing all existing ListeningPoints created bythis SipStack. Returns an empty Iterator if no ListeningPointsexist. |
| getRouter | | public Router getRouter()(Code) | | Gets the Router object that identifies the default Router information of
this SipStack. This value is set using the Properties object passed to
the
SipFactory.createSipStack(Properties) method upon creation of
the SipStack object.
the Router object identifying the Router information. |
| getSipProviders | | public Iterator getSipProviders()(Code) | | 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.
the list of Providers attached to this Sipstack. |
| getStackName | | public String getStackName()(Code) | | 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.
a string identifing the stack instance |
| isRetransmissionFilterActive | | public boolean isRetransmissionFilterActive()(Code) | | 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
javax.sip.TimeoutEvent 's, however an application will be
notified if the underlying transaction expires with a
Timeout.TRANSACTION notification encapsulated in a TimeoutEvent.
ServerTransaction.enableRetransmissionAlerts the value of the retransmission filter, true ifthe filter is set, false otherwise. |
| start | | public void start() throws SipException(Code) | | 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 |
| stop | | public void stop()(Code) | | 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 |
|
|