oracle.jbo.common.ampool
Interface SessionCookie

All Superinterfaces:

ApplicationModuleHandle, ApplicationModuleRef, java.io.Serializable

All Known Subinterfaces:

HttpSessionCookie

All Known Implementing Classes:

SessionCookieImpl

public interface SessionCookie

extends ApplicationModuleRef

Interface for session cookies. Session cookies are used by the client side BC4J frameworks to identify unique client sessions.

The session cookie is used to uniquely identify a client session across server requests and server instances. Examples of clients include web browsers and java applications.

Session cookie equality should be determined by the application and session identifiers of the cookie. Session identifiers should be unique across all client sessions. Session identifiers should also be consistent across web servers. These requirements are necessary to support consistent session identification across web server instances.

To illustrate the usages of the session and application identifiers consider a stateful web application that is load balanced across many servlet containers. Assume that two users are accessing this application from two different browsers. Further assume that the first http request from browser one is forwarded to web server one and that the first request from browser two is forwarded be web server two.

At this point each browser session has created application state that is maintained by their respective servers. The BC4J portions of these states are represented by two session cookie instances that have been created for the two client sessions on their respective servers. These session cookies will be stored in the server session context that has been created for each browser.

Now assume that the second request from browser one is forwarded to web server two. The server load balancing implementation may copy the session context, which should include the session cookie that was created by the first request, from web server one to web server two.

Now, if the session identifiers of the browser session cookies are equal then the second request from browser one may be identified as having originated from browser two and the request could "see" the state for browser two. Among other things, this could result in security leaks (imagine that I am using an online shopping application and am suddenly shown a page that contains the credit card information of another user).

In addition to the session identifier that is described above, the session cookie also supports an application identifier. Application identifers may be used to identify unique applications. To illustrate, assume that an online shopping application must support multiple shopping carts of the same type or class for each session. One shopping cart is used to store book orders while the other is used to store cd orders. Further, in order for the application to scale, assume that it is necessary to support both applications with the same pool of application modules. In order to maintain the two application states separately the application framework must be able to distinguish between the two session applications. The session cookie uses the application id to segment the session context for multiple applications.

Developers who are implementing their own session cookies should use both the application identifier and the session identifier in order to test equality between cookies.

Finally, a session cookie value is a string representation of session application state. Because this representation may be activated in different physical sessions (if the web server crashed between requests) the cookie value should contain both the session and the passivation identifiers of the cookie. The application id a good candidate for naming the cookie because it should be unique within a given session context.

Field Summary

Type	Field
static int	NULL_PASSIVATION_ID
static boolean	SHARED
static boolean	STATE_MANAGED
static boolean	STATE_UNMANAGED
static boolean	UNSHARED

Method Summary

Type	Method
void	copyInto(SessionCookie cookie) Copies the state of this cookie into the target cookie.
boolean	equals(java.lang.Object obj)
java.lang.String	getApplicationId() Returns the application id for this session cookie.
EnvInfoProvider	getEnvInfoProvider()
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.
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.lang.String	getValue() Returns the session cookie value.
int	hashCode()
boolean	isActivationRequired() Deprecated. ApplicationDevelopers should instead override: isActivationRequired(ApplicationModule) This method will still be invoked from the new method.
boolean	isActivationRequired(ApplicationModule context) Indicates that state activation is required upon the next checkout for this session.
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.
java.lang.String	readValue(java.lang.Object source) Read the cookie value to the specified data sink.
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	resetStateInternal() INTERNAL USE ONLY.
void	setActivationRequired(boolean activateRequired) 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.
java.lang.String	toString()
void	writeValue(java.lang.Object sink) Write the cookie value to the specified data sink.

Methods inherited from interface oracle.jbo.common.ampool.ApplicationModuleRef

isApplicationModuleReserved, releaseApplicationModule, releaseApplicationModule, resetState, useApplicationModule, useApplicationModule, useApplicationModule

Methods inherited from interface oracle.jbo.ApplicationModuleHandle

getClientEnvironment, getClientEnvironment, getEnvironment, getEnvironment, getUserData

Field Detail

NULL_PASSIVATION_ID

public static final int NULL_PASSIVATION_ID

SHARED

public static final boolean SHARED

UNSHARED

public static final boolean UNSHARED

STATE_MANAGED

public static final boolean STATE_MANAGED

STATE_UNMANAGED

public static final boolean STATE_UNMANAGED

Method Detail

getApplicationId

public java.lang.String getApplicationId()

Returns the application id for this session cookie.

getSessionId

public java.lang.String getSessionId()

Returns the session identifier.

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

getValue

public java.lang.String getValue()

Returns the session cookie value.

Session cookie values represent the session application state.

getEnvInfoProvider

public EnvInfoProvider getEnvInfoProvider()

setEnvInfoProvider

public void setEnvInfoProvider(EnvInfoProvider envInfo)

writeValue

public void writeValue(java.lang.Object sink)

Write the cookie value to the specified data sink.

Parameters:

sink - a data sink

readValue

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

Read the cookie value to the specified data sink.

Parameters:

source - a data source

getPassivationId

public int getPassivationId()

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

setPassivationId

public void setPassivationId(int passivationId)

Sets the identifier for the last persisted session application state.

reservePassivationId

public void reservePassivationId()

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.

See Also:

getReservedPassivationId()

reservePassivationId

public void reservePassivationId(java.lang.Object sink)

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

See Also:

getReservedPassivationId()

getReservedPassivationId

public int getReservedPassivationId()

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.

setReservedPassivationId

public void setReservedPassivationId(int reservedPassivationId)

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

resetStateInternal

public void resetStateInternal()

INTERNAL USE ONLY. Applications should not use this method.

getPoolSignature

public long getPoolSignature()

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

setEnvironment

public void setEnvironment(java.util.Hashtable environment)

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.

setEnvironment

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

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.

getSyncLock

public java.lang.Object getSyncLock()

INTERNAL USE ONLY. Applications should not use this method.

getLastUpdate

public java.util.Date getLastUpdate()

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

copyInto

public void copyInto(SessionCookie cookie)

Copies the state of this cookie into the target cookie.

Parameters:

cookie - the target of the copy.

isFailoverEnabled

public boolean isFailoverEnabled()

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.

isConnectionPoolingEnabled

public boolean isConnectionPoolingEnabled()

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.

isResetNonTransactionalState

public 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.

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.

isActivationRequired

public boolean isActivationRequired()

Deprecated. ApplicationDevelopers should instead override:

isActivationRequired(ApplicationModule)

This method will still be invoked from the new method.

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

Since:

9.0.2

isActivationRequired

public boolean isActivationRequired(ApplicationModule context)

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.

setActivationRequired

public void setActivationRequired(boolean activateRequired)

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

setSessionCookieListener

public void setSessionCookieListener(SessionCookieListener listener)

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

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

getSSOUserName

public java.lang.String getSSOUserName()

getSSOSubscriber

public java.lang.String getSSOSubscriber()

getThreadRefCount

public int getThreadRefCount()

INTERNAL USE ONLY. Applications should not use this method.