javax.servlet.sip

Interface SipSessionsUtil

public interface SipSessionsUtil

A utility class providing additional support for converged HTTP/SIP applications and converged Java EE / SIP applications.

This class can be accessed through the ServletContext parameter named javax.servlet.sip.SipSessionsUtil or it can be injected using the @Resource annotation.

Since:

1.1

Method Summary

Methods

Modifier and Type	Method and Description
SipApplicationSession	getApplicationSessionById(String applicationSessionId) Returns the SipApplicationSession for a given applicationSessionId.
SipApplicationSession	getApplicationSessionByKey(String applicationSessionKey, boolean create) Returns the SipApplicationSession for a given session applicationSessionKey.
SipSession	getCorrespondingSipSession(SipSession session, String headerName) Returns related SipSession.
SipApplicationSession	getCurrentApplicationSession() Returns the application session on the current thread's context.
<T> T	getManagedBean(Class<T> type, Annotation... qualifiers) Returns the CDI bean of the specified type and qualifiers in the scope of the application session of current thread.
Set<String>	getSipApplicationSessionIds() Return a Set of all Ids of the SipApplicationSession objects that belong to the application from where this method is invoked.
Set<String>	getSipApplicationSessionIds(String indexKey) Return an Set of Ids of the SipApplicationSession objects on which the specified index key was previously added using SipApplicationSession.addIndexKey method.

Method Detail

getApplicationSessionById

SipApplicationSession getApplicationSessionById(String applicationSessionId)

Returns the SipApplicationSession for a given applicationSessionId. The applicationSessionId String is the same as that obtained through SipApplicationSession.getId(). The method shall return the Application Session only if the queried application session belongs to the application from where this method is invoked. As an example if there exists a SIP Application with some Java EE component like a Message Driven Bean, bundled in the same application archive file (.war), then if the id of SipApplicationSession is known to the MDB it can get a reference to the SipApplicationSession object using this method. If this MDB were in a different application then it would not possible for it to access the SipApplicationSession. The method returns null in case the container does not find the SipApplicationSession instance matching the ID.

Parameters:

applicationSessionId - the SipApplicationSession's id

Returns:

SipApplicationSession object or a null if it is not found

Throws:

NullPointerException - if the applicationSessionId is null.

See Also:

SipApplicationSession.getId()

getApplicationSessionByKey

SipApplicationSession getApplicationSessionByKey(String applicationSessionKey,
                                               boolean create)

Returns the SipApplicationSession for a given session applicationSessionKey. The applicationSessionKey String is the same as that supplied to SipFactory#createApplicationSessionByKey. The method shall return the Application Session only if the queried application session belongs to the application from where this method is invoked. The method returns null in case the container does not find the SipApplicationSession instance matching the applicationSessionKey.

Parameters:

applicationSessionKey - session applicationSessionKey of the SipApplicationSession

create - controls whether new session should be created upon lookup failure

Returns:

SipApplicationSession object or a null if it is not found and create is set to false. If create is true, create a new SipApplicationSession with the given applicationSessionKey

Throws:

NullPointerException - if the applicationSessionKey is null.

See Also:

SipFactory.createApplicationSessionByKey(String)

getCorrespondingSipSession

SipSession getCorrespondingSipSession(SipSession session,
                                    String headerName)

Returns related SipSession. This method is helpful when the application code wants to carry out session join or replacement as described by RFC 3911 and RFC 3891 respectively.
The association is made implicitly by the container implementation. An example is shown below.

 @Resource
 SipSessionsUtil sipSessionsUtil;
 protected void doInvite(SipServletRequest req) {
   SipSession joining = req.getSession(true);
   SipSession beingJoined = sipSessionsUtil.getCorrespondingSipSession(
                            joining,"Join");
   [...]
 }
 

Parameters:

session - one of the two related SIP sessions. For example, it can be the joining session or the replacing session.

headerName - the header name through which the association is made. For example, for RFC 3911, it is Join, for RFC 3891, it is Replaces

Returns:

SipSession related to the supplied session. For RFC 3911, if joining session is passed in, the session being joined is returned. For RFC 3891, if the replacing session is passed in, the session being replaced is returned. If none is found, this method returns null.

getSipApplicationSessionIds

Set<String> getSipApplicationSessionIds(String indexKey)

Return an Set of Ids of the SipApplicationSession objects on which the specified index key was previously added using SipApplicationSession.addIndexKey method. Only the Ids of the SipApplicationSession objects belongs to the application from where this method is invoked will be returned.

Parameters:

indexKey - A string that act as the index key for retrieving the Id of the SipApplicationSession

Returns:

Set oof the Ids of the SipApplicationSession objects If there is no SipApplicationSession with the specified index key can be found, an empty Set will be returned.

Since:

2.0

getSipApplicationSessionIds

Set<String> getSipApplicationSessionIds()

Return a Set of all Ids of the SipApplicationSession objects that belong to the application from where this method is invoked.

Returns:

Set of the Ids of the SipApplicationSession objects.

Since:

2.0

getCurrentApplicationSession

SipApplicationSession getCurrentApplicationSession()

Returns the application session on the current thread's context. When executed from within a servlet, this method returns the application session of the SipServletMessage that triggered servlet invocation. When executed from a running task submitted as specified in chapter 18.3, this method will return the application session in the context of the task.

Returns:

application session of the current thread context. Null, if there is none.

Since:

2.0

getManagedBean

<T> T getManagedBean(Class<T> type,
                   Annotation... qualifiers)

Returns the CDI bean of the specified type and qualifiers in the scope of the application session of current thread. Only beans with the scope @SipApplicationSessionScoped will be returned. If no qualifiers are given default qualifier is assumed.

Type Parameters:

T - type of the bean.

Parameters:

type - Class representing the type of managed bean.

qualifiers - CDI qualifiers of the bean.

Returns:

instance of CDI managed bean or null if there is no bean matching the type

Throws:

IllegalArgumentException - if the type is not a valid bean type or if the annotations given are not qualifiers or if the same qualifier is given multiple times

Since:

2.0

See Also:

getCurrentApplicationSession()