javax.servlet.sip
Interface SipSession

public interface SipSession

Represents point-to-point SIP relationships. It roughly corresponds to a SIP dialog. In particular, for UAs it maintains (or is otherwise associated with) dialog state so as to be able to create subequent requests belonging to that dialog (using createRequest).

For UACs, SipSession extend the notion of SIP dialogs to have well-defined state before a dialog has been established and after a final non-2xx terminates an early dialog. This allows UACs to create "subsequent" requests without having an established dialog. The effect is that the subsequent request will have the same Call-ID, From and To headers (with the same From tag and without a To tag), the will exist in the same CSeq space.

All messages are potentially associated with a SipSession. The SipSession can be retrieved from the message by calling SipServletMessage.getSession().

Nested Class Summary

static class

SipSession.State Possible SIP dialog states from SipSession FSM.

Method Summary

SipServletRequest	createRequest(java.lang.String method) Returns a new request object.
SipApplicationSession	getApplicationSession() Returns the application session with which this SipSession is associated.
java.lang.Object	getAttribute(java.lang.String name) Returns the object bound with the specified name in this session, or null if no object is bound under the name.
java.util.Enumeration<java.lang.String>	getAttributeNames() Returns an Enumeration over the String objects containing the names of all the objects bound to this session.
java.lang.String	getCallId() Returns the Call-ID for this SipSession.
long	getCreationTime() Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT.
java.lang.String	getId() Returns a string containing the unique identifier assigned to this session.
boolean	getInvalidateWhenReady() Returns true if the container will notify the application when this SipSession is in the ready-to-invalidate state.
long	getLastAccessedTime() Returns the last time the client sent a request associated with this session, as the number of milliseconds since midnight January 1, 1970 GMT.
Address	getLocalParty() Returns the Address identifying the local party.
SipApplicationRoutingRegion	getRegion() This method allows the application to obtain the region it was invoked in for this SipSession.
Address	getRemoteParty() Returns the Address identifying the remote party.
javax.servlet.ServletContext	getServletContext() Returns the ServletContext to which this session belongs.
SipSession.State	getState() Returns the current SIP dialog state, which is one of INITIAL, EARLY, CONFIRMED, or TERMINATED.
URI	getSubscriberURI() Returns the URI of the subscriber for which this application is invoked to serve.
void	invalidate() Invalidates this session and unbinds any objects bound to it.
boolean	isReadyToInvalidate() Returns true if this session is in a ready-to-invalidate state.
boolean	isValid() Returns true if this SipSession is valid, false otherwise.
void	removeAttribute(java.lang.String name) Removes the object bound with the specified name from this session.
void	setAttribute(java.lang.String name, java.lang.Object attribute) Binds an object to this session, using the name specified.
void	setHandler(java.lang.String name) Sets the handler for this SipSession.
void	setInvalidateWhenReady(boolean invalidateWhenReady) Specifies whether the container should notify the application when the SipSession is in the ready-to-invalidate state as defined above.
void	setOutboundInterface(java.net.InetAddress address) In multi-homed environment this method can be used to select the outbound interface to use when sending requests for this SipSession.
void	setOutboundInterface(java.net.InetSocketAddress address) In multi-homed environment this method can be used to select the outbound interface and source port number to use when sending requests for this SipSession.

Method Detail

getCreationTime

long getCreationTime()

Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT.

Returns:

a long specifying when this session was created, expressed in milliseconds since 1/1/1970 GMT

getId

java.lang.String getId()

Returns a string containing the unique identifier assigned to this session. The identifier is assigned by the servlet container and is implementation dependent.

Returns:

a string specifying the identifier assigned to this session

getLastAccessedTime

long getLastAccessedTime()

Returns the last time the client sent a request associated with this session, as the number of milliseconds since midnight January 1, 1970 GMT. Actions that your application takes, such as getting or setting a value associated with the session, do not affect the access time.

Returns:

a long representing the last time the client sent a request associated with this session, expressed in milliseconds since 1/1/1970 GMT

invalidate

void invalidate()

Invalidates this session and unbinds any objects bound to it.

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

isReadyToInvalidate

boolean isReadyToInvalidate()

Returns true if this session is in a ready-to-invalidate state. A SipSession is in the ready-to-invalidate state under any of the following conditions:

1. The SipSession transitions to the TERMINATED state.
2. The SipSession transitions to the COMPLETED state when it is acting as a non-record-routing proxy.
3. The SipSession acting as a UAC transitions from the EARLY state back to the INITIAL state on account of receiving a non-2xx final response and has not initiated any new requests (does not have any pending transactions).

Returns:

true if the session is in ready-to-invalidate state, false otherwise

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

Since:

1.1

setInvalidateWhenReady

void setInvalidateWhenReady(boolean invalidateWhenReady)

Specifies whether the container should notify the application when the SipSession is in the ready-to-invalidate state as defined above. The container notifies the application using the SipSessionListener.sessionReadyToInvalidate callback.

Parameters:

invalidateWhenReady - if true, the container will observe this session and notify the application when it is in the ready-to-invalidate state. The session is not observed if the flag is false. The default is true for v1.1 applications and false for v1.0 applications.

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

Since:

1.1

See Also:

isReadyToInvalidate(), SipSessionListener.sessionReadyToInvalidate(SipSessionEvent se)

getInvalidateWhenReady

boolean getInvalidateWhenReady()

Returns true if the container will notify the application when this SipSession is in the ready-to-invalidate state.

Returns:

value of the invalidateWhenReady flag

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

Since:

1.1

See Also:

isReadyToInvalidate()

getApplicationSession

SipApplicationSession getApplicationSession()

Returns the application session with which this SipSession is associated. If none exists, then a new one is created and returned after associating it with this SipSession.

Returns:

the application session for this SipSession

getCallId

java.lang.String getCallId()

Returns the Call-ID for this SipSession. This is the value of the Call-ID header for all messages belonging to this session.

Returns:

the Call-ID for this SipSession

getLocalParty

Address getLocalParty()

Returns the Address identifying the local party. This is the value of the From header of locally initiated requests in this leg.

Returns:

address of local party

getRemoteParty

Address getRemoteParty()

Returns the Address identifying the remote party. This is the value of the To header of locally initiated requests in this leg.

createRequest

SipServletRequest createRequest(java.lang.String method)

Returns a new request object. This method is used by user agents only.

Note that this method must not be used to create ACK or CANCEL requests. User agents create ACKs by calling SipServletResponse.createAck() and CANCELs are created by calling SipServletRequest.createCancel().

Parameters:

method - the SIP method of the new request

Returns:

the new request object

Throws:

java.lang.IllegalArgumentException - if method is not a syntactically valid SIP method or if it's "ACK" or "CANCEL"

java.lang.IllegalStateException - if this SipSession has been invalidated or if this SipSession is in the INITIAL state and there is an ongoing transaction or if this SipSession is in the TERMINATED state

setHandler

void setHandler(java.lang.String name)
                throws javax.servlet.ServletException

Sets the handler for this SipSession. This method can be used to explicitly specify the name of the servlet which should handle all subsequently received messages for this SipSession. The servlet must belong to the same application (i.e. same ServletContext) as the caller.

Parameters:

name - name of the servlet to be invoked for incoming SIP messages belonging to this SipSession

Throws:

javax.servlet.ServletException - if no servlet with the specified name exists in this application

java.lang.IllegalStateException - if this method is called on an invalidated session

getAttribute

java.lang.Object getAttribute(java.lang.String name)

Returns the object bound with the specified name in this session, or null if no object is bound under the name.

Parameters:

name - a string specifying the name of the object

Returns:

the object with the specified name

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

java.lang.NullPointerException - if the name is null.

getAttributeNames

java.util.Enumeration<java.lang.String> getAttributeNames()

Returns an Enumeration over the String objects containing the names of all the objects bound to this session.

Returns:

an Enumeration over the String objects specifying the names of all the objects bound to this session

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

setAttribute

void setAttribute(java.lang.String name,
                  java.lang.Object attribute)

Binds an object to this session, using the name specified. If an object of the same name is already bound to the session, the object is replaced.

Parameters:

name - the name to which the object is bound; cannot be null

attribute - the object to be bound; cannot be null

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

java.lang.NullPointerException - on null name or attribute.

removeAttribute

void removeAttribute(java.lang.String name)

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

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

getState

SipSession.State getState()

Returns the current SIP dialog state, which is one of INITIAL, EARLY, CONFIRMED, or TERMINATED. These states are defined in RFC3261.

Returns:

the current SIP dialog state

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

Since:

1.1

setOutboundInterface

void setOutboundInterface(java.net.InetSocketAddress address)

In multi-homed environment this method can be used to select the outbound interface and source port number to use when sending requests for this SipSession. The specified address must be the address of one of the configured outbound interfaces. The set of SipURI objects which represent the supported outbound interfaces can be obtained from the servlet context attribute named javax.servlet.sip.outboundInterfaces.

The port is interpreted as an advice by the app to the container. If the port of the socket address has a non-zero value, the container will make a best-effort attempt to use it as the source port number for UDP packets, or as a source port number for TCP connections it originates. If the port is not available, the container will use its default port allocation scheme.

Invocation of this method also impacts the system headers generated by the container for this SipSession, such as the the Via and the Contact headers. The IP address part of the socket address is used to construct these system headers.

Parameters:

address - the socket address which represents the outbound interface

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

java.lang.IllegalArgumentException - if the address is not understood by the container as one of its outbound interfaces

java.lang.NullPointerException - on null address

Since:

1.1

setOutboundInterface

void setOutboundInterface(java.net.InetAddress address)

In multi-homed environment this method can be used to select the outbound interface to use when sending requests for this SipSession. The specified address must be the address of one of the configured outbound interfaces. The set of SipURI objects which represent the supported outbound interfaces can be obtained from the servlet context attribute named javax.servlet.sip.outboundInterfaces.

Invocation of this method also impacts the system headers generated by the container for this message, such as the the Via and the Contact header. The supplied IP address is used to construct these system headers.

Parameters:

address - the address which represents the outbound interface

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

java.lang.IllegalArgumentException - if the address does not represent one of the container's outbound interfaces

java.lang.NullPointerException - on null address

Since:

1.1

isValid

boolean isValid()

Returns true if this SipSession is valid, false otherwise. The SipSession can be invalidated by calling the method invalidate() on it or if its invalidateWhenReady flag is true and it transitions to the ready-to-invalidate state. Also the SipSession can be invalidated by the container when either the associated SipApplicationSession times out or SipApplicationSession.invalidate() is invoked.

Returns:

boolean true if the session is valid, false otherwise.

Since:

1.1

getRegion

SipApplicationRoutingRegion getRegion()

This method allows the application to obtain the region it was invoked in for this SipSession. This information helps the application to determine the location of the subscriber returned by SipSession.getSubscriberURI().

If this SipSession is created when this servlet receives an initial request, this method returns the region in which this servlet is invoked. The SipApplicationRoutingRegion is only available if this SipSession received an initial request. Otherwise, this method throws IllegalStateException.

Returns:

The routing region (ORIGINATING, NEUTRAL, TERMINATING or their sub-regions)

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

Since:

1.1

getSubscriberURI

URI getSubscriberURI()

Returns the URI of the subscriber for which this application is invoked to serve. This is only available if this SipSession received an initial request. Otherwise, this method throws IllegalStateException.

Returns:

URI of the subscriber

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

Since:

1.1

getServletContext

javax.servlet.ServletContext getServletContext()

Returns the ServletContext to which this session belongs. By definition, there is one ServletContext per sip (or web) module per JVM. Though, a SipSession belonging to a distributed application deployed to a distributed container may be available across JVMs , this method returns the context that is local to the JVM on which it was invoked.

Returns:

ServletContext object for the sip application

Since:

1.1

See Also:

ServletContext