|
Oracle Fusion Middleware Java API Reference for Oracle ADF Model 11g Release 1 (11.1.1) E10653-03 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface SessionCookie
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 | |
---|---|
static java.lang.String |
BUNDLED_EXC_MODE_KEY A user data key which may be used to set the ApplicationModule txn bundled exception mode upon next use. |
static int |
FORCE_RELEASE_MODE |
static int |
MANAGED_RELEASE_MODE |
static int |
NULL_PASSIVATION_ID |
static int |
REMOVE_RESOURCE |
static int |
RESERVED_MANAGED_RELEASE_MODE |
static int |
RESERVED_UNMANAGED_RELEASE_MODE |
static boolean |
SHARED |
static int |
SHARED_MANAGED_RELEASE_MODE |
static int |
SHARED_RELEASE_MODE |
static int |
SHARED_UNMANAGED_RELEASE_MODE |
static boolean |
STATE_MANAGED |
static boolean |
STATE_UNMANAGED |
static boolean |
UNSHARED |
static java.lang.String |
VALUE_SINK_KEY |
Method Summary | |
---|---|
void |
copyInto(SessionCookie cookie) Copies the state of this cookie into the target cookie. |
void |
destroy() Destroys the SessionCookie. |
boolean |
equals(java.lang.Object obj) |
java.lang.String |
getApplicationId() Returns the application id for this session cookie. |
java.lang.String |
getEnvConfigurationName() Return the name of the BC4J configuration that was used to initialize the SessionCookie environment. |
EnvInfoProvider |
getEnvInfoProvider() |
boolean |
getIgnorePiggyback() INTERNAL USE ONLY. |
java.lang.Object |
getInfoObject() INTERNAL USE ONLY. |
java.util.Date |
getLastUpdate() Returns a date value indicating the last time the state of this cookie was updated. |
long |
getLastUpdateLong() |
ApplicationPoolSvcMsgContext |
getMessageContext() Returns the current message context for this cookie. |
int |
getMostRecentStackId() If the current thread holds an active ApplicationModule reference then this method will delegate to ApplicationModule.getMostRecentStackId() . |
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.Object |
getUserData(java.lang.Object name) Acquires the user data associated with the specified key from the SessionCookie user data map. |
java.lang.String |
getValue() Returns the session cookie value. |
int |
hashCode() |
boolean |
isActivationRequired() Deprecated. ApplicationDevelopers should instead override:
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 |
isApplicationModuleReleased() Determines if the ApplicationModule which is referenced by this session has been released to the ApplicationPool. |
boolean |
isApplicationModuleReleasedByThread() If the cookie is multi-threaded then this method will determine if the invoking thread has released the SessionCookie ApplicationModule. |
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. |
boolean |
isWriteCookieValue() Indicates that the cookie passivation id should be written to the client. |
void |
passivateState(java.lang.Object sink) Passivates the session ApplicationModule state. |
java.lang.String |
readValue(java.lang.Object source) Read the cookie value to the specified data sink. |
void |
releaseApplicationModule(boolean checkin, boolean manageState) Deprecated. since 9.0.3 Use checkin=true, manageState=true: SHARED_MANAGED_RELEASE_MODE checkin=true, manageState=false: SHARED_UNMANAGED_RELEASE_MODE checkin=false, manageState=true: RESERVED_MANAGED_RELEASE_MODE checkin=false, manageState=false: RESERVED_UNMANAGED_RELEASE_MODE |
void |
releaseApplicationModule(boolean checkin, boolean manageState, long waitTimeout) Deprecated. since 9.0.3 use |
void |
releaseApplicationModule(int releaseFlags) Release an application module for reuse. |
void |
releaseApplicationModule(int releaseFlags, long waitTimeout) Release an application module for reuse. |
java.lang.Object |
removeUserData(java.lang.Object name) Removes the user data associated with the specified key from the SessionCookie user data map. |
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 |
setActivated(boolean activated) 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 |
setIgnorePiggyback(boolean ignorePiggyback) INTERNAL USE ONLY. |
void |
setInfoObject(java.lang.Object infoObject) INTERNAL USE ONLY. |
void |
setMessageContext(ApplicationPoolSvcMsgContext messageContext) INTERNAL USE ONLY. |
void |
setMostRecentStackId(int mostRecentStackId) INTERNAL USE ONLY. |
void |
setPassivationId(int passivationId) Sets the identifier for the last persisted session application state. |
void |
setReferenceCounting(boolean isReferenceCounting) Advanced Use Only: By default a SessionCookie may invoke ApplicationModuleRef.useApplicationModule() an arbitrary number of times with only one matching releaseApplicationModule(int) invocation. |
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 |
setUserData(java.lang.Object name, java.lang.Object value) Puts user data in the SessionCookie user data map. |
java.lang.String |
toString() |
boolean |
wasActivated() INTERANL USE ONLY. |
void |
writeValue(java.lang.Object sink) Write the cookie value to the specified data sink. |
void |
writeValue(java.lang.Object sink, java.lang.String value) Write the specified cookie value to the specified data sink. |
Methods inherited from interface oracle.jbo.common.ampool.ApplicationModuleRef |
---|
isApplicationModuleReserved, resetState, useApplicationModule, useApplicationModule, useApplicationModule |
Methods inherited from interface oracle.jbo.ApplicationModuleHandle |
---|
getClientEnvironment, getClientEnvironment, getEnvironment, getEnvironment, getUserData |
Field Detail |
---|
static final int NULL_PASSIVATION_ID
static final boolean SHARED
static final boolean UNSHARED
static final boolean STATE_MANAGED
static final boolean STATE_UNMANAGED
static final int SHARED_RELEASE_MODE
static final int MANAGED_RELEASE_MODE
static final int REMOVE_RESOURCE
static final int FORCE_RELEASE_MODE
static final int SHARED_MANAGED_RELEASE_MODE
static final int SHARED_UNMANAGED_RELEASE_MODE
static final int RESERVED_UNMANAGED_RELEASE_MODE
static final int RESERVED_MANAGED_RELEASE_MODE
static final java.lang.String BUNDLED_EXC_MODE_KEY
static final java.lang.String VALUE_SINK_KEY
Method Detail |
---|
void releaseApplicationModule(boolean checkin, boolean manageState)
Use releaseApplicationModule(int)
instead. Replace with the following flags for each checkin/manageState permutation:
checkin=true, manageState=true: SHARED_MANAGED_RELEASE_MODE checkin=true, manageState=false: SHARED_UNMANAGED_RELEASE_MODE checkin=false, manageState=true: RESERVED_MANAGED_RELEASE_MODE checkin=false, manageState=false: RESERVED_UNMANAGED_RELEASE_MODE
This method should be invoked at the end of each session request.
If another thread is holding the lock associated with the session cookie then the current thread will wait indefinitely. Please see releaseApplicationModule(boolean, boolean, long)
if a wait timeout is desired.
The checkin parameter may be used to indicate that the session application module instance should be checked in for reuse by other sessions.
The manageState parameter may be used to indicate that the session application state should be managed between requests by the pooling framework.
releaseApplicationModule
in interface ApplicationModuleRef
checkin
- SHARED or UNSHAREDmanageState
- manage the session application state between requestsvoid releaseApplicationModule(boolean checkin, boolean manageState, long waitTimeout)
use releaseApplicationModule(int, long)
instead. Replace with the following flags each checkin/manageState permutation: checkin=true, manageState=true: SHARED_MANAGED_RELEASE_MODE checkin=true, manageState=false: SHARED_UNMANAGED_RELEASE_MODE checkin=false, manageState=true: RESERVED_MANAGED_RELEASE_MODE checkin=false, manageState=false: RESERVED_UNMANAGED_RELEASE_MODE
This method should be invoked at the end of each session request.
If another thread is holding the lock associated with the session cookie then the current thread will wait for the period specified by the waitTimeout parameter. The current thread may be blocked upon invoking releaseApplicationModule if it did not acquire a session cookie lock when it dereferenced the application module with ApplicationModuleRef.useApplicationModule(boolean)
.
The checkin parameter may be used to indicate that the session application module instance should be checked in for reuse by other sessions.
The manageState parameter may be used to indicate that the session application state should be managed between requests by the pooling framework.
releaseApplicationModule
in interface ApplicationModuleRef
checkin
- SHARED or UNSHAREDmanageState
- STATE_MANAGED or STATE_UNMANAGEDwaitTimeout
- specifies the amount of time in milliseconds that the thread should wait for the session cookie lockvoid releaseApplicationModule(int releaseFlags, long waitTimeout)
This method should be invoked at the end of each session request.
If another thread is holding the lock associated with the session cookie then the current thread will wait for the period specified by the waitTimeout parameter. The current thread may be blocked upon invoking releaseApplicationModule if it did not acquire a session cookie lock when it dereferenced the application module with ApplicationModuleRef.useApplicationModule(boolean)
.
The SessionCookie supports the following release modes:
SHARED_MANAGED_RELEASE_MODE: Release the ApplicationModule for re-use by other sessions. Manage this session's ApplicationModule state.
SHARED_UNMANAGED_RELEASE_MODE: Release the ApplicationModule for re-use by other sessions. Do not manage this session's ApplicationModule state.
RESERVED_UNMANAGED_RELEASE_MODE: Do not release the ApplicationModule for re-use by other sessions. Do not manage this session's ApplicationModule state. This mode would be used if failover is not required.
RESERVED_MANAGED_RELEASE_MODE: Do not release the ApplicationModule for re-use by other sessions. Manage this session's ApplicationModule state. This mode would be used if failover is required for a reserved ApplicationModule instance.
releaseFlags
- the desired releaseFlags. Must be one of the following release modes: SHARED_MANAGED_RELEASE_MODE SHARED_UNMANAGED_RELEASE_MODE RESERVED_UNMANAGED_RELEASE_MODE RESERVED_MANAGED_RELEASE_MODEwaitTimeout
- specifies the amount of time in milliseconds that the thread should wait for the session cookie lockvoid releaseApplicationModule(int releaseFlags)
This method should be invoked at the end of each session request.
If another thread is holding the lock associated with the session cookie then the current thread will wait for the period specified by the waitTimeout parameter. The current thread may be blocked upon invoking releaseApplicationModule if it did not acquire a session cookie lock when it dereferenced the application module with ApplicationModuleRef.useApplicationModule(boolean)
.
The SessionCookie supports the following release modes:
SHARED_MANAGED_RELEASE_MODE: Release the ApplicationModule for re-use by other sessions. Manage this session's ApplicationModule state.
SHARED_UNMANAGED_RELEASE_MODE: Release the ApplicationModule for re-use by other sessions. Do not manage this session's ApplicationModule state.
RESERVED_UNMANAGED_RELEASE_MODE: Do not release the ApplicationModule for re-use by other sessions. Do not manage this session's ApplicationModule state. This mode would be used if failover is not required.
RESERVED_MANAGED_RELEASE_MODE: Do not release the ApplicationModule for re-use by other sessions. Manage this session's ApplicationModule state. This mode would be used if failover is required for a reserved ApplicationModule instance.
releaseFlags
- the desired releaseFlags. Must be one of the following release modes: SHARED_MANAGED_RELEASE_MODE SHARED_UNMANAGED_RELEASE_MODE RESERVED_UNMANAGED_RELEASE_MODE RESERVED_MANAGED_RELEASE_MODEboolean isApplicationModuleReleased()
This method differs from ApplicationModuleRef.isApplicationModuleReserved()
in that isApplicationModuleReserved will return true if an unshared or reserved release mode has been used to release an ApplicationModule.
boolean isApplicationModuleReleasedByThread()
If the SessionCookie ApplicationModule has been released then true will be returned.
If the invoking thread did not previously invoke ApplicationModuleRef.useApplicationModule()
since the last release then true will be returned.
If the cookie is single threaded then this method will return the same result as isApplicationModuleReleased()
isApplicationModuleReleased()
java.lang.String getApplicationId()
java.lang.String getSessionId()
Session identifers should be uniques across sessions and consistent across servers.
java.lang.String getValue()
Session cookie values represent the session application state.
EnvInfoProvider getEnvInfoProvider()
void setEnvInfoProvider(EnvInfoProvider envInfo)
void writeValue(java.lang.Object sink)
sink
- a data sinkvoid writeValue(java.lang.Object sink, java.lang.String value)
sink
- a data sinkjava.lang.String readValue(java.lang.Object source)
source
- a data sourceint getPassivationId()
void setPassivationId(int passivationId)
void reservePassivationId()
A passivation id should not be reserved if one has already been reserved or if failover is disabled.
getReservedPassivationId()
void reservePassivationId(java.lang.Object sink)
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 or if failover is disabled.
getReservedPassivationId()
void passivateState(java.lang.Object sink)
If a not null sink is passed then passivateState should persist the passivation id to the sink using writeValue(Object)
.
State passivation should not take place if failover is disabled.
int getReservedPassivationId()
The next passivation id should be used when generating the session cookie value.
int getMostRecentStackId()
ApplicationModule.getMostRecentStackId()
.
If the current thread does not reference a reserved ApplicationModule then this method will return a local copy of the most recent stack id.
The local copy is updated in the following circumstances:
reservePassivationId()
is invoked.getMostRecentStackId()
is invoked while the SessionCookie holds an active ApplicationModule reference.The local stack snapshot id allows SessionCookie clients to reuse persistent snapshot ids as stack snapshots. This will reduce the memory overhead of maintaining an in-memory snapshot of an ApplicationModule state. This method should only be used if failover has been enabled.
This method is really only useful for clients that have enabled failover and require the stack id after the ApplicationModule has been released. Invoking this method while an active ApplicationModule reference is held is equivalent to invoking ApplicationModule.getMostRecentStackId()
and therefore does not add any value.
void setMostRecentStackId(int mostRecentStackId)
This method is used by the pooling framework to set the local most recent stack id.
getMostRecentStackId()
void setReservedPassivationId(int reservedPassivationId)
void resetStateInternal()
long getPoolSignature()
void setEnvironment(java.util.Hashtable environment)
void setEnvironment(java.lang.Object key, java.lang.Object value)
java.lang.Object getSyncLock()
java.util.Date getLastUpdate()
long getLastUpdateLong()
void copyInto(SessionCookie cookie)
cookie
- the target of the copy.boolean isFailoverEnabled()
Session cookie developers should be careful that this value not change after a session cookie has become active.
boolean isWriteCookieValue()
Defaults to false.
boolean isConnectionPoolingEnabled()
Session cookie developers should be careful that this value not change after a session cookie has become active.
boolean isResetNonTransactionalState()
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.
boolean isActivationRequired()
isActivationRequired(ApplicationModule)
This method will still be invoked from the new method.
java.lang.String getEnvConfigurationName()
boolean isActivationRequired(ApplicationModule context)
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.
void setActivationRequired(boolean activateRequired)
void setSessionCookieListener(SessionCookieListener listener)
java.lang.String toString()
toString
in class java.lang.Object
int hashCode()
hashCode
in class java.lang.Object
boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
java.lang.String getSSOUserName()
java.lang.String getSSOSubscriber()
int getThreadRefCount()
void setReferenceCounting(boolean isReferenceCounting)
ApplicationModuleRef.useApplicationModule()
an arbitrary number of times with only one matching releaseApplicationModule(int)
invocation. The release will always result in the ApplicationModule being released to the ApplicationPool. If reference counting is enabled then the number of release invocations must match the number of use invocations and only the last release will result in the ApplicationModule being released to the ApplicationPool.void setSingleThreaded(boolean isSingleThreaded)
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 oracle.jbo.http.HttpSessionCookieImpl
instances is false.
void setUserData(java.lang.Object name, java.lang.Object value)
SessionCookie user data is automatically synched with the ApplicationModule upon ApplicationModule use.
java.lang.Object getUserData(java.lang.Object name)
java.lang.Object removeUserData(java.lang.Object name)
boolean getIgnorePiggyback()
void setIgnorePiggyback(boolean ignorePiggyback)
boolean wasActivated()
void setActivated(boolean activated)
ApplicationPoolSvcMsgContext getMessageContext()
The request represented by this message context should not be confused with the user request. The pool request represents a request from the pool to be performed by a request handler upon the poolable resource. There may be many pool requests issued during a single user request. For example, two pool requests will be required to acquire and release an ApplicationModule.
An application may access the message context during request processing in order to acquire more information about the pool request. For example, the DefaultConnectionStrategy uses the ApplicationPoolSvcMsgContext to acquire the user credentials that are to be used for connect.
void destroy()
void setMessageContext(ApplicationPoolSvcMsgContext messageContext)
java.lang.Object getInfoObject()
void setInfoObject(java.lang.Object infoObject)
getInfoObject()
.
|
Oracle Fusion Middleware Java API Reference for Oracle ADF Model 11g Release 1 (11.1.1) E10653-03 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |