gov.nist.javax.sip

Class SipStackImpl

java.lang.Object

gov.nist.javax.sip.stack.SIPTransactionStack

gov.nist.javax.sip.SipStackImpl

All Implemented Interfaces:

SipStackExt, SIPDialogEventListener, SIPTransactionEventListener, EventListener, SipStack

public class SipStackImpl
extends SIPTransactionStack
implements SipStack, SipStackExt

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 ). For NIST SIP stack all properties can also be passed as JVM system properties from the command line as -D arguments. 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
  Use of this property is still supported but deprecated. Please use gov.nist.javax.sip.STACK_LOGGER and gov.nist.javax.sip.SERVER_LOGGER for integration with logging frameworks and for custom formatting of log records. This property is used by the built in log4j based logger. You can use the standard log4j level names here (i.e. ERROR, INFO, WARNING, OFF, DEBUG, TRACE) If this is set to INFO 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. If the value of this property is set to LOG4J, then the effective log levels are determined from the log4j settings file (e.g. log4j.properties). The logger name for the stack is specified using the gov.nist.javax.sip.LOG4J_LOGGER_NAME property. By default log4j logger name for the stack is the same as the stack name. For example, properties.setProperty("gov.nist.javax.sip.TRACE_LEVEL", "LOG4J"); properties.setProperty("gov.nist.javax.sip.LOG4J_LOGGER_NAME", "SIPStackLogger"); allows you to now control logging in the stack entirely using log4j facilities.
• gov.nist.javax.sip.LOG_FACTORY = classpath Use of this property is still supported but deprecated. Please use gov.nist.javax.sip.STACK_LOGGER and gov.nist.javax.sip.SERVER_LOGGER for integration with logging frameworks and for custom formatting of log records.
  The fully qualified classpath for an implementation of the MessageLogFactory. The stack calls the MessageLogFactory functions to format the log for messages that are received or sent. This function allows you to log auxiliary information related to the application or environmental conditions into the log stream. The log factory must have a default constructor.
• gov.nist.javax.sip.SERVER_LOG = fileName
  Use of this property is still supported but deprecated. Please use gov.nist.javax.sip.STACK_LOGGER and gov.nist.javax.sip.SERVER_LOGGER for integration with logging frameworks and for custom formatting of log records. Log valid incoming messages here. If this is left null AND the TRACE_LEVEL is above INFO (or TRACE) 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.DEBUG_LOG = fileName Use of this property is still supported but deprecated. Please use gov.nist.javax.sip.STACK_LOGGER and gov.nist.javax.sip.SERVER_LOGGER for integration with logging frameworks and for custom formatting of log records.
  Where the debug log goes. 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.LOG_STACK_TRACE_ON_MESSAGE_SEND = true|false
  Set true if you want to to log a stack trace at INFO level for each message send. This is really handy for debugging.
• gov.nist.javax.sip.STACK_LOGGER = full path name to the class implementing gov.nist.core.StackLogger interface
  If this property is defined the sip stack will try to instantiate it through a no arg constructor. This allows to use different logging implementations than the ones provided by default to log what happens within the stack while processing SIP messages. If this property is not defined, the default sip stack LogWriter will be used for logging
• gov.nist.javax.sip.SERVER_LOGGER = full path name to the class implementing gov.nist.core.ServerLogger interface
  If this property is defined the sip stack will try to instantiate it through a no arg constructor. This allows to use different logging implementations than the ones provided by default to log sent/received messages by the sip stack. If this property is not defined, the default sip stack ServerLog will be used for logging
• gov.nist.javax.sip.AUTOMATIC_DIALOG_ERROR_HANDLING = [true|false]
  Default is true. This is also settable on a per-provider basis. This flag is set to true by default. When set to false the following behaviors are enabled:
  • Turn off Merged requests Loop Detection:
    The following behavior is turned off: If the request has no tag in the To header field, the UAS core MUST check the request against ongoing transactions. If the From tag, Call-ID, and CSeq exactly match those associated with an ongoing transaction, but the request does not match that transaction (based on the matching rules in Section 17.2.3), the UAS core SHOULD generate a 482 (Loop Detected) response and pass it to the server transaction.
• gov.nist.javax.sip.IS_BACK_TO_BACK_USER_AGENT = [true|false]
  Default is false This property controls a setting on the Dialog objects that the stack manages. Pure B2BUA applications should set this flag to true. This property can also be set on a per-dialog basis. Setting this to true imposes serialization on re-INVITE and makes the sending of re-INVITEs asynchronous. The sending of re-INVITE is controlled as follows : If the previous in-DIALOG request was an invite ClientTransaction then the next re-INVITEs that uses the dialog will wait till an ACK has been sent before admitting the new re-INVITE. If the previous in-DIALOG transaction was a INVITE ServerTransaction then Dialog waits for ACK before re-INVITE is allowed to be sent. If a dialog is not ACKed within 32 seconds, then the dialog is torn down and a BYE sent to the peer.
• 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.DELIVER_TERMINATED_EVENT_FOR_NULL_DIALOG = [true|false]
  If set to false (the default), the application does NOT get notified when a Dialog in the NULL state is terminated. ( Dialogs in the NULL state are not associated with an actual SIP Dialog. They are a programming convenience. A Dialog is in the NULL state before the first response for the Dialog forming Transaction). If set to true, the SipListener will get a DialogTerminatedEvent when a Dialog in the NULL state is terminated.
• gov.nist.javax.sip.CACHE_SERVER_CONNECTIONS = [true|false]
  Default value is true. Setting this to false 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 transactions). If true (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 false makes the Stack close the server socket after a 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.MAX_CLIENT_TRANSACTIONS = integer
  Max number of active client transactions before the caller blocks and waits for the number to drop below a threshold. Default is unlimited, i.e. the caller never blocks and waits for a client transaction to become available (i.e. it does its own resource management in the application).
• gov.nist.javax.sip.PASS_INVITE_NON_2XX_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) to wait on the transaction lock used to serialize message delivery. 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 unusable thread stuck waiting for the lock to be released. A good value for this property is the lifespan of the transaction or the expected blocking delay in the listener.
• gov.nist.javax.sip.MAX_TX_LIFETIME_INVITE = Integer
  Defaults -1 : infinite. Typical can be dependent on early dialog timeout by example 3 minutes could be a good default Max time (seconds) an INVITE transaction is supposed to live in the stack. This is to avoid any leaks in whatever state the transaction can be in even if the application misbehaved When the max time is reached, a timeout event will fire up to the application listener so that the application can take action and then will be removed from the stack after the typical lingering period of 8s in the stack
• gov.nist.javax.sip.MAX_TX_LIFETIME_NON_INVITE = Integer
  Defaults -1 : infinite. Typical is dependent on T1 by example 2 * T1 could be a good default Max time (seconds) a non INVITE transaction is supposed to live in the stack. This is to avoid any leaks in whatever state the transaction can be in even if the application misbehaved When the max time is reached, a timeout event will fire up to the application listener so that the application can take action and then will be removed from the stack after the typical lingering period of 8s in the stack. There is a specific property as a non INVITE property is short live as compared to INVITE and so can be collected ore eagerly to save up on memory usage
• 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. The default address resolver is a pass-through address resolver (i.e. just returns the input string without doing a resolution). See gov.nist.javax.sip.DefaultAddressResolver.
• gov.nist.javax.sip.AUTO_GENERATE_TIMESTAMP= [true| false]
  (default is 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.
• gov.nist.javax.sip.NIO_MAX_SOCKET_IDLE_TIME = long
  Defines the number of milliseconds a NIO TCP socket will be kept alive after the last IO operation on that socket. This allows to clean up after high initial load of new calls that hang up or stay idle. Note that disconnecting the socket does't end the SIP call. A new socket will be established when needed for any existing calls by the SIP RFC spec.
• gov.nist.javax.sip.stack.USE_DIRECT_BUFFERS = [true|false]
  Default is true If set to false, the NIO stack won't use direct buffers. As Direct buffers reside outside of the heap memory, they can lead to unforeseen out of memory exceptions as seen in http://java.net/jira/browse/JSIP-430. This flag allows to use non direct buffers for better memory monitoring and management.
• gov.nist.javax.sip.COMPUTE_CONTENT_LENGTH_FROM_MESSAGE_BODY = [true|false]
  Default is false If set to true, when you are creating a message from a String, the MessageFactory will compute the content length from the message content and ignore the provided content length parameter in the Message. Otherwise, it will use the content length supplied and generate a parse exception if the content is truncated.
• gov.nist.javax.sip.CANCEL_CLIENT_TRANSACTION_CHECKED = [true|false]
  Default is true. This flag is added in support of load balancers or failover managers where you may want to cancel ongoing transactions from a different stack than the original stack. If set to false then the CANCEL client transaction is not checked for the existence of the INVITE or the state of INVITE when you send the CANCEL request. Hence you can CANCEL an INVITE from a different stack than the INVITE. You can also create a CANCEL client transaction late and send it out after the INVITE server transaction has been Terminated. Clearly this will result in protocol errors. Setting the flag to true ( default ) enables you to avoid common protocol errors.
• gov.nist.javax.sip.IS_BACK_TO_BACK_USER_AGENT = [true|false]
  Default is false This property controls a setting on the Dialog objects that the stack manages. Pure B2BUA applications should set this flag to true. This property can also be set on a per-dialog basis. Setting this to true imposes serialization on re-INVITE and makes the sending of re-INVITEs asynchronous. The sending of re-INVITE is controlled as follows : If the previous in-DIALOG request was an invite ClientTransaction then the next re-INVITEs that uses the dialog will wait till an ACK has been sent before admitting the new re-INVITE. If the previous in-DIALOG transaction was a INVITE ServerTransaction then Dialog waits for ACK before re-INVITE is allowed to be sent. If a dialog is not ACKed within 32 seconds, then the dialog is torn down and a BYE sent to the peer.
• gov.nist.javax.sip.RECEIVE_UDP_BUFFER_SIZE = int
  Default is 8*1024. This property control the size of the UDP buffer used for SIP messages. Under load, if the buffer capacity is overflown the messages are dropped causing retransmissions, further increasing the load and causing even more retransmissions. Good values to this property for servers is a big number in the order of 8*8*1024.
• gov.nist.javax.sip.SEND_UDP_BUFFER_SIZE = int
  Default is 8*1024. This property control the size of the UDP buffer used for SIP messages. Under load, if the buffer capacity is overflown the messages are dropped causing retransmissions, further increasing the load and causing even more retransmissions. Good values to this property for servers is a big number in the order of 8*8*1024 or higher.
• gov.nist.javax.sip.CONGESTION_CONTROL_TIMEOUT = int How much time messages are allowed to wait in queue before being dropped due to stack being too slow to respond. Default value is 8000 ms. The value is in milliseconds
• gov.nist.javax.sip.TCP_POST_PARSING_THREAD_POOL_SIZE = integer Use 0 or do not set this option to disable it. When using TCP your phones/clients usually connect independently creating their own TCP sockets. Sometimes however SIP devices are allowed to tunnel multiple calls over a single socket. This can also be simulated with SIPP by running "sipp -t t1". In the stack each TCP socket has it's own thread. When all calls are using the same socket they all use a single thread, which leads to severe performance penalty, especially on multi-core machines. This option instructs the SIP stack to use a thread pool and split the CPU load between many threads. The number of the threads is specified in this parameter. The processing is split immediately after the parsing of the message. It cannot be split before the parsing because in TCP the SIP message size is in the Content-Length header of the message and the access to the TCP network stream has to be synchronized. Additionally in TCP the message size can be larger. This causes most of the parsing for all calls to occur in a single thread, which may have impact on the performance in trivial applications using a single socket for all calls. In most applications it doesn't have performance impact. If the phones/clients use separate TCP sockets for each call this option doesn't have much impact, except the slightly increased memory footprint caused by the thread pool. It is recommended to disable this option in this case by setting it 0 or not setting it at all. You can simulate multi-socket mode with "sipp -t t0". With this option also we avoid closing the TCP socket when something fails, because we must keep processing other messages for other calls. Note: This option relies on accurate Content-Length headers in the SIP messages. It cannot recover once a malformed message is processed, because the stream iterator will not be aligned any more. Eventually the connection will be closed.
• gov.nist.javax.sip.DELIVER_UNSOLICITED_NOTIFY = [true|false]
  Default is false. This flag is added to allow Sip Listeners to receive all NOTIFY requests including those that are not part of a valid dialog.
• gov.nist.javax.sip.REJECT_STRAY_RESPONSES = [true|false] Default is false A flag that checks responses to test whether the response corresponds to a via header that was previously generated by us. Note that setting this flag implies that the stack will take control over setting the VIA header for Sip Requests sent through the stack. The stack will attach a suffix to the VIA header branch and check any response arriving at the stack to see if that response suffix is present. If it is not present, then the stack will silently drop the response.
• gov.nist.javax.sip.MAX_FORK_TIME_SECONDS = integer Maximum time for which the original transaction for which a forked response is received is tracked. This property is only relevant to Dialog Stateful applications ( User Agents or B2BUA). When a forked response is received in this time interval from when the original INVITE client transaction was sent, the stack will place the original INVITE client transction in the ResponseEventExt and deliver that to the application. The event handler can get the original transaction from this event.
• gov.nist.javax.sip.EARLY_DIALOG_TIMEOUT_SECONDS=integer Maximum time for which a dialog can remain in early state. This is defaulted to 3 minutes ( 180 seconds).
• gov.nist.javax.sip.THREAD_PRIORITY=integer Control the priority of the threads started by the stack.
• gov.nist.javax.sip.MESSAGE_PARSER_FACTORY = name of the class implementing gov.nist.javax.sip.parser.MessageParserFactory This factory allows pluggable implementations of the MessageParser that will take care of parsing the incoming messages. By example one could plug a lazy parser through this factory.
• gov.nist.javax.sip.MESSAGE_PROCESSOR_FACTORY = name of the class implementing gov.nist.javax.sip.parser.MessageProcessorFactory This factory allows pluggable implementations of the MessageProcessor that will take care of incoming messages. By example one could plug a NIO Processor through this factory.
• gov.nist.javax.sip.TIMER_CLASS_NAME = name of the class implementing gov.nist.javax.sip.stack.timers.SipTimer interface This allows pluggable implementations of the Timer that will take care of scheduling the various SIP Timers. By example one could plug a regular timer, a scheduled thread pool executor.
• gov.nist.javax.sip.DELIVER_RETRANSMITTED_ACK_TO_LISTENER=boolean A testing property that allows application to see the ACK for retransmitted 200 OK requests. Note that this is for test purposes only
*
• gov.nist.javax.sip.AGGRESSIVE_CLEANUP=boolean A property that will cleanup Dialog, and Transaction structures agrressively to improve memroy usage and performance (up to 50% gain). However one needs to be careful in its code on how and when it accesses transaction and dialog data since it cleans up aggressively when transactions changes state to COMPLETED or TERMINATED and for Dialog once the ACK is received/sent
• gov.nist.javax.sip.MIN_KEEPALIVE_TIME_SECONDS = integer Minimum time between keep alive pings (CRLF CRLF) from clients. If pings arrive with less than this frequency they will be replied with CRLF CRLF if greater they will be rejected. The default is -1 (i.e. do not respond to CRLF CRLF).
• gov.nist.javax.sip.DIALOG_TIMEOUT_FACTOR= integer Default to 64. The number of ticks before a dialog that does not receive an ACK receives a Timeout notification. Note that this is only relevant if the registered SipListener is of type SipListenerExt
• gov.nist.javax.sip.SIP_MESSAGE_VALVE= String Default to null. The class name of your custom valve component. An instance of this class will be created and the SIPMessageValve.processRequest/Response() methods will be called for every message before any long-lived SIP Stack resources are allocated (no transactions, no dialogs). From within the processRequest callback implementation you can drop messages, send a response statelessly or otherwise transform/pre-process the message before it reaches the next steps of the pipeline. Similarly from processResponse() you can manipulate a response or drop it silently, but dropping responses is not recommended, because the transaction already exists when the request for the response was sent.
• gov.nist.javax.sip.SIP_EVENT_INTERCEPTOR Default to null. The class name of your custom interceptor object. An instance of this object will be created at initialization of the stack. You must implement the interface gov.nist.javax.sip.stack.SIPEventInterceptor and handle the lifecycle callbacks. This interface is the solution for https://jain-sip.dev.java.net/issues/show_bug.cgi?id=337 . It allows to wrap the JSIP pipeline and execute custom analysis logic as SIP messages advance through the pipeline checkpoints. One example implementation of this interceptor is gov.nist.javax.sip.stack.CallAnalysisInterceptor, which will periodically check for requests stuck in the JAIN SIP threads and if some request is taking too long it will log the stack traces for all threads. The logging can occur only on certain events, so it will not overwhelm the CPU. The overall performance penalty by using this class in production under load is only 2% peak on average laptop machine. There is minimal locking inside. One known limitation of this feature is that you must use gov.nist.javax.sip.REENTRANT_LISTENER=true to ensure that the request will be processed in the original thread completely for UDP.
• gov.nist.javax.sip.TLS_CLIENT_PROTOCOLS = String Comma-separated list of protocols to use when creating outgoing TLS connections. The default is "TLSv1.2, TLSv1.1, TLSv1". It's advisable not to use SSL protocols because of http://googleonlinesecurity.blogspot.fr/2014/10/this-poodle-bites-exploiting-ssl-30.html
• gov.nist.javax.sip.TLS_SECURITY_POLICY = String The fully qualified path name of a TLS Security Policy implementation that is consulted for certificate verification of outbund TLS connections.
• gov.nist.javax.sip.TLS_CLIENT_AUTH_TYPE = String Valid values are Default (backward compatible with previous versions) , Enabled, Want, Disabled or DisabledAll. Set to Enabled if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. Set to Want if you want the SSL stack to request a client Certificate, but not fail if one isn't presented. A Disabled value will not require a certificate chain for the Server Connection. A DisabledAll will not require a certificate chain for both Server and Client Connections.
• gov.nist.javax.sip.RELIABLE_CONNECTION_KEEP_ALIVE_TIMEOUT Value in seconds which is used as default keepalive timeout (See also http://tools.ietf.org/html/rfc5626#section-4.4.1). Defaults to "infiinity" seconds (i.e. timeout event not delivered).
• gov.nist.javax.sip.SSL_HANDSHAKE_TIMEOUT Value in seconds which is used as default timeout for performing the SSL Handshake This prevents bad clients of connecting without sending any data to block the server
• gov.nist.javax.sip.SSL_RENEGOTIATION_ENABLED = [true|false] Default value is true. Allow or disallow SSL renegotiation to resolve potential DoS problem - reference and another reference. The safe option is to disable it.
• javax.net.ssl.keyStore = fileName
  Default is NULL. If left undefined the keyStore and trustStore will be left to the java runtime defaults. If defined, any TLS sockets created (client and server) will use the key store provided in the fileName. The trust store will default to the same store file. A password must be provided to access the keyStore using the following property:
  properties.setProperty("javax.net.ssl.keyStorePassword", "<password>"); properties.setProperty("javax.net.ssl.trustStorePassword", "<password>");
  If not trustStorePassword is provided then the keyStorePassword will be used for both. The trust store can be changed, to a separate file with the following setting:
  properties.setProperty("javax.net.ssl.trustStore", "<trustStoreFileName location>");
  If the trust store property is provided the password on the trust store must be the same as the key store.
  
  

Note that the stack supports the extensions that are defined in SipStackExt. These will be supported in the next release of JAIN-SIP. You should only use the extensions that are defined in this class.

Version:

1.2 $Revision: 1.143 $ $Date: 2010-12-02 22:04:18 $

Author:

M. Ranganathan

Nested Class Summary

Nested classes/interfaces inherited from class gov.nist.javax.sip.stack.SIPTransactionStack

SIPTransactionStack.PingTimer

Field Summary

Fields

Modifier and Type	Field and Description
protected Hashtable<String,ListeningPointImpl>	listeningPoints
static Integer	MAX_DATAGRAM_SIZE Max datagram size.
protected List<SipProviderImpl>	sipProviders

Fields inherited from class gov.nist.javax.sip.stack.SIPTransactionStack

addressResolver, aggressiveCleanup, BASE_TIMER_INTERVAL, cacheClientConnections, cacheServerConnections, cancelClientTransactionChecked, checkBranchId, clientAuth, clientTransactionTable, clientTransactionTableHiwaterMark, clientTransactionTableLowaterMark, CONNECTION_LINGER_TIME, defaultRouter, deliverRetransmittedAckToListener, dialogCreatingMethods, dialogTable, dialogTimeoutFactor, earlyDialogTable, earlyDialogTimeout, forkedEvents, generateTimeStampHeader, ioHandler, isAutomaticDialogErrorHandlingEnabled, isAutomaticDialogSupportEnabled, isBackToBackUserAgent, isDialogTerminatedEventDeliveredForNullDialog, logRecordFactory, logStackTraceOnMessageSend, maxConnections, maxContentLength, maxForkTime, maxListenerResponseTime, maxMessageSize, maxTxLifetimeInvite, maxTxLifetimeNonInvite, messageParserFactory, messageProcessorFactory, minKeepAliveInterval, needsLogging, networkLayer, nioSocketMaxIdleTime, outboundProxy, readTimeout, receiveUdpBufferSize, reliableConnectionKeepAliveTimeout, remoteTagReassignmentAllowed, retransmissionAlertTransactions, rfc2543Supported, router, routerPath, securityManagerProvider, selfRoutingThreadpoolExecutor, sendUdpBufferSize, serverDialogMergeTestTable, serverLogger, serverTransactionTable, serverTransactionTableHighwaterMark, serverTransactionTableLowaterMark, sipEventInterceptor, sipMessageFactory, sipMessageValve, socketTimeoutAuditor, stackAddress, stackCongenstionControlTimeout, stackInetAddress, stackName, threadAuditor, threadPoolSize, toExit, unlimitedClientTransactionTableSize, unlimitedServerTransactionTableSize, useRouterForAll

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SipStackImpl() Creates a new instance of SipStackImpl.
	SipStackImpl(Properties configurationProperties) Constructor for the stack.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	acquireSem()
void	addLogAppender(org.apache.log4j.Appender appender) Deprecated. TODO: remove this method May 11, 2010.
ListeningPoint	createListeningPoint(int port, String transport) Deprecated.
ListeningPoint	createListeningPoint(String address, int port, String transport) Creates a ListeningPoint a given IP address, port and transport.
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.
protected void	finalize() Finalization -- stop the stack on finalization.
AuthenticationHelper	getAuthenticationHelper(AccountManager accountManager, HeaderFactory headerFactory) Get the authentication helper.
Properties	getConfigurationProperties()
String[]	getEnabledCipherSuites() Return the currently enabled cipher suites of the Stack.
String[]	getEnabledProtocols() Return the currently enabled protocols to use when creating TLS connection.
EventScanner	getEventScanner()
String	getIPAddress() Deprecated.
Iterator	getListeningPoints() Returns an Iterator of existing ListeningPoints created by this SipStack.
org.apache.log4j.Logger	getLogger() Deprecated. TODO: This method will be removed May 11, 2010.
LogRecordFactory	getLogRecordFactory() Get the message log factory registered with the stack.
AuthenticationHelper	getSecureAuthenticationHelper(SecureAccountManager accountManager, HeaderFactory headerFactory) Get the authentication helper.
SipListener	getSipListener() Get the listener for the stack.
Iterator<SipProviderImpl>	getSipProviders() Returns an Iterator of existing SipProviders that have been created by this SipStack.
String	getStackName() Gets the user friendly name that identifies this SipStack instance.
TlsSecurityPolicy	getTlsSecurityPolicy() Get the TLS Security Policy implementation for the stack.
boolean	isAutomaticDialogErrorHandlingEnabled()
boolean	isBackToBackUserAgent() Get the "back to back User Agent" flag.
boolean	isReEntrantListener()
boolean	isRetransmissionFilterActive() Deprecated.
void	releaseSem()
void	setEnabledCipherSuites(String[] newCipherSuites) Set the list of cipher suites supported by the stack.
void	setEnabledProtocols(String[] newProtocols) Set the list of protocols supported by the stack for outgoing TLS connections.
void	setIsBackToBackUserAgent(boolean flag) Set the "back to back User Agent" flag.
void	setTlsSecurityPolicy(TlsSecurityPolicy tlsSecurityPolicy)
void	start() This method initiates the active processing of the stack.
void	stop() This methods initiates the shutdown of the stack.

Methods inherited from class gov.nist.javax.sip.stack.SIPTransactionStack

addExtensionMethod, addForkedClientTransaction, addMessageProcessor, addTransaction, addTransaction, addTransactionPendingAck, auditStack, checkBranchId, closeAllSockets, closeReliableConnection, createClientTransaction, createDialog, createDialog, createDialog, createDialog, createMessageChannel, createMessageProcessor, createRawMessageChannel, createServerTransaction, decrementActiveClientTransactionCount, dialogErrorEvent, disableLogging, enableLogging, findCancelTransaction, findMergedTransaction, findPendingTransaction, findSubscribeTransaction, findTransaction, findTransaction, findTransactionPendingAck, getAckTimeoutFactor, getActiveClientTransactionCount, getAddressResolver, getClientAuth, getClientTransactionTableSize, getDialog, getDialogs, getDialogs, getEarlyDialog, getEarlyDialogTimeout, getForkedTransaction, getHostAddress, getJoinDialog, getLocalAddressForTcpDst, getLocalAddressForTlsDst, getMaxForkTime, getMaxMessageSize, getMaxTxLifetimeInvite, getMaxTxLifetimeNonInvite, getMessageParserFactory, getMessageProcessorFactory, getMessageProcessors, getMinKeepAliveInterval, getNetworkLayer, getNextHop, getReceiveUdpBufferSize, getReinviteExecutor, getReliableConnectionKeepAliveTimeout, getReplacesDialog, getRetransmissionAlertTransaction, getRouter, getRouter, getSelfRoutingThreadpoolExecutor, getSendUdpBufferSize, getServerLogger, getServerTransactionTableSize, getSslHandshakeTimeout, getStackLogger, getTcpPostParsingThreadPoolSize, getThreadAuditor, getThreadPriority, getTimer, isAggressiveCleanup, isAlive, isCancelClientTransactionChecked, isDeliverRetransmittedAckToListener, isDeliverTerminatedEventForAck, isDeliverUnsolicitedNotify, isDialogCreated, isEventForked, isLoggingEnabled, isLoggingEnabled, isLogStackTraceOnMessageSend, isNon2XXAckPassedToListener, isRemoteTagReassignmentAllowed, isRfc2543Supported, isSslRenegotiationEnabled, isTransactionPendingAck, mapTransaction, newSIPServerRequest, newSIPServerResponse, printDialogTable, putDialog, putInMergeTable, putMergeDialog, putPendingTransaction, reInit, removeDialog, removeDialog, removeFromMergeTable, removeMergeDialog, removeMessageProcessor, removePendingTransaction, removeTransaction, removeTransactionHash, removeTransactionPendingAck, setAddressResolver, setAggressiveCleanup, setClientAuth, setDeliverDialogTerminatedEventForNullDialog, setDeliverTerminatedEventForAck, setDeliverUnsolicitedNotify, setEarlyDialogTimeout, setHostAddress, setKeepAliveTimeout, setLogRecordFactory, setLogStackTraceOnMessageSend, setMaxConnections, setMaxForkTime, setMaxTxLifetimeInvite, setMaxTxLifetimeNonInvite, setMessageFactory, setMessageParserFactory, setMessageProcessorFactory, setNon2XXAckPassedToListener, setReceiveUdpBufferSize, setReliableConnectionKeepAliveTimeout, setRouter, setSendUdpBufferSize, setSingleThreaded, setSslHandshakeTimeout, setSslRenegotiationEnabled, setStackName, setTcpPostParsingThreadPoolSize, setThreadPoolSize, setThreadPriority, setTimer, stopStack, transactionErrorEvent

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface gov.nist.javax.sip.SipStackExt

getDialogs, getJoinDialog, getLocalAddressForTcpDst, getLocalAddressForTlsDst, getReplacesDialog, setAddressResolver

Methods inherited from interface javax.sip.SipStack

getRouter

Field Detail

listeningPoints

protected Hashtable<String,ListeningPointImpl> listeningPoints

sipProviders

protected List<SipProviderImpl> sipProviders

MAX_DATAGRAM_SIZE

public static final Integer MAX_DATAGRAM_SIZE

Max datagram size.

Constructor Detail

SipStackImpl

protected SipStackImpl()

Creates a new instance of SipStackImpl.

SipStackImpl

public SipStackImpl(Properties configurationProperties)
             throws PeerUnavailableException

Constructor for the stack.

Parameters:

configurationProperties - -- stack configuration properties including NIST-specific extensions.

Throws:

PeerUnavailableException

Method Detail

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<SipProviderImpl> 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

protected void finalize()

Finalization -- stop the stack on finalization. Exit the transaction scanner and release all resources.

Overrides:

finalize in class Object

See Also:

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

getSipListener

public SipListener getSipListener()

Get the listener for the stack. A stack can have only one listener. To get an event from a provider, the listener has to be registered with the provider. The SipListener is application code.

Specified by:

getSipListener in class SIPTransactionStack

Returns:

-- the stack SipListener

getTlsSecurityPolicy

public TlsSecurityPolicy getTlsSecurityPolicy()

Get the TLS Security Policy implementation for the stack. The TlsSecurityPolicy is application code.

Returns:

-- the TLS Security Policy implementation

getLogRecordFactory

public LogRecordFactory getLogRecordFactory()

Get the message log factory registered with the stack.

Returns:

-- the messageLogFactory of the stack.

addLogAppender

@Deprecated
public void addLogAppender(org.apache.log4j.Appender appender)

Deprecated. TODO: remove this method May 11, 2010.

Set the log appender ( this is useful if you want to specify a particular log format or log to something other than a file for example). This method is will be removed May 11, 2010 or shortly there after.

Parameters:

Appender - - the log4j appender to add.

getLogger

@Deprecated
public org.apache.log4j.Logger getLogger()

Deprecated. TODO: This method will be removed May 11, 2010.

Get the log4j logger ( for log stream integration ). This method will be removed May 11, 2010 or shortly there after.

Returns:

the log4j logger.

getEventScanner

public EventScanner getEventScanner()

getAuthenticationHelper

public AuthenticationHelper getAuthenticationHelper(AccountManager accountManager,
                                           HeaderFactory headerFactory)

Description copied from interface: SipStackExt

Get the authentication helper.

Specified by:

getAuthenticationHelper in interface SipStackExt

Parameters:

accountManager - -- account manager (for fetching credentials).

headerFactory - -- header factory.

Returns:

- the authentication helper which can be used for generating the appropriate headers for handling authentication challenges for user agents.

getSecureAuthenticationHelper

public AuthenticationHelper getSecureAuthenticationHelper(SecureAccountManager accountManager,
                                                 HeaderFactory headerFactory)

Description copied from interface: SipStackExt

Get the authentication helper.

Specified by:

getSecureAuthenticationHelper in interface SipStackExt

Parameters:

accountManager - -- account manager (for fetching credentials).

headerFactory - -- header factory.

Returns:

- the authentication helper which can be used for generating the appropriate headers for handling authentication challenges for user agents.

setEnabledCipherSuites

public void setEnabledCipherSuites(String[] newCipherSuites)

Set the list of cipher suites supported by the stack. A stack can have only one set of suites. These are not validated against the supported cipher suites of the java runtime, so specifying a cipher here does not guarantee that it will work.
The stack has a default cipher suite of:

• TLS_RSA_WITH_AES_128_CBC_SHA
• SSL_RSA_WITH_3DES_EDE_CBC_SHA
• TLS_DH_anon_WITH_AES_128_CBC_SHA
• SSL_DH_anon_WITH_3DES_EDE_CBC_SHA

NOTE: This function must be called before adding a TLS listener

Specified by:

setEnabledCipherSuites in interface SipStackExt

Parameters:

String - [] The new set of ciphers to support.

getEnabledCipherSuites

public String[] getEnabledCipherSuites()

Return the currently enabled cipher suites of the Stack.

Returns:

The currently enabled cipher suites.

setEnabledProtocols

public void setEnabledProtocols(String[] newProtocols)

Set the list of protocols supported by the stack for outgoing TLS connections. A stack can have only one set of protocols. These are not validated against the supported protocols of the java runtime, so specifying a protocol here does not guarantee that it will work.
The stack has a default protocol suite of:

• TLSv1.2
• TLSv1.1
• TLSv1

NOTE: This function must be called before creating a TLSMessageChannel.

Parameters:

String - [] The new set of protocols to use for outgoing TLS connections.

getEnabledProtocols

public String[] getEnabledProtocols()

Return the currently enabled protocols to use when creating TLS connection.

Returns:

The currently enabled protocols.

setIsBackToBackUserAgent

public void setIsBackToBackUserAgent(boolean flag)

Set the "back to back User Agent" flag.

Parameters:

flag - - boolean flag to set.

isBackToBackUserAgent

public boolean isBackToBackUserAgent()

Get the "back to back User Agent" flag. return the value of the flag

isAutomaticDialogErrorHandlingEnabled

public boolean isAutomaticDialogErrorHandlingEnabled()

setTlsSecurityPolicy

public void setTlsSecurityPolicy(TlsSecurityPolicy tlsSecurityPolicy)

acquireSem

public boolean acquireSem()

releaseSem

public void releaseSem()

getConfigurationProperties

public Properties getConfigurationProperties()

Returns:

the configurationProperties

isReEntrantListener

public boolean isReEntrantListener()

Returns:

the reEntrantListener