SipSession

The SipSession interface represents point-to-point SIP relationships, similar to a SIP dialog. It keeps track of dialog state for User Agents (UAs) and allows them to create further requests within the same dialog using the createRequest method. For User Agent Clients (UACs), it also manages dialog-like relationships before a dialog is fully established or after a final non-2xx response ends an early dialog. This ensures that subsequent requests use the same Call-ID, From, and To headers (with the same From tag and no To tag) and stay within the same CSeq sequence. All SIP messages can be linked to a SipSession, which can be accessed through the SipServletMessage.getSession() method.

Nested class:

SipSession.State
The SipSession.State defines the possible states a SIP dialog can have according to the SipSession finite state machine (FSM). These states represent the different phases in the lifecycle of a SIP dialog, from its creation to its termination. They are used by the SipSession to track its current status and transition between states as SIP requests and responses are exchanged. For more details, refer to the Description.

Methods:

createRequest
SipServletRequest createRequest(java.lang.String method)
The method generates a new SIP request object for user agents to initiate a new SIP transaction. It cannot be used to create ACK or CANCEL requests, which must be created using the appropriate methods (SipServletResponse.createAck() or SipServletRequest.createCancel()).
Parameters:
method: The SIP method for the new request (e.g., "INVITE", "BYE", "OPTIONS").
Returns:
A new request object based on the provided method.
Exceptions:
java.lang.IllegalArgumentException is thrown if the method is not a valid SIP method (e.g., improperly formatted), either "ACK" or "CANCEL".
java.lang.IllegalStateException is thrown if:

• The SipSession has been invalidated.
• The SipSession is in the INITIAL state and there is an ongoing transaction.
• The SipSession is in the TERMINATED state.

getApplicationSession
SipApplicationSession getApplicationSession()
The method retrieves the SipApplicationSession associated with the current SipSession. If no application session exists, a new one is created, associated with this SipSession, and then returned.
Returns:
The SipApplicationSession associated with this SipSession.

getAttribute
java.lang.Object getAttribute(java.lang.String name)
The method retrieves an object bound to this SipSession using the specified name. If no object is associated with the given name, the method returns null.
Attribute names must follow the same conventions as Java package names.
Reserved attribute names starting with javax.servlet.sip.* are for internal use by the SIP Servlet API and should not be used by applications.
Parameters:
name: The name of the object to retrieve.
Returns:
The object associated with the specified name, or null if no such object exists.
Exceptions:
java.lang.IllegalStateException is thrown if the session has been invalidated.
java.lang.NullPointerException is thrown if the provided name is null.

getAttributeNames
java.util.Enumeration<java.lang.String> getAttributeNames()
The method retrieves an Enumeration of String objects that represent the names of all attributes bound to this SipSession.
If no attributes are bound to the session, the method returns an empty Enumeration.
The method provides a list of attribute names without exposing the actual attribute objects.
Attribute names starting with javax.servlet.sip.* are reserved for internal use by the SIP Servlet API and should not be used by applications.
Returns:
An Enumeration containing the names of all attributes bound to this session.
Exception:
java.lang.IllegalStateException is thrown if the session has been invalidated.

getCallId
java.lang.String getCallId()
The method retrieves the Call-ID associated with this SipSession. The Call-ID is a unique identifier for all messages that belong to the same SIP session and remains consistent throughout its lifetime. The Call-ID value is derived from the Call-ID header, which is present in all SIP messages associated with this session.
Returns:
The Call-ID of this SipSession.

getCreationTime
long getCreationTime()
The method retrieves the exact time when this SipSession was created. The time is expressed as the number of milliseconds since midnight, January 1, 1970 (GMT).
Returns:
A long value representing the session's creation time in milliseconds since January 1, 1970, GMT.

getId
java.lang.String getId()
The method retrieves the unique identifier assigned to this SipSession. This identifier is generated by the servlet container and is implementation-dependent, ensuring that each session has a distinct identifier.
Returns:
A string representing the unique identifier assigned to this session.

getInvalidateWhenReady
boolean getInvalidateWhenReady()
The method checks whether the container will notify the application when the SipSession transitions into the ready-to-invalidate state. This flag determines if the session is observed for readiness to be invalidated.
Returns:
If true, the container will notify the application when the session is ready to invalidate. If false,  the session will not be observed for readiness to invalidate.
Exception:
java.lang.IllegalStateException is thrown if the method is invoked on an invalidated session.

getLastAccessedTime
long getLastAccessedTime()
The method retrieves the timestamp of the last activity associated with this SipSession. This activity refers specifically to a client sending a request associated with the session. Actions taken within the application, such as accessing or modifying session attributes, do not update the last accessed time.
Returns:
The time of the last client request associated with this session, measured in milliseconds since midnight January 1, 1970 GMT.

getLocalParty
Address getLocalParty()
The method retrieves the Address object representing the local party in this session. This corresponds to the value of the From header in requests initiated locally within this leg of the SIP session. The returned Address provides details such as the SIP URI and any associated parameters of the local party.
Returns:
The Address identifying the local party.

getRegion
SipApplicationRoutingRegion getRegion()
The method retrieves the SipApplicationRoutingRegion in which the application was invoked for this SipSession. This information is useful for determining the location or region of the subscriber, as defined by the routing region (e.g., ORIGINATING, NEUTRAL, TERMINATING, or sub-regions).
This method only applies if the SipSession was created as a result of receiving an initial request. For sessions created from subsequent requests, this method will not provide a region.
Returns:
The routing region associated with this SipSession (e.g., ORIGINATING, NEUTRAL, TERMINATING).
Exception:
java.lang.IllegalStateException is thrown if the session is invalidated or if this method is called for a SipSession that did not receive an initial request.

getRemoteParty
Address getRemoteParty()
The method retrieves the Address identifying the remote party for this SipSession. For locally initiated requests, this corresponds to the value of the To header in this leg of the SIP communication.
Returns:
The Address object representing the remote party for this SipSession.

getServletContext
javax.servlet.ServletContext getServletContext()
The method retrieves the ServletContext associated with the SIP application that owns this SipSession. The ServletContext provides access to application-level configuration and shared resources.
For distributed applications in a distributed container, even though a SipSession may be accessible across multiple JVMs, this method returns the ServletContext local to the JVM where it is invoked.
Returns:
The ServletContext object for the SIP application associated with this SipSession.

getState
SipSession.State getState()
The method retrieves the current SIP dialog state of the SipSession. The possible states are:

• INITIAL: The session is newly created, and no messages have been exchanged.
• EARLY: A provisional response (1xx) has been sent or received, but the dialog is not yet established.
• CONFIRMED: The dialog has been successfully established (e.g., after a 200 OK response to an INVITE).
• TERMINATED: The dialog has ended.

These states are defined in RFC3261 and reflect the progression of the SIP session lifecycle.
Returns:
The current dialog state of this SipSession.
Exception:
java.lang.IllegalStateException is thrown if this method is called on a session that has been invalidated.

getSubscriberURI
URI getSubscriberURI()
The method retrieves the URI of the subscriber associated with this SipSession. This URI identifies the subscriber for whom the application is serving. It is available only if the SipSession was created as a result of receiving an initial request.
Returns:
The URI of the subscriber associated with this SipSession.
Exception: 
java.lang.IllegalStateException is thrown if the method is called on an invalidated session, or the SipSession did not receive an initial request.

invalidate
void invalidate()
The method invalidates this SipSession, rendering it unusable. Once invalidated, any objects bound to this session are unbound and the session cannot be used further.
Exception:
java.lang.IllegalStateException is thrown if this method is invoked on an already invalidated session.

isReadyToInvalidate
boolean isReadyToInvalidate()
The method determines whether the current SipSession is in a ready-to-invalidate state. The session is considered ready-to-invalidate under the following conditions:

• The SipSession transitions to the TERMINATED state.
• The SipSession transitions to the COMPLETED state while acting as a non-record-routing proxy.
• The SipSession is acting as a UAC and transitions from the EARLY state back to the INITIAL state due to receiving a non-2xx final response, provided no new requests have been initiated and no transactions are pending.

Returns:
true if the session is in a ready-to-invalidate state, false otherwise.
Exception:
java.lang.IllegalStateException is thrown if this method is invoked on an invalidated session.

isValid
boolean isValid()
The method checks whether the current SipSession is valid. A SipSession can be invalidated under the following conditions:

• The invalidate() method is explicitly called on the session.
• The invalidateWhenReady flag is true, and the session transitions to the ready-to-invalidate state.
• The session is invalidated by the container when:
• The associated SipApplicationSession times out.
• The SipApplicationSession.invalidate() method is invoked.

Returns:
true, if the SipSession is valid and false, if the SipSession is no longer valid.

removeAttribute
void removeAttribute(java.lang.String name)
The method removes the object bound with the specified name from this session. If the session does not have an object bound with the specified name, this method does nothing.
Parameters:
name: the name of the object to remove from this session
Exception:
java.lang.IllegalStateException is thrown if this method is called on an invalidated session

setAttribute
void setAttribute(java.lang.String name,
                  java.lang.Object attribute)
The method binds an object to this SipSession under the specified name. If an object with the same name is already bound, it will be replaced with the new object. This method allows applications to store session-specific data in the SipSession.
Parameters:
name: A non-null string specifying the name under which the object is bound.
attribute: A non-null object to be bound to the session.
Exceptions:
java.lang.IllegalStateException is thrown if the SipSession has been invalidated.
java.lang.NullPointerException is thrown if either the name or attribute is null.

setHandler
void setHandler(java.lang.String name)
                throws javax.servlet.ServletException
The method sets the handler for this SipSession. This method specifies the name of the servlet that will handle all subsequent SIP messages received for this SipSession. The specified servlet must belong to the same SIP application (i.e., the same ServletContext) as the caller.
Parameters:
name: A string representing the name of the servlet that should handle incoming SIP messages for this SipSession.
Exceptions:
javax.servlet.ServletException is thrown if no servlet with the specified name exists in the current SIP application.
java.lang.IllegalStateException is thrown if this method is called on an invalidated session.

setInvalidateWhenReady
void setInvalidateWhenReady(boolean invalidateWhenReady)
The method specifies whether the SIP container should notify the application when the SipSession transitions to the ready-to-invalidate state. If set to true, the container observes the session and notifies the application using the SipSessionListener.sessionReadyToInvalidate callback when the session reaches the ready-to-invalidate state.
Parameters:
invalidateWhenReady: if true, the container observes this session and notifies the application when it reaches the ready-to-invalidate state. If false, the container does not observe this session.
Default value is:
true for SIP Servlet API v1.1 applications.
false for SIP Servlet API v1.0 applications.
Exception:
java.lang.IllegalStateException is thrown if this method is called on an invalidated session.

setOutboundInterface
void setOutboundInterface(java.net.InetAddress address)
This method is used in a multi-homed environment to select the outbound network interface for sending requests associated with this SipSession. The specified IP address must match one of the configured outbound interfaces in the container. This selection influences the system headers generated by the container (e.g., Via and Contact).
The list of supported outbound interfaces can be retrieved from the servlet context attribute javax.servlet.sip.outboundInterfaces.
Parameters:
address: A java.net.InetAddress object representing the outbound interface to be used. The address must match one of the configured outbound interfaces available in the container.
Exceptions:
java.lang.IllegalStateException is thrown if this method is called on an invalidated session.
java.lang.IllegalArgumentException is thrown if the specified address is not one of the container's configured outbound interfaces.
java.lang.NullPointerException is thrown if the address parameter is null.

setOutboundInterface
void setOutboundInterface(java.net.InetSocketAddress address)
This method allows the application to specify both the outbound network interface and the source port for sending requests in a multi-homed environment. The specified InetSocketAddress must represent one of the container's configured outbound interfaces. The container will make a best-effort attempt to use the provided port if it is non-zero. If the specified port is unavailable, the container will use its default port allocation scheme.
The chosen interface and port affect the system headers generated by the container for this SipSession (e.g., Via and Contact). The IP address of the provided socket address is used to construct these headers.
The list of supported outbound interfaces can be retrieved from the servlet context attribute javax.servlet.sip.outboundInterfaces.
The container interprets the port as an advisory value and may not always guarantee its use.
Parameters:
address: A java.net.InetSocketAddress object representing the outbound interface and source port. The IP address part must match one of the configured outbound interfaces.
Exceptions:
java.lang.IllegalStateException is thrown if this method is called on an invalidated session.
java.lang.IllegalArgumentException is thrown if the specified address is not one of the container's configured outbound interfaces.
java.lang.NullPointerException is thrown if the address parameter is null.