Oracle WebLogic Communications Server 10.1 API Reference

com.bea.wcp.util
Class Sessions

java.lang.Object
  com.bea.wcp.util.Sessions

All Implemented Interfaces:

com.bea.wcp.sip.SipConstants

public final class Sessions

extends java.lang.Object

implements com.bea.wcp.sip.SipConstants

A utility class for supporting converged applications having HTTP and SIP Sessions. An instance of this class is available as the ServletContext attribute "com.bea.wcp.util.Sessions" for converged applications. Several methods in this class need to lock underlying sessions (call states, strictly speaking), and that locking could possibly fail. This does not necessarily indicate an error condition, merely that the object is busy, and accessed by another thread. When a lock can not be obtained, but nothing is actually wrong, a runtime exception of type UnableToLockException is thrown.

Copyright © 2008 Oracle Corp. All Rights Reserved.

Field Summary

Fields inherited from interface com.bea.wcp.sip.SipConstants

APPSESSION_TIMEOUT_DURATION, APPSESSION_TIMEOUT_MAX, BRANCH_PREFIX, CATTR_100REL, CATTR_ATTR_DIAMETER_NODE, CATTR_FACTORY, CATTR_OUTBOUND_INTERFACES, CATTR_PATH, CATTR_PROFILE_SERVICE, CATTR_SUPPORTED, CATTR_SUPPORTEDRFCS, CATTR_TIMER, CATTR_TMPDIR, CATTR_TRACE_MESSAGE_LISTENER_FACTORY, CHARSET_UTF8, DEFAULT_ENCODING, DEFAULT_EXPIRES, DEFAULT_MAX_FORWARDS, DEFAULT_MAX_UDP_SIZE, DEFAULT_MTU_SIZE, DEFAULT_RETRY_AFTER, DEFAULT_T1, DEFAULT_T2, DEFAULT_T4, DEFAULT_TB, DEFAULT_TCP_PORT, DEFAULT_TF, DEFAULT_TLS_PORT, DEFAULT_UDP_PORT, DELIMITER, HEADER_CLUSTER_INFO, HEADER_PARAMETER_CLUSTER, HEADER_PROXY_POLICY, HEADER_SIDEWAYS_INFO_ORIG_CONN, HEADER_SIDEWAYS_INFO_RELAY_CONN, HEADER_SIDEWAYS_INFO_REQ_CERT, HEADER_SIDEWAYS_INFO_RESP_CERT, MAX_UDP_PAYLOAD_SIZE, MAX_UNSIGNED_BYTE, MAX_UNSIGNED_INT, MIN_UNSIGNED_BYTE, MIN_UNSIGNED_INT, MINUTE, MTU_HEADER_SIZE, NAP_PROTOCOL_DIAMETER, NAP_PROTOCOL_DIAMETER_SCTP, NAP_PROTOCOL_DIAMETERS, NAP_PROTOCOL_SIP, NAP_PROTOCOL_SIP_ADMIN, NAP_PROTOCOL_SIPS, REQ_X509Certificate, RESP_X509Certificate, SCTP, SESSIONS, SIP_JNDI_OBJECTS, SIP_JNDI_SIP_FACTORY, SIP_JNDI_SIP_SESSIONS_UTIL, SIP_JNDI_TIMER_SERVICE, SIP_SESSIONS_UTIL, SIP_VERSION, SUPPORTED_EXTN, TCP, TLS, UDP, UDP_PACKET_SIZE

Constructor Summary

Sessions(ServletContext servletContext)

Method Summary

HttpSession	createHttpSession() Deprecated. javax.servlet.sip.ConvergedHttpSession.getApplicationSession should be used instead.
java.lang.Object	doAction(java.lang.String applicationSessionId, WlssAction action) This method allows a way to execute a WlssAction in a transactional manner.
SipApplicationSession	getApplicationSession(HttpSession httpSession) Deprecated. javax.servlet.sip.ConvergedHttpSession.getApplicationSession() should be used instead
SipApplicationSession	getApplicationSession(java.lang.String applicationSessionId) Deprecated. javax.servlet.sip.SipSessionsUtil.getApplicationSession( String applicationSessionId) should be used instead.
SipApplicationSession	getApplicationSession(java.lang.String applicationSessionId, long timeout, java.util.concurrent.TimeUnit units) Deprecated. javax.servlet.sip.SipSessionsUtil.getApplicationSession( String applicationSessionId) should be used instead.
java.util.Iterator	getApplicationSessionsByCallId(java.lang.String callId) Deprecated. javax.servlet.sip.ConvergedHttpSession should be used instead.
java.util.Iterator	getApplicationSessionsByCallId(java.lang.String callId, long timeout, java.util.concurrent.TimeUnit units) Deprecated. javax.servlet.sip.ConvergedHttpSession should be used instead.
java.lang.String	getEncodedURL(java.lang.String url, HttpSession httpSession) Deprecated. javax.servlet.sip.ConvergedHttpSession.encodeURL(String url) should be used instead
java.lang.String	getEncodedURL(java.lang.String relativePath, java.lang.String scheme, HttpSession httpSession) Deprecated. javax.servlet.sip.ConvergedHttpSession.encodeURL(String relativePath, String scheme) should be used instead
void	removeApplicationSession(HttpSession httpSession) Deprecated. javax.servlet.sip.ConvergedHttpSession should be used instead.
void	removeApplicationSession(HttpSession httpSession, long timeout, java.util.concurrent.TimeUnit units) Deprecated. javax.servlet.sip.ConvergedHttpSession should be used instead.
void	setApplicationSession(HttpSession httpSession, SipApplicationSession sipApplicationSession) Deprecated. javax.servlet.sip.ConvergedHttpSession.getApplicationSession() should be used instead.
void	setApplicationSession(HttpSession httpSession, SipApplicationSession sipApplicationSession, long timeout, java.util.concurrent.TimeUnit units) Deprecated. javax.servlet.sip.ConvergedHttpSession.getApplicationSession() should be used instead.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Sessions

public Sessions(ServletContext servletContext)

Method Detail

createHttpSession

public HttpSession createHttpSession()

Deprecated. javax.servlet.sip.ConvergedHttpSession.getApplicationSession should be used instead.

This method creates a new HttpSession. SIP applications can then modify the session state for the newly-created HttpSession and invoke setApplicationSession to create a parent-child relationship for later use.

Returns:

new HttpSession

See Also:

setApplicationSession(javax.servlet.http.HttpSession, javax.servlet.sip.SipApplicationSession), removeApplicationSession(javax.servlet.http.HttpSession)

doAction

public java.lang.Object doAction(java.lang.String applicationSessionId,
                                 WlssAction action)
                          throws java.lang.Exception

This method allows a way to execute a WlssAction in a transactional manner. During the execution of this method, no other thread or engine tier cluster member will be allowed access to the call-state pertaining to the SipApplicationSession with applicationSessionId. When this API is used by the applications, the container guarentees that the business logic contained within the WlssAction will be executed with a lock on the SipApplicationSession instance corresponding to the applicationSessionId.

Parameters:

applicationSessionId - id of the SipApplicationSession that needs to be updated in a transactional manner.

action - WlssAction which is passed by the application

Returns:

Returns the result of the WlssAction's run method (may be null)

Throws:

java.lang.IllegalArgumentException - if applicationSessionId or action parameters were null or if callId could not be extracted from the applicationSessionId

java.lang.Exception

See Also:

WlssSipApplicationSession.doAction(com.bea.wcp.sip.WlssAction)

getApplicationSession

public SipApplicationSession getApplicationSession(HttpSession httpSession)

Deprecated. javax.servlet.sip.ConvergedHttpSession.getApplicationSession() should be used instead

Returns the SipApplicationSession if a parent-child relationship exists.

Parameters:

httpSession - child httpSession of requested ApplicationSession

Returns:

SipApplicationSession

See Also:

setApplicationSession(javax.servlet.http.HttpSession, javax.servlet.sip.SipApplicationSession), removeApplicationSession(javax.servlet.http.HttpSession)

getApplicationSession

public SipApplicationSession getApplicationSession(java.lang.String applicationSessionId)

Deprecated. javax.servlet.sip.SipSessionsUtil.getApplicationSession( String applicationSessionId) should be used instead.

Returns the SipApplicationSession for a given applicationSessionId. The applicationSessionId String is the same as that obtained through SipApplicationSession.getId().

Parameters:

applicationSessionId - the SipApplicationSession's id

Returns:

SipApplicationSession

Throws:

com.bea.wcp.sip.engine.server.UnableToLockException

See Also:

SipApplicationSession.getId()

getApplicationSession

public SipApplicationSession getApplicationSession(java.lang.String applicationSessionId,
                                                   long timeout,
                                                   java.util.concurrent.TimeUnit units)
                                                              throws com.bea.wcp.sip.engine.server.LockTimeoutException

Deprecated. javax.servlet.sip.SipSessionsUtil.getApplicationSession( String applicationSessionId) should be used instead.

Returns the SipApplicationSession for a given applicationSessionId. The applicationSessionId String is the same as that obtained through SipApplicationSession.getId().

Parameters:

applicationSessionId - the SipApplicationSession's id

timeout - how long to try to get the required lock

units - the unit for timeout -- milliseconds, presumably

Returns:

SipApplicationSession

Throws:

com.bea.wcp.sip.engine.server.LockTimeoutException - if cannot aquire lock in TimeUnit

See Also:

SipApplicationSession.getId()

getApplicationSessionsByCallId

public java.util.Iterator getApplicationSessionsByCallId(java.lang.String callId)

Deprecated. javax.servlet.sip.ConvergedHttpSession should be used instead.

Returns an Iterator over all SipApplicationSessions associated with the given callId. There can be more than one SipApplicationSession with application composition. The callId string is the same as that obtained through the SipServletRequest.getCallId() method.

Parameters:

callId - the Call-ID String

Returns:

Iterator over all SipApplicationSessions

Throws:

com.bea.wcp.sip.engine.server.UnableToLockException

See Also:

SipServletMessage.getCallId()

getApplicationSessionsByCallId

public java.util.Iterator getApplicationSessionsByCallId(java.lang.String callId,
                                                         long timeout,
                                                         java.util.concurrent.TimeUnit units)
                                                  throws com.bea.wcp.sip.engine.server.LockTimeoutException

Deprecated. javax.servlet.sip.ConvergedHttpSession should be used instead.

Returns an Iterator over all SipApplicationSessions associated with the given callId. There can be more than one SipApplicationSession with application composition. The callId string is the same as that obtained through the SipServletRequest.getCallId() method.

This method provides explicit control over locking, using the timeout and unit parameters, and the thrown LockTimeoutException exception.

Parameters:

callId - the Call-ID String

timeout - how long to try to get the required lock

units - the unit for timeout -- milliseconds, presumably

Returns:

Iterator over all SipApplicationSessions

Throws:

com.bea.wcp.sip.engine.server.LockTimeoutException - if cannot aquire lock in TimeUnit

See Also:

SipServletMessage.getCallId()

getEncodedURL

public java.lang.String getEncodedURL(java.lang.String url,
                                      HttpSession httpSession)

Deprecated. javax.servlet.sip.ConvergedHttpSession.encodeURL(String url) should be used instead

This method encodes the HTTP URL with the jsessionid. ";jsessionid=http-session-id|primary|secondary". The URL parameter should be an absolute URL. For example, http://server:7001/mywebapp/foo.jsp. Where "/mywebapp" is the context path of the the current ServletContext, because that is where the httpSession belongs to.

Parameters:

url - the HTTP url String to be encoded

httpSession - the session created using createHttpSession()

Returns:

encoded URL with jsessionid

See Also:

createHttpSession()

getEncodedURL

public java.lang.String getEncodedURL(java.lang.String relativePath,
                                      java.lang.String scheme,
                                      HttpSession httpSession)

Deprecated. javax.servlet.sip.ConvergedHttpSession.encodeURL(String relativePath, String scheme) should be used instead

Converts the given relative path to an absolute URL by prepending the contextPath for the current ServletContext, the given scheme ("http" or "https"), and the host:port, and then encoding the resulting URL with the jsessionid.

For example, this method converts:

   from: "/foo.jsp"
   to: "http://server:8888/mywebapp/foo.jsp;jsessionid=http-session-id|primary|secondary"
 

Where,

   "/mywebapp" is the contextPath for the current ServletContext
   server is the FrontendHost defined in ClusterMBean/ServerMBean.
     If missing, it defaults to the ListenAddress of the current server.
   port is  the FrontendHTTPPort/FrontendHTTPSPort (depending on
     the scheme) as defined in the ClusterMBean/ServerMBean. If missing,
     it defaults to the publicAddress of the SSL NetworkChannel
 

Parameters:

relativePath - relative to the current webapp

scheme - the scheme ("http" or "https")

httpSession - the session created using createHttpSession()

Returns:

encoded URL with jsessionid

See Also:

createHttpSession()

removeApplicationSession

public void removeApplicationSession(HttpSession httpSession)

Deprecated. javax.servlet.sip.ConvergedHttpSession should be used instead.

This method removes the specified SipApplicationSession as the parent of the given HttpSession, if it was previously designated as the parent.

Parameters:

httpSession - HttpSession

Throws:

com.bea.wcp.sip.engine.server.UnableToLockException

See Also:

setApplicationSession(javax.servlet.http.HttpSession, javax.servlet.sip.SipApplicationSession)

removeApplicationSession

public void removeApplicationSession(HttpSession httpSession,
                                     long timeout,
                                     java.util.concurrent.TimeUnit units)
                              throws com.bea.wcp.sip.engine.server.LockTimeoutException

Deprecated. javax.servlet.sip.ConvergedHttpSession should be used instead.

This method removes the specified SipApplicationSession as the parent of the given HttpSession, if it was previously designated as the parent.

Parameters:

httpSession - HttpSession

timeout - how long to try to get the required lock

units - the unit for timeout

Throws:

com.bea.wcp.sip.engine.server.LockTimeoutException - if cannot aquire lock in TimeUnit

See Also:

setApplicationSession(javax.servlet.http.HttpSession, javax.servlet.sip.SipApplicationSession)

setApplicationSession

public void setApplicationSession(HttpSession httpSession,
                                  SipApplicationSession sipApplicationSession)

Deprecated. javax.servlet.sip.ConvergedHttpSession.getApplicationSession() should be used instead.

This method sets SipApplicationSession as the parent of the specified HttpSession. The effect is that for any subsequent getSessions() method invocation on SipApplicationSession, this HttpSession is returned in the Iterator. The callId string is the same as that obtained from SipServletRequest.getCallId().

Parameters:

httpSession - HttpSession

sipApplicationSession - SipApplicationSession

Throws:

java.lang.IllegalArgumentException - if parent has been set already

com.bea.wcp.sip.engine.server.UnableToLockException

See Also:

SipServletMessage.getCallId(), removeApplicationSession(javax.servlet.http.HttpSession)

setApplicationSession

public void setApplicationSession(HttpSession httpSession,
                                  SipApplicationSession sipApplicationSession,
                                  long timeout,
                                  java.util.concurrent.TimeUnit units)
                           throws com.bea.wcp.sip.engine.server.LockTimeoutException

Deprecated. javax.servlet.sip.ConvergedHttpSession.getApplicationSession() should be used instead.

This method sets SipApplicationSession as the parent of the specified HttpSession. The effect is that for any subsequent getSessions() method invocation on SipApplicationSession, this HttpSession is returned in the Iterator. The callId string is the same as that obtained from SipServletRequest.getCallId().

This method provides explicit control over locking, using the timeout and unit parameters, and the thrown LockTimeoutException exception.

Parameters:

httpSession - HttpSession

sipApplicationSession - SipApplicationSession

timeout - how long to try to get the required lock

units - the unit for timeout

Throws:

java.lang.IllegalArgumentException - if parent has been set already

com.bea.wcp.sip.engine.server.LockTimeoutException - if cannot aquire lock in TimeUnit

See Also:

SipServletMessage.getCallId(), removeApplicationSession(javax.servlet.http.HttpSession)