oracle.jbo.common.ampool
Class SessionCookieImpl

java.lang.Object
  |
  +--oracle.jbo.common.ampool.SessionCookieImpl

All Implemented Interfaces:

ApplicationModuleHandle, ApplicationModuleRef, java.io.Serializable, SessionCookie

Direct Known Subclasses:

HttpSessionCookieImpl

public class SessionCookieImpl

extends java.lang.Object

implements SessionCookie, java.io.Serializable

Default SessionCookie implementation.

Default session cookie instances should only be instantiated by an application pool. This is required because the default session cookie uses the application pool framework to manage application state and to share application module instances between requests. Please see ApplicationPool.createSessionCookie(String, String, Properties) for more information about creating session cookies.

The default implementation uses a session cookie lock to prevent access to the session cookie application module resource by multiple threads. A lock is obtained when a thread invokes useApplicationModule. The lock is released when the thread invokes releaseApplicationModule.

Please see SessionCookie for more information about session cookies.

See Also:

Serialized Form

Fields inherited from interface oracle.jbo.common.ampool.SessionCookie

NULL_PASSIVATION_ID, SHARED, STATE_MANAGED, STATE_UNMANAGED, UNSHARED

Constructor Summary

SessionCookieImpl(java.lang.String applicationId, java.lang.String sessionId, ApplicationPool pool)

SessionCookieImpl(java.lang.String applicationId, java.lang.String sessionId, ApplicationPool pool, java.security.Principal userPrincipal)
Constructor.

Method Summary

Type	Method
void	copyInto(SessionCookie cookie) Copies the state of this cookie into the target cookie.
boolean	equals(java.lang.Object obj) Session cookies are equal if their application and session identifiers are equal
java.lang.String	getApplicationId() Returns the application id for this session cookie.
java.util.Hashtable	getClientEnvironment() Returns a java.util.Hashtable representing the BC4J context that is related to this application session.
java.lang.Object	getClientEnvironment(java.lang.Object key) Returns the value of the specified attribute from the ApplicationModuleHandle client environment.
EnvInfoProvider	getEnvInfoProvider()
java.util.Hashtable	getEnvironment() Returns a java.util.Hashtable representing the BC4J context that is related to this application session.
java.lang.Object	getEnvironment(java.lang.Object key) Returns the value of the specified attribute from the ApplicationModuleHandle environment.
java.util.Date	getLastUpdate() Returns a date value indicating the last time the state of this cookie was updated.
int	getPassivationId() Return an identifier for the last persisted session application state.
long	getPoolSignature() Returns the signature of the pool for which this session cookie is a handle.
protected boolean	getProperty(java.lang.String name, java.util.Hashtable environment, boolean defaultValue)
int	getReservedPassivationId() Return the identifier that will be used to persist the session application state at the end of the request.
java.lang.String	getSessionId() Returns the session identifier.
java.lang.String	getSSOSubscriber()
java.lang.String	getSSOUserName()
java.lang.Object	getSyncLock() INTERNAL USE ONLY.
int	getThreadRefCount() INTERNAL USE ONLY.
java.util.Hashtable	getUserData() Returns a java.util.Hashtable which may be used to store user specific context that is related to this application session.
java.lang.String	getValue() Returns the session cookie value.
int	hashCode()
boolean	isActivationRequired() Indicates that state activation is required upon the next checkout for this session.
boolean	isActivationRequired(ApplicationModule context) Indicates that state activation is required upon the next checkout for this session.
boolean	isApplicationModuleReserved() Tests if the application module that is referenced by this session cookie has been reserved for exclusive access by this session cookie.
boolean	isConnectionPoolingEnabled() Indicates that the session application module resource's JDBC connection should be released immediately upon release to the application pool.
boolean	isFailoverEnabled() Indicates that session application module state should be persisted to secondary storage immediately upon a managed release.
boolean	isResetNonTransactionalState() Indicates whether or not the non-transactional state of the session application module resource should be preserved upon an unmanaged release to the application pool.
static int	parsePassivationId(java.lang.String cookieValue)
static java.lang.String	parseSessionId(java.lang.String cookieValue)
java.lang.String	readValue(java.lang.Object source) Read the cookie value to the specified data sink.
void	releaseApplicationModule(boolean checkin, boolean manageState) The default implementation will release the session cookie lock after having checked in the session application module.
void	releaseApplicationModule(boolean checkin, boolean manageState, long waitTimeout) The default implementation will release the session cookie lock after having checked in the session application module.
void	reservePassivationId() Reserves a unique identifier for the session application.
void	reservePassivationId(java.lang.Object sink) Reserves a unique identifier for the session application.
void	resetState() Reset the ApplicationModule state associated with this ApplicationModuleRef.
void	resetStateInternal() INTERNAL USE ONLY.
void	setActivationRequired(boolean activationRequired) May be used to force activation upon the next checkout for this session.
void	setEnvInfoProvider(EnvInfoProvider envInfo)
void	setEnvironment(java.util.Hashtable environment) Sets the session environment.
void	setEnvironment(java.lang.Object key, java.lang.Object value) Sets the session environment.
void	setPassivationId(int passivationId) Sets the identifier for the last persisted session application state.
void	setReservedPassivationId(int reservedPassivationId) Set the identifier that will be used to persist the session application state.
void	setSessionCookieListener(SessionCookieListener listener) Set a session cookie listener on the cookie.
void	setSingleThreaded(boolean isSingleThreaded) Advanced Use Only:
void	timeout() Internal use only.
java.lang.String	toString()
ApplicationModule	useApplicationModule() Returns an application module instance without acquiring a session cookie lock.
ApplicationModule	useApplicationModule(boolean lock) Returns an application module instance for the current thread.
ApplicationModule	useApplicationModule(boolean lock, long waitTimeout) The default implementation must obtain a session cookie lock before checking an application module instance out from the pool.
void	writeValue(java.lang.Object sink) Write the cookie value to the specified data sink.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SessionCookieImpl

public SessionCookieImpl(java.lang.String applicationId,
                         java.lang.String sessionId,
                         ApplicationPool pool,
                         java.security.Principal userPrincipal)

Constructor.

Applications should not invoke this constructor directly. A session cookie factory should be used instead.

The implementation requires that all three parameters be not null.

Parameters:

applicationId - a unique identifier for the session application

sessionId - a unique identifer for the session

pool - an application pool instance

timeout - the amount of time a thread should wait for an application module resource

SessionCookieImpl

public SessionCookieImpl(java.lang.String applicationId,
                         java.lang.String sessionId,
                         ApplicationPool pool)

Method Detail

getEnvInfoProvider

public EnvInfoProvider getEnvInfoProvider()

Specified by:

getEnvInfoProvider in interface SessionCookie

setEnvInfoProvider

public void setEnvInfoProvider(EnvInfoProvider envInfo)

Specified by:

setEnvInfoProvider in interface SessionCookie

getLastUpdate

public java.util.Date getLastUpdate()

Description copied from interface: SessionCookie

Returns a date value indicating the last time the state of this cookie was updated.

Specified by:

getLastUpdate in interface SessionCookie

toString

public java.lang.String toString()

Specified by:

toString in interface SessionCookie

Overrides:

toString in class java.lang.Object

hashCode

public int hashCode()

Specified by:

hashCode in interface SessionCookie

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Session cookies are equal if their application and session identifiers are equal

Specified by:

equals in interface SessionCookie

Overrides:

equals in class java.lang.Object

getPoolSignature

public long getPoolSignature()

Description copied from interface: SessionCookie

Returns the signature of the pool for which this session cookie is a handle.

Specified by:

getPoolSignature in interface SessionCookie

getApplicationId

public java.lang.String getApplicationId()

Description copied from interface: SessionCookie

Returns the application id for this session cookie.

Specified by:

getApplicationId in interface SessionCookie

getSessionId

public java.lang.String getSessionId()

Description copied from interface: SessionCookie

Returns the session identifier.

Session identifers should be uniques across sessions and consistent across servers.

Specified by:

getSessionId in interface SessionCookie

getValue

public java.lang.String getValue()

Description copied from interface: SessionCookie

Returns the session cookie value.

Session cookie values represent the session application state.

Specified by:

getValue in interface SessionCookie

getEnvironment

public java.util.Hashtable getEnvironment()

Description copied from interface: ApplicationModuleHandle

Returns a java.util.Hashtable representing the BC4J context that is related to this application session. Application developers should not modify this environment directly.

Specified by:

getEnvironment in interface ApplicationModuleHandle

getEnvironment

public java.lang.Object getEnvironment(java.lang.Object key)

Description copied from interface: ApplicationModuleHandle

Returns the value of the specified attribute from the ApplicationModuleHandle environment.

Specified by:

getEnvironment in interface ApplicationModuleHandle

getClientEnvironment

public java.util.Hashtable getClientEnvironment()

Description copied from interface: ApplicationModuleHandle

Returns a java.util.Hashtable representing the BC4J context that is related to this application session. Application developers should not modify this environment directly. The client environment differs from the environment returned by ApplicationModuleHandle.getEnvironment() in that the client environment will not be marshalled to the middle tier.

Specified by:

getClientEnvironment in interface ApplicationModuleHandle

getClientEnvironment

public java.lang.Object getClientEnvironment(java.lang.Object key)

Description copied from interface: ApplicationModuleHandle

Returns the value of the specified attribute from the ApplicationModuleHandle client environment.

Specified by:

getClientEnvironment in interface ApplicationModuleHandle

setEnvironment

public void setEnvironment(java.lang.Object key,
                           java.lang.Object value)

Description copied from interface: SessionCookie

Sets the session environment. When creating a session cookie the application pool should use this method to initialize the new session cookie instance with the default pool environment. After initializiation the developer may use this method to modify any session level application pool properties. An ApplicationPoolException will be thrown if this method is invoked after the session cookie has become active.

Specified by:

setEnvironment in interface SessionCookie

setEnvironment

public void setEnvironment(java.util.Hashtable environment)

Description copied from interface: SessionCookie

Sets the session environment. When creating a session cookie the application pool should use this method to initialize the new session cookie instance with the default pool environment. After initializiation the developer may use this method to modify any session level application pool properties. An ApplicationPoolException will be thrown if this method is invoked after the session cookie has become active.

Specified by:

setEnvironment in interface SessionCookie

isApplicationModuleReserved

public boolean isApplicationModuleReserved()

Description copied from interface: ApplicationModuleRef

Tests if the application module that is referenced by this session cookie has been reserved for exclusive access by this session cookie.

Specified by:

isApplicationModuleReserved in interface ApplicationModuleRef

Following copied from interface: oracle.jbo.common.ampool.ApplicationModuleRef

Returns:

boolean true if the referenced instance is reserved

useApplicationModule

public ApplicationModule useApplicationModule()

Description copied from interface: ApplicationModuleRef

Returns an application module instance without acquiring a session cookie lock.

Specified by:

useApplicationModule in interface ApplicationModuleRef

Following copied from interface: oracle.jbo.common.ampool.ApplicationModuleRef

See Also:

ApplicationModuleRef.useApplicationModule(boolean, long)

useApplicationModule

public ApplicationModule useApplicationModule(boolean lock)

Description copied from interface: ApplicationModuleRef

Returns an application module instance for the current thread. Uses the default waitTimeout specified by the cookie.

Specified by:

useApplicationModule in interface ApplicationModuleRef

Following copied from interface: oracle.jbo.common.ampool.ApplicationModuleRef

Parameters:

lock - specify whether a session lock should be acquired for the shared application module resource

See Also:

ApplicationModuleRef.useApplicationModule(boolean, long)

useApplicationModule

public ApplicationModule useApplicationModule(boolean lock,
                                              long waitTimeout)

The default implementation must obtain a session cookie lock before checking an application module instance out from the pool. This will prevent multi-threaded use of an application module instance for a given session.

Specified by:

useApplicationModule in interface ApplicationModuleRef

Following copied from interface: oracle.jbo.common.ampool.ApplicationModuleRef

Parameters:

lock - specify whether a session lock should be acquired for the shared application module resource

waitTimeout - specifies the amount of time in milliseconds that the thread should wait for the session cookie lock

timeout

public void timeout()

Internal use only.

releaseApplicationModule

public void releaseApplicationModule(boolean checkin,
                                     boolean manageState)

The default implementation will release the session cookie lock after having checked in the session application module. At this point any other waiting session threads may be notified.

Specified by:

releaseApplicationModule in interface ApplicationModuleRef

Following copied from interface: oracle.jbo.common.ampool.ApplicationModuleRef

Parameters:

checkin - SHARED or UNSHARED

manageState - manage the session application state between requests

releaseApplicationModule

public void releaseApplicationModule(boolean checkin,
                                     boolean manageState,
                                     long waitTimeout)

The default implementation will release the session cookie lock after having checked in the session application module. At this point any other waiting session threads may be notified.

Specified by:

releaseApplicationModule in interface ApplicationModuleRef

Following copied from interface: oracle.jbo.common.ampool.ApplicationModuleRef

Parameters:

checkin - SHARED or UNSHARED

manageState - STATE_MANAGED or STATE_UNMANAGED

waitTimeout - specifies the amount of time in milliseconds that the thread should wait for the session cookie lock

writeValue

public void writeValue(java.lang.Object sink)

Description copied from interface: SessionCookie

Write the cookie value to the specified data sink.

Specified by:

writeValue in interface SessionCookie

Following copied from interface: oracle.jbo.common.ampool.SessionCookie

Parameters:

sink - a data sink

readValue

public java.lang.String readValue(java.lang.Object source)

Description copied from interface: SessionCookie

Read the cookie value to the specified data sink.

Specified by:

readValue in interface SessionCookie

Following copied from interface: oracle.jbo.common.ampool.SessionCookie

Parameters:

source - a data source

getSyncLock

public java.lang.Object getSyncLock()

Description copied from interface: SessionCookie

INTERNAL USE ONLY. Applications should not use this method.

Specified by:

getSyncLock in interface SessionCookie

isActivationRequired

public boolean isActivationRequired()

Description copied from interface: SessionCookie

Indicates that state activation is required upon the next checkout for this session. INTERNAL USE ONLY. Applications should not use this method.

Specified by:

isActivationRequired in interface SessionCookie

isActivationRequired

public boolean isActivationRequired(ApplicationModule context)

Description copied from interface: SessionCookie

Indicates that state activation is required upon the next checkout for this session. The application module is passed to provide some context for the activation check. For example, an advanced developer could store some additional properties on the ApplicationModule to indicate whether or not it is necessary to activate that ApplicationModule.

The ApplicationModule may not yet be in a valid state so care should be taken when accessing the ApplicationModule from a custom SessionCookie implementation.

This method is invoked only if the session's affinity to its ApplicationModule was maintained between requests. The return value of this method is ignored if the session's affinity to its ApplicationModule was lost. INTERNAL USE ONLY. Applications should not use this method.

Specified by:

isActivationRequired in interface SessionCookie

setActivationRequired

public void setActivationRequired(boolean activationRequired)

Description copied from interface: SessionCookie

May be used to force activation upon the next checkout for this session. INTERNAL USE ONLY. Applications should not use this method.

Specified by:

setActivationRequired in interface SessionCookie

getPassivationId

public int getPassivationId()

Description copied from interface: SessionCookie

Return an identifier for the last persisted session application state. The passivation id should may used to activate a previous application state.

Specified by:

getPassivationId in interface SessionCookie

setPassivationId

public void setPassivationId(int passivationId)

Description copied from interface: SessionCookie

Sets the identifier for the last persisted session application state.

Specified by:

setPassivationId in interface SessionCookie

reservePassivationId

public void reservePassivationId()

Description copied from interface: SessionCookie

Reserves a unique identifier for the session application. The identifier will be used to persist the session application state if session state management has been enabled.

A passivation id should not be reserved if one has already been reserved, if the session cookie does not reference a reserved application module, or if failover is disabled.

Specified by:

reservePassivationId in interface SessionCookie

Following copied from interface: oracle.jbo.common.ampool.SessionCookie

See Also:

SessionCookie.getReservedPassivationId()

reservePassivationId

public void reservePassivationId(java.lang.Object sink)

Description copied from interface: SessionCookie

Reserves a unique identifier for the session application. The identifier will be used to persist the session application state if session state management has been enabled.

If a not null sink is passed then reservePassivationId should persist the reserved passivation id to the sink using SessionCookie.writeValue(Object).

A passivation id should not be reserved if one has already been reserved, if the session cookie does not reference a reserved application module, or if failover is disabled.

Specified by:

reservePassivationId in interface SessionCookie

Following copied from interface: oracle.jbo.common.ampool.SessionCookie

See Also:

SessionCookie.getReservedPassivationId()

getReservedPassivationId

public int getReservedPassivationId()

Description copied from interface: SessionCookie

Return the identifier that will be used to persist the session application state at the end of the request.

The next passivation id should be used when generating the session cookie value.

Specified by:

getReservedPassivationId in interface SessionCookie

setReservedPassivationId

public void setReservedPassivationId(int reservedPassivationId)

Description copied from interface: SessionCookie

Set the identifier that will be used to persist the session application state.

Specified by:

setReservedPassivationId in interface SessionCookie

getUserData

public java.util.Hashtable getUserData()

Description copied from interface: ApplicationModuleHandle

Returns a java.util.Hashtable which may be used to store user specific context that is related to this application session.

Specified by:

getUserData in interface ApplicationModuleHandle

getSSOUserName

public java.lang.String getSSOUserName()

Specified by:

getSSOUserName in interface SessionCookie

getSSOSubscriber

public java.lang.String getSSOSubscriber()

Specified by:

getSSOSubscriber in interface SessionCookie

resetState

public void resetState()

Description copied from interface: ApplicationModuleRef

Reset the ApplicationModule state associated with this ApplicationModuleRef.

Invoking this method after an ApplicationModule has been released with state management specified will result in the affinity between the ApplicationModuleRef and the ApplicationModule state being lost. Consequently, the next time invocation of useApplicationModule on this ApplicationModuleRef will return a stateless Applicationmodule.

Invoking this method on an ApplicationModuleRef which is not referencing any ApplicationModule state will have no effect. Invoking this method on an ApplicationModuleRef which is currently reserving an ApplicationModule will result in an ApplicationPoolException.

Specified by:

resetState in interface ApplicationModuleRef

resetStateInternal

public void resetStateInternal()

Description copied from interface: SessionCookie

INTERNAL USE ONLY. Applications should not use this method.

Specified by:

resetStateInternal in interface SessionCookie

copyInto

public void copyInto(SessionCookie cookie)

Description copied from interface: SessionCookie

Copies the state of this cookie into the target cookie.

Specified by:

copyInto in interface SessionCookie

Following copied from interface: oracle.jbo.common.ampool.SessionCookie

Parameters:

cookie - the target of the copy.

isFailoverEnabled

public boolean isFailoverEnabled()

Description copied from interface: SessionCookie

Indicates that session application module state should be persisted to secondary storage immediately upon a managed release.

Session cookie developers should be careful that this value not change after a session cookie has become active.

Specified by:

isFailoverEnabled in interface SessionCookie

isConnectionPoolingEnabled

public boolean isConnectionPoolingEnabled()

Description copied from interface: SessionCookie

Indicates that the session application module resource's JDBC connection should be released immediately upon release to the application pool.

Session cookie developers should be careful that this value not change after a session cookie has become active.

Specified by:

isConnectionPoolingEnabled in interface SessionCookie

isResetNonTransactionalState

public boolean isResetNonTransactionalState()

Description copied from interface: SessionCookie

Indicates whether or not the non-transactional state of the session application module resource should be preserved upon an unmanaged release to the application pool.

Transactional state includes the state of the transaction caches (EO and VO) and database state. Non-transactional state includes child view usage and application module usage instances and their related state including dynamic where clauses, order by clauses, and bind parameters. If connection pooling has been disabled for the application pool then non-transaction state will also include any cached JDBC statements.

Specified by:

isResetNonTransactionalState in interface SessionCookie

getProperty

protected boolean getProperty(java.lang.String name,
                              java.util.Hashtable environment,
                              boolean defaultValue)

setSessionCookieListener

public void setSessionCookieListener(SessionCookieListener listener)

Description copied from interface: SessionCookie

Set a session cookie listener on the cookie. INTERNAL USE ONLY. Applications should not use this method.

Specified by:

setSessionCookieListener in interface SessionCookie

parseSessionId

public static java.lang.String parseSessionId(java.lang.String cookieValue)

parsePassivationId

public static int parsePassivationId(java.lang.String cookieValue)

getThreadRefCount

public final int getThreadRefCount()

Description copied from interface: SessionCookie

INTERNAL USE ONLY. Applications should not use this method.

Specified by:

getThreadRefCount in interface SessionCookie

setSingleThreaded

public void setSingleThreaded(boolean isSingleThreaded)

Advanced Use Only:

Setting this property will force the cookie to maintain a refcount for all threads that have invoked useApplicationModule after the property has been set. Only after the last thread that has used the application module releases the application will the application module actually be returned to the pool.

The default value of this property for SessionCookieImpl instances is true.

The default value of this property for HttpSessionCookieImpl instances is false.