javax.servlet.sip

Interface SipSession

All Superinterfaces:

AttributeStore

public interface SipSession
extends AttributeStore

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

Nested Classes

Modifier and Type	Interface and Description
static class	SipSession.State Possible SIP dialog states from SipSession FSM.

Method Summary

Methods

Modifier and Type	Method and Description
SipServletRequest	createRequest(String method) Returns a new request object.
SipServletRequest	getActiveInvite(UAMode mode) This method returns the active invite request, if any on the session.
InviteBranch	getActiveInviteBranch() This method returns the currently active initial invite branch for the session (or null if there is no active branch).
SipServletRequest	getActiveRequest(String requestId) This method allows the application to access an active request using its requestId.
Collection<SipServletRequest>	getActiveRequests(UAMode mode) This method returns an immutable collection of currently active requests.
SipApplicationSession	getApplicationSession() Returns the application session with which this SipSession is associated.
Enumeration<String>	getAttributeNames() Deprecated. As of release 2.0, replaced by AttributeStore.getAttributeNameSet()
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.
Flow	getFlow() Returns the flow used for sending or receiving messages in this SipSession.
ForkingContext	getForkingContext() Returns the instance of ForkingContext which this SipSession is part of.
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.
SessionKeepAlive	getKeepAlive() Return the SessionKeepAlive of the session.
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.
SipServletResponse	getUnacknowledgedProvisionalResponse(String provisionalResponseId) This method returns a reliable provisional response using its id.
Collection<SipServletResponse>	getUnacknowledgedProvisionalResponses(UAMode mode) This method returns an immutable collection of unacknowledged reliable provisional responses for the session.
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	setFlow(Flow flow) Indicate that the specified flow be used while sending messages on this SipSession.
void	setHandler(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(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(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.
void	terminateDialog() Terminates the associated dialog.
void	terminateDialog(AutomaticProcessingListener listener) Terminates the associated dialog.
void	terminateProxiedDialog() Terminates a SIP dialog that has been proxied.
void	terminateProxiedDialog(AutomaticProcessingListener listener) Terminates a SIP dialog that has been proxied.
void	terminateProxiedDialog(UAMode direction) Terminates a SIP dialog that has been proxied.
void	terminateProxiedDialog(UAMode direction, AutomaticProcessingListener listener) Terminates a SIP dialog that has been proxied.

Methods inherited from interface javax.servlet.sip.AttributeStore

clearAttributes, getAttribute, getAttributeNameSet, removeAttribute, setAttribute

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

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

terminateDialog

void terminateDialog()

Terminates the associated dialog.

Throws:

IllegalStateException - If this method is called when the dialog termination has already been initiated or if the session is created by any SIP method that does not establish dialog.

Since:

2.0

terminateDialog

void terminateDialog(AutomaticProcessingListener listener)

Terminates the associated dialog. The AutomaticProcessingListener instance is used to receive all the messages sent or receives after the application calls this method.

Parameters:

listener - Instance of AutomaticProcessingListener.

Throws:

IllegalStateException - If this method is called when the dialog termination has already been initiated or if the session is created by any SIP method that does not establish a dialog.

Since:

2.0

terminateProxiedDialog

void terminateProxiedDialog()

Terminates a SIP dialog that has been proxied. This behaviour breaks RFC 3261, as a SIP proxy MUST NOT create and send requests down an established dialog. However, some 3GPP applications need this ability (see 3GPP TS 24.229 section 5.2.8.1.2 Release of an existing session). Given the way that this method breaks RFC 3261, this method should be used with caution and any application that uses it should be carefully tested. Note that the container send appropriate termination messages in both the direction of the proxy to terminate the session.

Throws:

IllegalStateException - If this method is called when the dialog termination has already been initiated or if the session is created by any SIP method that does not establish a dialog.

Since:

2.0

terminateProxiedDialog

void terminateProxiedDialog(AutomaticProcessingListener listener)

Terminates a SIP dialog that has been proxied. This behaviour breaks RFC 3261, as a SIP proxy MUST NOT create and send requests down an established dialog. However, some 3GPP applications need this ability (see 3GPP TS 24.229 section 5.2.8.1.2 Release of an existing session). Given the way that this method breaks RFC 3261, this method should be used with caution and any application that uses it should be carefully tested. Note that the container send appropriate termination messages in both the direction of the proxy to terminate the session.

Parameters:

listener - Instance of AutomaticProcessingListener.

Throws:

IllegalStateException - If this method is called when the dialog termination has already been initiated or if the session is created by any SIP method that does not establish a dialog.

Since:

2.0

terminateProxiedDialog

void terminateProxiedDialog(UAMode direction)

Terminates a SIP dialog that has been proxied. This behaviour breaks RFC 3261, as a SIP proxy MUST NOT create and send requests down an established dialog. However, some 3GPP applications need this ability (see 3GPP TS 24.229 section 5.2.8.1.2 Release of an existing session). Given the way that this method breaks RFC 3261, this method should be used with caution and any application that uses it should be carefully tested. Note that the container send appropriate termination messages in the specified direction of the proxy to terminate the session.

Parameters:

direction - the direction in which messages must be sent in order to terminate the dialog.

Throws:

IllegalStateException - If this method is called when the dialog termination has already been initiated or if the session is created by any SIP method that does not establish a dialog.

Since:

2.0

terminateProxiedDialog

void terminateProxiedDialog(UAMode direction,
                          AutomaticProcessingListener listener)

Terminates a SIP dialog that has been proxied. This behaviour breaks RFC 3261, as a SIP proxy MUST NOT create and send requests down an established dialog. However, some 3GPP applications need this ability (see 3GPP TS 24.229 section 5.2.8.1.2 Release of an existing session). Given the way that this method breaks RFC 3261, this method should be used with caution and any application that uses it should be carefully tested. Note that the container send appropriate termination messages in the specified direction of the proxy to terminate the session.

Parameters:

direction - the direction in which messages must be sent in order to terminate the dialog.

listener - Instance of AutomaticProcessingListener.

Throws:

IllegalStateException - If this method is called when the dialog termination has already been initiated or if the session is created by any SIP method that does not establish a dialog.

Since:

2.0

invalidate

void invalidate()

Invalidates this session and unbinds any objects bound to it.

Throws:

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:

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:

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:

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

getForkingContext

ForkingContext getForkingContext()

Returns the instance of ForkingContext which this SipSession is part of.

Returns:

Instance of ForkingContext

Throws:

IllegalStateException - if this method is called on an invalidated session

Since:

2.0

See Also:

ForkingContext

getCallId

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(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:

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

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

IllegalStateException - if this method is called on an invalidated session

getAttributeNames

@Deprecated
Enumeration<String> getAttributeNames()

Deprecated. As of release 2.0, replaced by AttributeStore.getAttributeNameSet()

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:

IllegalStateException - if this method is called on an invalidated session

Since:

1.1

setOutboundInterface

void setOutboundInterface(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 attributes named javax.servlet.sip.outboundAddresses and 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:

IllegalStateException - if this method is called on an invalidated session

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

NullPointerException - on null address

Since:

1.1

setOutboundInterface

void setOutboundInterface(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 attributes named javax.servlet.sip.outboundAddresses and 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:

IllegalStateException - if this method is called on an invalidated session

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

NullPointerException - on null address

Since:

1.1

setFlow

void setFlow(Flow flow)

Indicate that the specified flow be used while sending messages on this SipSession.

Parameters:

flow - Flow instance to be used while sending the messages.

Throws:

IllegalArgumentException - if the Flow does not exist or the transport association represented by the flow is broken or not known to the container.

Since:

2.0

See Also:

Flow

getFlow

Flow getFlow()

Returns the flow used for sending or receiving messages in this SipSession.

Returns:

Flow Returns the instance flow that is used for sending or receiving the message. Null, if there is no flow as per RFC 5626 is associated with this session.

Since:

2.0

See Also:

Flow

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:

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:

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

getKeepAlive

SessionKeepAlive getKeepAlive()

Return the SessionKeepAlive of the session.

Returns:

SessionKeepAlive of this session.

Since:

2.0

See Also:

SessionKeepAlive

getActiveRequest

SipServletRequest getActiveRequest(String requestId)

This method allows the application to access an active request using its requestId. A request is considered active until a final response has been sent or received. A request that is created but not sent by the application is not considered as an active request. If the referenced request is not active the method will return null.

Parameters:

requestId -

Returns:

active SipServletRequest with the specified requestId

Since:

2.0

getActiveRequests

Collection<SipServletRequest> getActiveRequests(UAMode mode)

This method returns an immutable collection of currently active requests. A request is considered active until a final response has been sent or received. A request that is created but not sent by the application is not considered as an active request. The mode parameter indicates whether incoming or outgoing requests are to be included

Parameters:

mode - Indicates whether the requests is incoming (UAS) or outgoing(UAC)

Returns:

A collection of active SipServletRequest objects with the specified mode

Since:

2.0

getActiveInvite

SipServletRequest getActiveInvite(UAMode mode)

This method returns the active invite request, if any on the session. An invite request is considered active until

• At a UAC: an ACK has been sent or an error response received
• At a UAS: an ACK has been received or an error response sent.
• At a proxy: a final response has been processed.

A request that is created but not sent by the application is not considered as an active request.

Parameters:

mode - Indicates whether the invite request is incoming (UAS) or outgoing(UAC)

Returns:

active invite request object.

Since:

2.0

getUnacknowledgedProvisionalResponse

SipServletResponse getUnacknowledgedProvisionalResponse(String provisionalResponseId)

This method returns a reliable provisional response using its id. A reliable provisional response can be obtained using this method until it is acknowledged by a PRACK.

Parameters:

provisionalResponseId - String that identifies the reliable provisional response.

Returns:

unacknowledged reliable provisional response object that matches the responseId. Null, if there are no unacknowledged provisional response matching the responseId is present.

Since:

2.0

getUnacknowledgedProvisionalResponses

Collection<SipServletResponse> getUnacknowledgedProvisionalResponses(UAMode mode)

This method returns an immutable collection of unacknowledged reliable provisional responses for the session. Reliable provisional responses can be obtained using this method until they are acknowledged by a PRACK.

Parameters:

mode - Indicates whether the mode is incoming (UAS) or outgoing(UAC)

Returns:

a collection of unacknowledged provisional responses.

Since:

2.0

getActiveInviteBranch

InviteBranch getActiveInviteBranch()

This method returns the currently active initial invite branch for the session (or null if there is no active branch). An invite branch is considered to be active from its creation until the following is true.

• At a UAC: an ACK has been sent or an error response received
• At a UAS: an ACK has been received or an error response sent.
• At a proxy: a final response has been processed.

Returns:

active InviteBranch object.

Since:

2.0