oracle.jbo.common.ampool
Interface ApplicationModuleRef

All Superinterfaces:

ApplicationModuleHandle, java.io.Serializable

All Known Subinterfaces:

SessionCookie

All Known Implementing Classes:

RemoteCookieImpl, SessionCookieImpl

public interface ApplicationModuleRef
extends ApplicationModuleHandle

Field Summary

static boolean	SHARED
static boolean	STATE_MANAGED
static boolean	STATE_UNMANAGED
static boolean	UNSHARED

Method Summary

boolean	isApplicationModuleReserved() Tests if the application module that is referenced by this session cookie has been reserved for exclusive access by this session cookie.
void	releaseApplicationModule(boolean checkin, boolean manageState) Release an application module for reuse.
void	releaseApplicationModule(boolean checkin, boolean manageState, long waitTimeout) Release an application module for reuse.
void	resetState() Reset the ApplicationModule state associated with this ApplicationModuleRef.
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) Returns an application module instance for the current thread.

Methods inherited from interface oracle.jbo.ApplicationModuleHandle

getClientEnvironment, getClientEnvironment, getEnvironment, getEnvironment, getUserData

Field Detail

SHARED

static final boolean SHARED

See Also:

Constant Field Values

UNSHARED

static final boolean UNSHARED

See Also:

Constant Field Values

STATE_MANAGED

static final boolean STATE_MANAGED

See Also:

Constant Field Values

STATE_UNMANAGED

static final boolean STATE_UNMANAGED

See Also:

Constant Field Values

Method Detail

isApplicationModuleReserved

boolean isApplicationModuleReserved()

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

Returns:

boolean true if the referenced instance is reserved

useApplicationModule

ApplicationModule useApplicationModule()

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

Specified by:

useApplicationModule in interface ApplicationModuleHandle

See Also:

useApplicationModule(boolean, long)

useApplicationModule

ApplicationModule useApplicationModule(boolean lock)

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

Parameters:

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

See Also:

useApplicationModule(boolean, long)

useApplicationModule

ApplicationModule useApplicationModule(boolean lock,
                                       long waitTimeout)

Returns an application module instance for the current thread.

If the application session cookie references application state the application state should be activated in the returned application module.

The lock parameter may be specified to acquire a lock for the shared application module resource. If a lock is acquired the application should be careful to release that lock after it is done using the application module resource. Application thread starvation may occur if the lock is held indefinitely.

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.

Best practice would be to invoke useApplicationModule(boolean) in a try...finally block that invokes releaseApplicationModule(boolean, boolean) during finally.

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

releaseApplicationModule

void releaseApplicationModule(boolean checkin,
                              boolean manageState)

Release an application module for reuse.

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.

Parameters:

checkin - SHARED or UNSHARED

manageState - manage the session application state between requests

releaseApplicationModule

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

Release an application module for reuse.

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

I

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

resetState

void resetState()

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.