gov.nist.javax.sip
Class SipStackImpl
java.lang.Object
gov.nist.javax.sip.stack.SIPTransactionStack
gov.nist.javax.sip.SipStackImpl
- All Implemented Interfaces:
- EventListener, SipStack, SIPTransactionEventListener
- public class SipStackImpl
- extends SIPTransactionStack
- implements SipStack
Implementation of SipStack.
The JAIN-SIP stack is initialized by a set of properties (see the JAIN SIP
documentation for an explanation of these properties
SipStack ). In addition to these, the following are
meaningful properties for the NIST SIP stack (specify these in the property
array when you create the JAIN-SIP statck):
- gov.nist.javax.sip.TRACE_LEVEL = integer
Currently only TRACE
(16) and DEBUG is meaningful. If this is set to 16 or above, then incoming valid
messages are logged in SERVER_LOG. If you set this to 32 and specify a
DEBUG_LOG then vast amounts of trace information will be dumped in to the
specified DEBUG_LOG. The server log accumulates the signaling trace. This can be viewed
using the trace viewer tool . Please send us both the server log and
debug log when reporting non-obvious problems. You can also use the strings
DEBUG or INFO for level 32 and 16 respectively
- gov.nist.javax.sip.SERVER_LOG = fileName
Log valid
incoming messages here. If this is left null AND the TRACE_LEVEL is above 16
then the messages are printed to stdout. Otherwise messages are logged in a
format that can later be viewed using the trace viewer application which is
located in the tools/tracesviewer directory. Mail this to us
with bug reports.
- gov.nist.javax.sip.LOG_MESSAGE_CONTENT = true|false
Set
true if you want to capture content into the log. Default is false. A bad
idea to log content if you are using SIP to push a lot of bytes through TCP.
- gov.nist.javax.sip.DEBUG_LOG = fileName
Where the debug
log goes. Mail this to us with bug reports.
- gov.nist.javax.sip.MAX_MESSAGE_SIZE = integer
Maximum size
of content that a TCP connection can read. Must be at least 4K. Default is
"infinity" -- ie. no limit. This is to prevent DOS attacks launched by
writing to a TCP connection until the server chokes.
- gov.nist.javax.sip.CACHE_SERVER_CONNECTIONS = [true|false]
Default value is true. Setting this to true makes the Stack close the server
socket after a Server Transaction goes to the TERMINATED state. This allows a
server to protectect against TCP based Denial of Service attacks launched by
clients (ie. initiate hundreds of client gransactions). If false (default
action), the stack will keep the socket open so as to maximize performance at
the expense of Thread and memory resources - leaving itself open to DOS
attacks.
- gov.nist.javax.sip.CACHE_CLIENT_CONNECTIONS = [true|false]
Default value is true. Setting this to true makes the Stack close the server
socket aftera Client Transaction goes to the TERMINATED state. This allows a
client release any buffers threads and socket connections associated with a
client transaction after the transaction has terminated at the expense of
performance.
- gov.nist.javax.sip.THREAD_POOL_SIZE = integer
Concurrency
control for number of simultaneous active threads. If unspecificed, the
default is "infinity". This feature is useful if you are trying to build a
container.
-
- If this is not specified, and the listener is re-entrant, each
event delivered to the listener is run in the context of a new thread.
- If this is specified and the listener is re-entrant, then the stack will
run the listener using a thread from the thread pool. This allows you to
manage the level of concurrency to a fixed maximum. Threads are pre-allocated
when the stack is instantiated.
- If this is specified and the listener is not re-entrant, then the stack
will use the thread pool thread from this pool to parse and manage the state
machine but will run the listener in its own thread.
- gov.nist.javax.sip.REENTRANT_LISTENER = true|false
Default
is false. Set to true if the listener is re-entrant. If the listener is
re-entrant then the stack manages a thread pool and synchronously calls the
listener from the same thread which read the message. Multiple transactions
may concurrently receive messages and this will result in multiple threads
being active in the listener at the same time. The listener has to be written
with this in mind. If you want good performance on a multithreaded
machine write your listener to be re-entrant and set this property to be true
- gov.nist.javax.sip.MAX_CONNECTIONS = integer
Max number of
simultaneous TCP connections handled by stack.
- gov.nist.javax.sip.MAX_SERVER_TRANSACTIONS = integer
Maximum
size of server transaction table. The low water mark is 80% of the high water
mark. Requests are selectively dropped in the lowater mark to highwater mark
range. Requests are unconditionally accepted if the table is smaller than the
low water mark. The default highwater mark is 5000
- gov.nist.javax.sip.PASS_INIVTE_NON2XX_ACK_TO_LISTENER = true|false
If true then the listener will see the ACK for non-2xx responses
for server transactions. This is not standard behavior per RFC 3261 (INVITE
server transaction state machine) but this is a useful flag for testing. The
TCK uses this flag for example.
- gov.nist.javax.sip.MAX_LISTENER_RESPONSE_TIME = Integer
Max time (seconds) before sending a response to a server transaction.
If a response is not sent within this time period, the transaction will
be deleted by the stack. Default time is "infinity" - i.e. if the listener
never responds, the stack will hang on to a reference for the transaction
and result in a memory leak.
- gov.nist.javax.sip.USE_TLS_ACCELERATOR = true|false
Default value is false. Setting this to true permits the
delegation of TLS encryption/decryption to an external, non SIP-aware, TLS
accelerator hardware. Such deployment requires the SIP stack to make its TLS
traffic goes over un-encrypted TCP connections to the TLS accelerator. So
all TLS listening points will be listening for plain TCP traffic, and
outgoing messages sent with a TLS provider will not be encrypted. Note that
this does not affect the transport value in the Via header. Another
deployment strategy for TLS acceleration would be to use one or a cluster of
outbound proxies that transform the TCP or UDP SIP connection to TLS
connections. This scenario does not need the USE_TLS_ACCELERATOR switch, as
the messages will be sent using a plain TCP or UDP provider.
- gov.nist.javax.sip.DELIVER_TERMINATED_EVENT_FOR_ACK = [true|false]
Default is false. ACK Server Transaction is a Pseuedo-transaction.
If you want termination notification on ACK transactions (so all server
transactions can be handled uniformly in user code during cleanup), then
set this flag to true.
- gov.nist.javax.sip.READ_TIMEOUT = integer
This is relevant
for incoming TCP connections to prevent starvation at the server. This
defines the timeout in miliseconds between successive reads after the first
byte of a SIP message is read by the stack. All the sip headers must be
delivered in this interval and each successive buffer must be of the content
delivered in this interval. Default value is -1 (ie. the stack is wide open
to starvation attacks) and the client can be as slow as it wants to be.
- gov.nist.javax.sip.NETWORK_LAYER = classpath
This is an
EXPERIMENTAL property (still under active devlopment). Defines a network
layer that allows a client to have control over socket allocations and
monitoring of socket activity. A network layer should implement
gov.nist.core.net.NetworkLayer. The default implementation simply acts as a
wrapper for the standard java.net socket layer. This functionality is still
under active development (may be extended to support security and other
features).
- gov.nist.javax.sip.ADDRESS_RESOLVER = classpath
The fully
qualified class path for an implementation of the AddressResolver interface.
The AddressResolver allows you to support lookup schemes for addresses
that are not directly resolvable to IP adresses using getHostByName. Specifying
your own address resolver allows you to customize address lookup.
- gov.nist.javax.sip.AUTO_GENERATE_TIMESTAMP= [true| false]
Automatically
generate a getTimeOfDay timestamp for a retransmitted request if the original request contained
a timestamp. This is useful for profiling.
- gov.nist.javax.sip.THREAD_AUDIT_INTERVAL_IN_MILLISECS = long
Defines
how often the application intends to audit the SIP Stack about the health of its internal
threads (the property specifies the time in miliseconds between successive audits).
The audit allows the application to detect catastrophic failures like an internal
thread terminating because of an exception or getting stuck in a deadlock condition.
Events like these will make the stack inoperable and therefore require immediate action
from the application layer (e.g., alarms, traps, reboot, failover, etc.)
Thread audits are disabled by default. If this property is not specified, audits will
remain disabled. An example of how to use this property is in src/examples/threadaudit.
- Version:
- 1.2 $Revision: 1.55 $ $Date: 2006/11/16 16:17:11 $
- Author:
- M. Ranganathan
| Methods inherited from class gov.nist.javax.sip.stack.SIPTransactionStack |
addExtensionMethod, addTransaction, addTransaction, createClientTransaction, createDialog, createMessageChannel, createRawMessageChannel, createServerHeaderForStack, createServerTransaction, disableLogging, enableLogging, findCancelTransaction, findMergedTransaction, findPendingTransaction, findSubscribeTransaction, findTransaction, getAddressResolver, getDialog, getDialogs, getHostAddress, getLogWriter, getMaxMessageSize, getNetworkLayer, getNextHop, getRetransmissionAlertTransaction, getRouter, getRouter, getServerLog, getThreadAuditor, isAlive, isDialogCreated, isEventForked, isLoggingEnabled, mapTransaction, newSIPServerRequest, printDialogTable, putDialog, putPendingTransaction, removeDialog, removeFromMergeTable, removePendingTransaction, removeTransaction, setAddressResolver, setMaxConnections, setSingleThreaded, setStackName, setThreadPoolSize, stopStack, transactionErrorEvent |
SipStackImpl
public SipStackImpl(Properties configurationProperties)
throws PeerUnavailableException
- Constructor for the stack.
- Parameters:
configurationProperties - --
stack configuration properties including NIST-specific
extensions.
- Throws:
PeerUnavailableException
createListeningPoint
public ListeningPoint createListeningPoint(String address,
int port,
String transport)
throws TransportNotSupportedException,
InvalidArgumentException
- Description copied from interface:
SipStack
- 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.
- Specified by:
createListeningPoint in interface SipStack
- Returns:
- ListeningPoint that uses the IP address port and transport.
- Throws:
InvalidArgumentException
TransportNotSupportedException
createSipProvider
public SipProvider createSipProvider(ListeningPoint listeningPoint)
throws ObjectInUseException
- Description copied from interface:
SipStack
- 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.
- Specified by:
createSipProvider in interface SipStack
- Parameters:
listeningPoint - listening point for this SipProvider.
- Returns:
- the newly created SipProvider been started.
- Throws:
ObjectInUseException - if another SipProvider is already associated
with this ListeningPoint.
deleteListeningPoint
public void deleteListeningPoint(ListeningPoint listeningPoint)
throws ObjectInUseException
- Description copied from interface:
SipStack
- 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.
- Specified by:
deleteListeningPoint in interface 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.
deleteSipProvider
public void deleteSipProvider(SipProvider sipProvider)
throws ObjectInUseException
- Description copied from interface:
SipStack
- 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.
- Specified by:
deleteSipProvider in interface 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()
- Deprecated.
- Get the IP Address of the stack.
- Specified by:
getIPAddress in interface SipStack
- Returns:
- a string identifing the IP Address. Null if there is no default
IP address associated with the stack instance.
- See Also:
SipStack.getIPAddress()
getListeningPoints
public Iterator getListeningPoints()
- Description copied from interface:
SipStack
- Returns an Iterator of existing ListeningPoints created by this SipStack.
All of the ListeningPoints of this SipStack belong to the same stack
vendor.
- Specified by:
getListeningPoints in interface SipStack
- Returns:
- an Iterator containing all existing ListeningPoints created by
this SipStack. Returns an empty Iterator if no ListeningPoints
exist.
isRetransmissionFilterActive
public boolean isRetransmissionFilterActive()
- Deprecated.
- Return true if retransmission filter is active.
- Specified by:
isRetransmissionFilterActive in interface SipStack
- Returns:
- the value of the retransmission filter,
true if
the filter is set, false otherwise. - See Also:
SipStack.isRetransmissionFilterActive()
getSipProviders
public Iterator getSipProviders()
- Description copied from interface:
SipStack
- 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.
- Specified by:
getSipProviders in interface SipStack
- Returns:
- the list of Providers attached to this Sipstack.
getStackName
public String getStackName()
- Description copied from interface:
SipStack
- 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.
- Specified by:
getStackName in interface SipStack
- Returns:
- a string identifing the stack instance
finalize
public void finalize()
- Finalization -- stop the stack on finalization. Exit the transaction
scanner and release all resources.
- See Also:
java.lang.Object#finalize()
createListeningPoint
public ListeningPoint createListeningPoint(int port,
String transport)
throws TransportNotSupportedException,
InvalidArgumentException
- Deprecated.
- This uses the default stack address to create a listening point.
- Specified by:
createListeningPoint in interface SipStack
- Parameters:
port - the port of the new ListeningPoint.transport - the transport of the new ListeningPoint.
- Returns:
- the ListeningPoint attached to this SipStack.
- Throws:
InvalidArgumentException - if the specified port is invalid.
TransportNotSupportedException- See Also:
SipStack.createListeningPoint(java.lang.String, int,
java.lang.String)
stop
public void stop()
- Description copied from interface:
SipStack
- 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.
- Specified by:
stop in interface SipStack
start
public void start()
throws ProviderDoesNotExistException,
SipException
- Description copied from interface:
SipStack
- 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.
- Specified by:
start in interface SipStack
- Throws:
SipException - if the stack cannot be started due to some system
level failure.
ProviderDoesNotExistException
A product of the NIST/ITL Advanced Networking Technologies Division.
See conditions of use.
Submit a bug report or feature request.