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

SipApplicationSession	getApplicationSessionById(java.lang.String applicationSessionId) Returns the SipApplicationSession for a given applicationSessionId.
SipApplicationSession	getApplicationSessionByKey(java.lang.String applicationSessionKey, boolean create) Returns the SipApplicationSession for a given session applicationSessionKey.
SipSession	getCorrespondingSipSession(SipSession session, java.lang.String headerName) Returns related SipSession.

Method Detail

getApplicationSessionById

SipApplicationSession getApplicationSessionById(java.lang.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:

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

See Also:

SipApplicationSession.getId()

getApplicationSessionByKey

SipApplicationSession getApplicationSessionByKey(java.lang.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:

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

See Also:

SipFactory.createApplicationSessionByKey(String)

getCorrespondingSipSession

SipSession getCorrespondingSipSession(SipSession session,
                                      java.lang.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.