oracle.jbo.common.ampool
Class ApplicationPoolImpl

java.lang.Object
  oracle.jbo.pool.ResourcePool
      oracle.jbo.common.ampool.ApplicationPoolImpl

All Implemented Interfaces:

ApplicationPool, java.io.Serializable

public class ApplicationPoolImpl

extends oracle.jbo.pool.ResourcePool

implements ApplicationPool

This class provides the default implementation of the ApplicationPool interface. A few notes about the locking strategy that has been employed to synchronize access to the shared application module resources in this pool. These notes are provided for the benefit of the application pool developer. They are not required to use the application pool.

The pool utilizes a singleton internal monitor object instance to synchronize read/write access to shared data.

In order to provide high pool availability, only those critical blocks that read/write from the shared data structures have been synchronized. Expensive application module operations like connect/disconnect, activiate/passivate, and rollback are performed outside of the pool lock. In order for this to work the application module is made not available inside of the pool lock before its state is modified. Using this strategy will prevent other sessions from attempting to recycle the application module instance while its state is not consistent.

This strategy of course assumes that application module access from the same session is properly synchronized. Consider the following scenario:

1. Request thread one from session one acquires a pool lock. While holding the lock the request sets the session application module as not available. Request thread one from session one then releases the pool lock and begins modifying the application module state.

2. Request thread two from session one comes along. Before the application module state has been modified by thread one above, request thread two invokes useApplicationModule. Request thread two acquires a pool lock and finds the application module instance associated with the request session (even though the application module is not available). Request thread two happily continues using the application module reference and a possible race condition between request threads one and two has occured.

In order to prevent this scenario, the pool assumes that session cookie access is also properly synchronized. This is indeed the case for the provided implementations of oracle.jbo.common.ampool.SessionCookie.

The discussion above introduces two levels of locking, session locking and pool locking. The pool's locking strategy utilizes the following rules to prevent deadlock:

1. Session locks are never acquired while pool locks are held. Please note that this rule does allow a pool lock to be acquired while a session lock is held. In fact, the pool depends upon this to prevent the race conditions mentioned above.

From an availability standpoint this rule makes sense since the rule implies that pool locks will be held for shorter duration then a session lock. However, because of the two levels of locking the application pool developer must be constantly aware of the potential for deadlock when implementing pool logic. To further understand the above rule consider the following scenario:

1. Request 1 for session 1 has acquired a pool lock without first acquiring a session lock. In the critical section the request updates some shared session state that requires a session lock to be acquired.

2. Concurrently, request 2 for session 1 acquires a session lock. In the critical section the request requires access to some shared application pool state that requires an application pool lock to be acquired.

Obviously, in the scenario above request one may be blocked waiting for the session lock that is held by request two and request two may be blocked waiting for the pool lock that is held by request one; the definition of deadlock.

Most pool methods should be accessed using a session cookie, so that the rule defined above holds true. However, there are some instances where a cookie lock could be acquired after a pool lock has been acquired:

1. When a request from session one recycles an application module that is referenced by session two. If the session two state must be passivated then the request thread from session one must update the passivation id of the session two cookie. This requires the request thread from session one to acquire a session lock for session two. It is safe to assume that a session lock for the session one has already been acquired because request one is an active request that must have accessed the pool using the session cookie API. It is not safe to assume that a session lock for session two has been acquired because the current pool request thread did not originate from session two. Attempting to acquire a session lock for session two while holding a pool lock may cause the deadlock mentioned above. This scenario is avoided by executing the section that requires the session lock for session two after the pool lock has been released.

2. When a referenced application module is removed by the high water mark functionality. This scenario is very similar to the one described in item one above. However, instead of the request thread from session one recycling an application module that is referenced by session two the request thread from session one is discarding the application module that is referenced by session two.

View definition of ApplicationPool
View Implementation of ApplicationPoolImpl

See Also:

Serialized Form

Field Summary

static int	CREATION_POLICY_ROUND_ROBIN
static int	CREATION_POLICY_SERIAL
static int	MAX_HANDLE_POLICY_ERROR
static int	MAX_HANDLE_POLICY_SPILL

Fields inherited from class oracle.jbo.pool.ResourcePool

MAX_WAIT_TIME, mLock, mLogger, WAIT_TIME_INCREMENT

Constructor Summary

ApplicationPoolImpl()
Constructor

Method Summary

void	addSessionCookie(SessionCookie cookie) Add an existing session cookie to the pool.
void	checkin(ApplicationModule appModule) Deprecated. Replaced by: SessionCookie.releaseApplicationModule(int). Application developers should invoke: SessionCookie.releaseApplicationModule(SessionCookie.SHARED_UNMANAGED_RELEASE_MODE) instead of this method. A session cookie instance may be acquired by invoking: createSessionCookie(String, String, Properties). This change was necessary to support the SessionCookie interface. Please see: SessionCookie for more information about using SessionCookies with the application pool.
java.lang.String	checkinWithSessionState(ApplicationModule appModule) Deprecated. Replaced by: SessionCookie.releaseApplicationModule(boolean, boolean). Application developers should invoke: SessionCookie.releaseApplicationModule(true, true) instead of this method. A session cookie instance may be acquired by invoking: createSessionCookie(String, String, Properties). This change was necessary to support the SessionCookie interface. Please see: SessionCookie for more information about using SessionCookies with the application pool.
ApplicationModule	checkout() Deprecated. Replaced by: ApplicationModuleRef.useApplicationModule(). Application developers should invoke: SessionCookie.useApplicationModule() instead of this method. A session cookie instance may be acquired by invoking: createSessionCookie(String, String, Properties). This change was necessary to support the SessionCookie interface. Please see: SessionCookie for more information about using SessionCookies with the application pool.
ApplicationModule	checkout(java.lang.String cookieValue) Deprecated. Replaced by: ApplicationModuleRef.useApplicationModule(). Application developers should invoke: SessionCookie.useApplicationModule() instead of this method. A session cookie instance may be acquired by invoking: createSessionCookie(String, String, Properties). This change was necessary to support the SessionCookie interface. Please see: SessionCookie for more information about using SessionCookies with the application pool.
void	commitAndSyncCache(ApplicationModule instance) Given an intitial Application Module instance, synchronizes the caches of all Application Module instances in the pool.
protected boolean	compareConnectionMetadata(ConnectionMetadata oldConnectionMetadata, ConnectionMetadata newConnectionMetadata) Invoked by the application pool implementation when an application module instance is recycled for use by a session different than the session that had previously used that instance.
protected void	connect(ApplicationModule appModule, java.util.Hashtable environment) Deprecated. Replaced by oracle.jbo.common.ampool.ConnectionStrategy#connect(ApplicationModule, SessionCookie). All extending logic that was implemented here should be implemented in a custom ConnectionStrategy class that extends DefaultConnectionStrategy.
ApplicationModule	createNewInstance() Deprecated. Replaced by ConnectionStrategy.createApplicationModule(SessionCookie, EnvInfoProvider). All extending logic that was implemented here should be implemented in a custom ConnectionStrategy class that extends: DefaultConnectionStrategy.
protected oracle.jbo.pool.ResourcePoolLogger	createPoolLogger()
SessionCookie	createSessionCookie(java.lang.String applicationId, java.lang.String sessionId, java.util.Properties properties) Create a session cookie for access to this pool.
protected void	disconnect(ApplicationModule appModule, boolean retainState, java.util.Hashtable environment) Deprecated. Replaced by ConnectionStrategy.disconnect(ApplicationModule, boolean, SessionCookie). All extending logic that was implemented here should be implemented in a custom ConnectionStrategy class that extends DefaultConnectionStrategy.
protected void	finalizeResource(java.lang.Object resource, java.lang.Object details)
java.lang.String	getApplicationModuleClass() Return the class name of the application modules being managed by the pool.
int	getAvailableInstanceCount() Returns the available number of instances in the Application Pool.
int	getAvailableNumPools() Deprecated. Replaced by getAvailableInstanceCount()
ConnectionStrategy	getConnectionStrategy() Get the application module strategy that will be used to create, connect, disconnect, and reconnect the application module.
protected java.lang.String	getConnectionStrategyClassName()
java.lang.String	getConnectString() Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be acquired from the ApplicationPool or SessionCookie environment by using the ConnectionStrategy.DB_CONNECT_STRING_PROPERTY key.
long	getCreationTimeMillis(ApplicationModule appModule) Gets the time when the app module was created (in milli-secs).
java.lang.String	getEnvConfigurationName() Return the name of the BC4J configuration that was used to initialize the pool environment.
java.util.Hashtable	getEnvironment() Returns the Hashtable that was used to initialize the Context for the application module instances.
int	getInitPoolSize() Get the initial number of application module instances which will be instantiated in the application pool.
ApplicationModule	getInstance(int index)
int	getInstanceCount() Returns the number of instances that the Application Pool has created.
protected int	getMaxAvailableSize()
protected int	getMaxInactiveAge()
int	getMaxPoolSize() Get the maximum number of application module instances which may be referenced by the application pool.
protected long	getMaxWaitTime() Determines how long a request should wait for an available application module instance when the maximum pool size has been reached.
protected int	getMinAvailableSize()
java.lang.String	getName() Returns the pool's name.
java.lang.String	getPassword() Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be acquired from the ApplicationPool or SessionCookie environment by using the Configuration.DB_PASSWORD_PROPERTY key.
java.lang.String	getPoolName() Deprecated. Replaced by getName().
protected int	getRecycleThreshold()
protected java.lang.Object	getResourceDetails(java.lang.Object resource)
protected java.lang.Object	getResourcePoolKey()
SessionCookieFactory	getSessionCookieFactory() Get the factory that will be used to create new session cookie instances.
protected java.lang.String	getSessionCookieFactoryClassName()
long	getSignature() Return a signature for the application pool.
Statistics	getStatistics() Returns the pool statistics.
long	getTimeCreated()
long	getTimeToCreateMillis(ApplicationModule appModule) Gets the time that it will tke to create the application module (in milli-secs).
protected int	getTimeToLive()
java.util.Hashtable	getUserData() Returns the User Data hashtable.
java.lang.String	getUserName() Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be acquired from the ApplicationPool or SessionCookie environment by using the Configuration.DB_USERNAME_PROPERTY key.
void	initialize()
void	initialize(java.lang.String name, java.lang.String applicationModuleClassName, java.lang.String connectString, java.util.Hashtable env) This initializes the ApplicationPool.
java.lang.Object	instantiateResource(java.util.Properties properties)
boolean	isAMPoolingEnabled()
boolean	isAvailable(ApplicationModule appModule) Deprecated. Implementation detail. This method has been made protected.
protected boolean	isDoConnectionPooling() Deprecated. This property is specific to the SessionCookie. Extending logic should be migrated to a custom extension of: SessionCookieImpl.isConnectionPoolingEnabled()
protected boolean	isDoFailover() Deprecated. This property is specific to the SessionCookie. Extending logic should be migrated to a custom extension of: SessionCookieImpl.isFailoverEnabled()
boolean	isDynamicJDBCCredentials()
protected boolean	isInstanceAlive(ApplicationModule instance) Performs tests to determine if the application module instance is still alive.
boolean	isUseExclusive()
protected void	notifyApplicationModuleReleased(ApplicationModule appModule, boolean isReleased) May be customized to perform special release processing.
protected void	reconnect(ApplicationModule appModule, java.util.Hashtable environment) Deprecated. Replaced by oracle.jbo.common.ampool.ConnectionStrategy#reconnect(ApplicationModule, SessionCookie). All extending logic that was implemented here should be implemented in a custom ConnectionStrategy class that extends DefaultConnectionStrategy.
void	releaseApplicationModule(SessionCookie cookie, boolean manageState) Mark the session's application module as available for reuse by other sessions.
void	releaseApplicationModule(SessionCookie cookie, int releaseFlags) Mark the session's application module as available for reuse by other sessions.
protected void	releaseInstance(ApplicationModule instance) Deprecated.
void	releaseInstances() Deprecated. Replaced by removeResources(). Method may be confused with releaseResource.
void	releaseResource(java.lang.Object resource, java.util.Properties properties)
protected boolean	removeFromManager()
protected boolean	removeResourceInternal(java.lang.Object resource)
com.sun.java.util.collections.ArrayList	removeResources() Remove all of the pool application module instances that have been created so far.
void	removeSessionCookie(SessionCookie cookie) Destroy a session cookie.
protected java.lang.Object	seekLRUAvailableResource(java.lang.Object refResource) Return the least recently used available resource in the pool.
protected java.lang.Object	seekMRUAvailableResource(java.lang.Object refResource) Return the most recently used available resource in the pool.
void	setAvailable(ApplicationModule appModule) This method may be used by clients if they are manually populating the pool with application module instances using #createInstance() to notify the pool when a new instance is ready for use by other threads.
void	setConnectionStrategy(ConnectionStrategy strategy) Set the application module strategy that will be used to create, connect, disconnect, and reconnect the application module.
void	setPassword(java.lang.String password) Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be set in the ApplicationPool or SessionCookie environment by using the Configuration.DB_PASSWORD_PROPERTY key.
void	setSessionCookieFactory(SessionCookieFactory sessionCookieFactory) Set the factory that will be used to create new session cookie instances.
protected boolean	setState(java.lang.Object appModule, byte state, java.util.Properties props)
void	setUserData(java.util.Hashtable userData) Replaces the userData with the new Hashtable.
void	setUserName(java.lang.String userName) Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be set in the ApplicationPool or SessionCookie environment by using the Configuration.DB_USERNAME_PROPERTY key.
ApplicationModule	useApplicationModule(SessionCookie cookie, boolean checkout) Returns an application module for the specified session cookie.
java.lang.Object	useResource(java.util.Properties properties)
boolean	validateSessionCookie(SessionCookie cookie) Validate that a session cookie is a valid handle for this pool.
boolean	validateSessionCookieInPool(SessionCookie cookie) Validate that a session cookie is a member of this pool.

Methods inherited from class oracle.jbo.pool.ResourcePool

addResource, addToRemoveList, allocateResource, createInitializer, createResource, decrementRefCount, dumpPoolStatistics, getAvailableResourceCount, getCreationTimeMillis, getInitializer, getRefCount, getResource, getResourceCount, getResourceInfo, getResourcePoolStatistics, getState, getSyncLock, getTimeToCreateMillis, incrementRefCount, initialize, isAvailable, logPoolEvent, removeResource, setAvailable, setAvailable, wakeup

Methods inherited from class java.lang.Object

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

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

dumpPoolStatistics, removeResource

Field Detail

CREATION_POLICY_SERIAL

public static int CREATION_POLICY_SERIAL

CREATION_POLICY_ROUND_ROBIN

public static int CREATION_POLICY_ROUND_ROBIN

MAX_HANDLE_POLICY_SPILL

public static int MAX_HANDLE_POLICY_SPILL

MAX_HANDLE_POLICY_ERROR

public static int MAX_HANDLE_POLICY_ERROR

Constructor Detail

ApplicationPoolImpl

public ApplicationPoolImpl()

Constructor

Method Detail

getSignature

public long getSignature()

Description copied from interface: ApplicationPool

Return a signature for the application pool.

The pool signature will also be used to determine whether a cookie is a valid handle to the pool instance. The pool signature value should be unique across pools and consistent across VMs.

Specified by:

getSignature in interface ApplicationPool

See Also:

ApplicationPool.validateSessionCookie(SessionCookie)

initialize

public void initialize()

initialize

public void initialize(java.lang.String name,
                       java.lang.String applicationModuleClassName,
                       java.lang.String connectString,
                       java.util.Hashtable env)

Description copied from interface: ApplicationPool

This initializes the ApplicationPool. The Pool name should be unique with respect to any other pools. An exception will be thrown on any errors such as duplicate pool name or mismatched information within the connectInfo parameter.

Specified by:

initialize in interface ApplicationPool

Parameters:

name - the name of the application module pool.

applicationModuleClassName - name of the application module for which the pool will be created.

connectString - the connection string to use to connect to the database.

env - name of the hash table containing the environment variables for the selected platform.

getConnectionStrategy

public ConnectionStrategy getConnectionStrategy()

Description copied from interface: ApplicationPool

Get the application module strategy that will be used to create, connect, disconnect, and reconnect the application module.

Specified by:

getConnectionStrategy in interface ApplicationPool

setConnectionStrategy

public void setConnectionStrategy(ConnectionStrategy strategy)

Description copied from interface: ApplicationPool

Set the application module strategy that will be used to create, connect, disconnect, and reconnect the application module.

Specified by:

setConnectionStrategy in interface ApplicationPool

getSessionCookieFactory

public SessionCookieFactory getSessionCookieFactory()

Description copied from interface: ApplicationPool

Get the factory that will be used to create new session cookie instances.

Specified by:

getSessionCookieFactory in interface ApplicationPool

setSessionCookieFactory

public void setSessionCookieFactory(SessionCookieFactory sessionCookieFactory)

Description copied from interface: ApplicationPool

Set the factory that will be used to create new session cookie instances.

Specified by:

setSessionCookieFactory in interface ApplicationPool

getMaxPoolSize

public int getMaxPoolSize()

Description copied from interface: ApplicationPool

Get the maximum number of application module instances which may be referenced by the application pool.

Specified by:

getMaxPoolSize in interface ApplicationPool

getInitPoolSize

public int getInitPoolSize()

Description copied from interface: ApplicationPool

Get the initial number of application module instances which will be instantiated in the application pool.

Specified by:

getInitPoolSize in interface ApplicationPool

createSessionCookie

public SessionCookie createSessionCookie(java.lang.String applicationId,
                                         java.lang.String sessionId,
                                         java.util.Properties properties)

Description copied from interface: ApplicationPool

Create a session cookie for access to this pool. Session cookies are used by the application pool to uniquely identify a pool client.

Specified by:

createSessionCookie in interface ApplicationPool

Parameters:

applicationId - an identifier which may be used to uniquely identify this cookie within the context of a session

sessionId - an option identifier which may be used to uniquely identify this cookie across sessions.

properties - an optional properties object which may be used to pass additional creation properties to the SessionCookieFactory.

addSessionCookie

public void addSessionCookie(SessionCookie cookie)

Description copied from interface: ApplicationPool

Add an existing session cookie to the pool. The session cookie must have been created by a pool instance with the same signature as this pool. This method may be used to add a de-serialized cookie to an existing pool instance.

Specified by:

addSessionCookie in interface ApplicationPool

See Also:

ApplicationPool.createSessionCookie(String, String, Properties), ApplicationPool.validateSessionCookie(SessionCookie)

removeSessionCookie

public void removeSessionCookie(SessionCookie cookie)

Description copied from interface: ApplicationPool

Destroy a session cookie.

Specified by:

removeSessionCookie in interface ApplicationPool

getApplicationModuleClass

public java.lang.String getApplicationModuleClass()

Description copied from interface: ApplicationPool

Return the class name of the application modules being managed by the pool.

Specified by:

getApplicationModuleClass in interface ApplicationPool

getConnectString

public java.lang.String getConnectString()

Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be acquired from the ApplicationPool or SessionCookie environment by using the ConnectionStrategy.DB_CONNECT_STRING_PROPERTY key.

Specified by:

getConnectString in interface ApplicationPool

Since:

9.0.2

See Also:

ConnectionStrategy, EnvInfoProvider, SessionCookie

getEnvironment

public java.util.Hashtable getEnvironment()

Description copied from interface: ApplicationPool

Returns the Hashtable that was used to initialize the Context for the application module instances.

Specified by:

getEnvironment in interface ApplicationPool

getResourceDetails

protected final java.lang.Object getResourceDetails(java.lang.Object resource)

seekLRUAvailableResource

protected final java.lang.Object seekLRUAvailableResource(java.lang.Object refResource)

Return the least recently used available resource in the pool.

Applications should not use this method.

Parameters:

refResource - if not null returns the resource that was less recently used than the reference resource.

seekMRUAvailableResource

protected final java.lang.Object seekMRUAvailableResource(java.lang.Object refResource)

Return the most recently used available resource in the pool.

Applications should not use this method.

Parameters:

refResource - if not null returns the resource that was more recently used than the reference resource.

finalizeResource

protected final void finalizeResource(java.lang.Object resource,
                                      java.lang.Object details)

checkin

public void checkin(ApplicationModule appModule)

Deprecated. Replaced by: SessionCookie.releaseApplicationModule(int).

Application developers should invoke: SessionCookie.releaseApplicationModule(SessionCookie.SHARED_UNMANAGED_RELEASE_MODE) instead of this method. A session cookie instance may be acquired by invoking: createSessionCookie(String, String, Properties).

This change was necessary to support the SessionCookie interface. Please see: SessionCookie for more information about using SessionCookies with the application pool.

Checks in an application instance that had previously been checked out. This makes the application instance avalable for subsequent checkout requests from this pool.

Specified by:

checkin in interface ApplicationPool

Parameters:

appModule - name of the application module instance to check in.

Since:

9.0.2

See Also:

SessionCookie.releaseApplicationModule(int), ApplicationModuleRef.useApplicationModule()

releaseApplicationModule

public void releaseApplicationModule(SessionCookie cookie,
                                     boolean manageState)

Description copied from interface: ApplicationPool

Mark the session's application module as available for reuse by other sessions.

If the managed flag is true then the pool will maintain logical application module state while still sharing an application module resource between sessions.

When an application module is marked available with managed state the application module will be passivated immediately if failover support has been requested (default). If failover support has been disabled, through the jbo.DoFailover system parameter, the application module will not be passivated until it is re-used by a session other than the session releasing in the application module.

Please see SessionCookie for more information regarding session identification and application state tracking.

Specified by:

releaseApplicationModule in interface ApplicationPool

Parameters:

cookie - a session cookie equal to the session cookie that was generated during checkout

manageState - indicates if the session's application module state should be managed by the pool

releaseApplicationModule

public void releaseApplicationModule(SessionCookie cookie,
                                     int releaseFlags)

Description copied from interface: ApplicationPool

Mark the session's application module as available for reuse by other sessions.

If the managed flag is true then the pool will maintain logical application module state while still sharing an application module resource between sessions.

When an application module is marked available with managed state the application module will be passivated immediately if failover support has been requested (default). If failover support has been disabled, through the jbo.DoFailover system parameter, the application module will not be passivated until it is re-used by a session other than the session releasing in the application module.

Please see SessionCookie for more information regarding session identification and application state tracking.

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

Specified by:

releaseApplicationModule in interface ApplicationPool

Parameters:

cookie - a session cookie equal to the session cookie that was generated during checkout

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_MODE

checkinWithSessionState

public java.lang.String checkinWithSessionState(ApplicationModule appModule)

Deprecated. Replaced by: SessionCookie.releaseApplicationModule(boolean, boolean).

Application developers should invoke: SessionCookie.releaseApplicationModule(true, true)

instead of this method. A session cookie instance may be acquired by invoking: createSessionCookie(String, String, Properties).

This change was necessary to support the SessionCookie interface. Please see: SessionCookie

for more information about using SessionCookies with the application pool.

Check-in the application module as being referenced by the invoking session thread.

This method should be used by pool clients that wish to maintain logical application module state while still sharing an application module resource across requests. The method returns a system generated session id for the check-in that should be used as the unique application module identifier by the client session.

The application module will be passivated immediately if failover support has been requested (default). If failover support has been disable, through the jbo.DoFailover system parameter, the application module will not be passivated until it is re-used by a session other than the session checking in the application module.

Specified by:

checkinWithSessionState in interface ApplicationPool

Parameters:

appModule - the application module that will be checked in

Since:

9.0.2

See Also:

SessionCookie.releaseApplicationModule(boolean, boolean), ApplicationModuleRef.useApplicationModule()

createNewInstance

public ApplicationModule createNewInstance()
                                    throws java.lang.Exception

Deprecated. Replaced by ConnectionStrategy.createApplicationModule(SessionCookie, EnvInfoProvider). All extending logic that was implemented here should be implemented in a custom ConnectionStrategy class that extends: DefaultConnectionStrategy.

Specified by:

createNewInstance in interface ApplicationPool

Throws:

java.lang.Exception

Since:

9.0.2

See Also:

ConnectionStrategy.createApplicationModule(SessionCookie, EnvInfoProvider)

instantiateResource

public java.lang.Object instantiateResource(java.util.Properties properties)

checkout

public ApplicationModule checkout()
                           throws java.lang.Exception

Deprecated. Replaced by: ApplicationModuleRef.useApplicationModule().

Application developers should invoke: SessionCookie.useApplicationModule()

instead of this method. A session cookie instance may be acquired by invoking: createSessionCookie(String, String, Properties).

This change was necessary to support the SessionCookie interface. Please see: SessionCookie for more information about using SessionCookies with the application pool.

Checks out stateless application instance from the pool. If the pool does not have any available instances, it will create a new instance and return it to the request thread.

Specified by:

checkout in interface ApplicationPool

Throws:

java.lang.Exception

Since:

9.0.2

See Also:

ApplicationModuleRef.useApplicationModule(), SessionCookie.releaseApplicationModule(boolean, boolean)

releaseInstances

public void releaseInstances()

Deprecated. Replaced by removeResources(). Method may be confused with releaseResource.

Specified by:

releaseInstances in interface ApplicationPool

Since:

9.0.2

See Also:

removeResources()

releaseInstance

protected void releaseInstance(ApplicationModule instance)

Deprecated.

Since:

9.0.2

See Also:

ResourcePool.removeResource(Object)

removeResourceInternal

protected boolean removeResourceInternal(java.lang.Object resource)

removeResources

public com.sun.java.util.collections.ArrayList removeResources()

Description copied from interface: ApplicationPool

Remove all of the pool application module instances that have been created so far.

The remove() method is called on the Application Modules being represented by the application instance class

Specified by:

removeResources in interface ApplicationPool

getAvailableInstanceCount

public int getAvailableInstanceCount()

Description copied from interface: ApplicationPool

Returns the available number of instances in the Application Pool.

Specified by:

getAvailableInstanceCount in interface ApplicationPool

getAvailableNumPools

public int getAvailableNumPools()

Deprecated. Replaced by getAvailableInstanceCount()

Specified by:

getAvailableNumPools in interface ApplicationPool

Since:

9.0.2

See Also:

getAvailableInstanceCount()

getInstanceCount

public int getInstanceCount()

Description copied from interface: ApplicationPool

Returns the number of instances that the Application Pool has created.

Specified by:

getInstanceCount in interface ApplicationPool

getInstance

public ApplicationModule getInstance(int index)

Specified by:

getInstance in interface ApplicationPool

checkout

public ApplicationModule checkout(java.lang.String cookieValue)

Deprecated. Replaced by: ApplicationModuleRef.useApplicationModule().

Application developers should invoke: SessionCookie.useApplicationModule()

instead of this method. A session cookie instance may be acquired by invoking: createSessionCookie(String, String, Properties).

This change was necessary to support the SessionCookie interface. Please see: SessionCookie

for more information about using SessionCookies with the application pool.

Returns an application module for the specified session. The session id must have been generated by a previous call to: checkinWithSessionState(ApplicationModule)

against this application module pool.

The session id should be used to re-create an application module state from a previous request.

If an unrecognized session id is specified then the pool should return a stateless application module instance.

Specified by:

checkout in interface ApplicationPool

Parameters:

cookieValue - a session identifier from a previous request

Since:

9.0.2

See Also:

ApplicationModuleRef.useApplicationModule(), SessionCookie.releaseApplicationModule(boolean, boolean)

useApplicationModule

public ApplicationModule useApplicationModule(SessionCookie cookie,
                                              boolean checkout)

Description copied from interface: ApplicationPool

Returns an application module for the specified session cookie. If the session has not already checked out an application module instance and the checkout flag is true then the application pool should checkout an application module instance for the specified session.

The requesting thread may obtain an application module with the state from a previous request by passing the previous request's cookie instance. The cookie should be used by the pool to re-create an application module state from a previous request.

If an "empty" session cookie is specified then the pool should return a stateless application module instance. An empty session cookie is defined as a cookie that does not reference a previous application module state. Please see SessionCookie.getPassivationId() for more information regarding application state maintenance.

In order to persist some internal state information, the application pool may mutate the specified cookie. Application pool clients should consequently be careful to reference the cookie value that is returned in the cookie value after checkout has been invoked.

Specified by:

useApplicationModule in interface ApplicationPool

Parameters:

cookie - an empty/previous session cookie

getPoolName

public java.lang.String getPoolName()

Deprecated. Replaced by getName().

Specified by:

getPoolName in interface ApplicationPool

Since:

5.0

See Also:

getName()

getName

public java.lang.String getName()

Description copied from interface: ApplicationPool

Returns the pool's name.

Specified by:

getName in interface ApplicationPool

getUserData

public java.util.Hashtable getUserData()

Description copied from interface: ApplicationPool

Returns the User Data hashtable. This is a generic container for any settings the user would like to associate with this application pool.

Specified by:

getUserData in interface ApplicationPool

setUserData

public void setUserData(java.util.Hashtable userData)

Description copied from interface: ApplicationPool

Replaces the userData with the new Hashtable.

Specified by:

setUserData in interface ApplicationPool

getUserName

public java.lang.String getUserName()

Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be acquired from the ApplicationPool or SessionCookie environment by using the Configuration.DB_USERNAME_PROPERTY key.

Returns the user name.

Specified by:

getUserName in interface ApplicationPool

Since:

9.0.2

See Also:

ConnectionStrategy, EnvInfoProvider, SessionCookie

setUserName

public void setUserName(java.lang.String userName)

Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be set in the ApplicationPool or SessionCookie environment by using the Configuration.DB_USERNAME_PROPERTY key.

Specified by:

setUserName in interface ApplicationPool

Since:

9.0.2

See Also:

ConnectionStrategy, EnvInfoProvider, SessionCookie

getPassword

public java.lang.String getPassword()

Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be acquired from the ApplicationPool or SessionCookie environment by using the Configuration.DB_PASSWORD_PROPERTY key.

Returns the password.

Specified by:

getPassword in interface ApplicationPool

Since:

9.0.2

See Also:

ConnectionStrategy, EnvInfoProvider, SessionCookie

setPassword

public void setPassword(java.lang.String password)

Deprecated. This value should be passed to the pool connection strategy as SessionCookie environment or by implementing an EnvInfoProvider. The value may be set in the ApplicationPool or SessionCookie environment by using the Configuration.DB_PASSWORD_PROPERTY key.

Specified by:

setPassword in interface ApplicationPool

Since:

9.0.2

See Also:

ConnectionStrategy, EnvInfoProvider, SessionCookie

commitAndSyncCache

public void commitAndSyncCache(ApplicationModule instance)

Description copied from interface: ApplicationPool

Given an intitial Application Module instance, synchronizes the caches of all Application Module instances in the pool.

This method commits the transaction for instance. Then, it loops through all other instances of the Application Module in the pool and synchronizes their caches with the changes committed by instance. For example:

  // Insert a new row
     row = voEmp1.createRow();

     row.setAttribute("EmpNum", new Integer(9999));
     row.setAttribute("EmpName", "NewPers");
     row.setAttribute("EmpJob", "JOBX");

     voEmp1.insertRow(row);

  // Commit the changes for the specified instance, then sync
  // them with the rest of the Application Module instances.
     pool1.commitAndSyncCache(am1);
 

Specified by:

commitAndSyncCache in interface ApplicationPool

Parameters:

instance - an instance of an Application Module in the pool.

isInstanceAlive

protected boolean isInstanceAlive(ApplicationModule instance)

Performs tests to determine if the application module instance is still alive. This is only invoked for an application module instance when it is recycled/reused. The default implementation tests the application module by invoking the remote getSession().getVersion().

This method may be overriden to provide a custom test.

validateSessionCookieInPool

public boolean validateSessionCookieInPool(SessionCookie cookie)

Description copied from interface: ApplicationPool

Validate that a session cookie is a member of this pool. A SessionCookie is a pool member if it can be used to acquire and release ApplicationModule instances from the ApplicationPool. SessionCookie(s) are automatically registered as an ApplicationPool member when they are created by that ApplicationPool with createSessionCookie(String, String, Properties). SessionCookie(s) are unregistered as an ApplicationPool member when they are removed from an an ApplicationPool with {@link #removeSessionCookie(SessionCookie)}.

Specified by:

validateSessionCookieInPool in interface ApplicationPool

validateSessionCookie

public boolean validateSessionCookie(SessionCookie cookie)

Description copied from interface: ApplicationPool

Validate that a session cookie is a valid handle for this pool. Session cookies may only access the pool from which they were created.

This method only validates that a SessionCookie was created by an ApplicationPool with the same signature as the target ApplicationPool. It is used by the default ApplicationPool implementation to verify that a SessionCookie may be added to the target pool. It does not validate that the SessionCookie is a valid member of the target ApplicationPool. Please use ApplicationPool.validateSessionCookieInPool(SessionCookie) to validate that a SessionCookie is a member of the target ApplicationPool.

Specified by:

validateSessionCookie in interface ApplicationPool

See Also:

ApplicationPool.getSignature(), ApplicationPool.validateSessionCookieInPool(SessionCookie)

notifyApplicationModuleReleased

protected void notifyApplicationModuleReleased(ApplicationModule appModule,
                                               boolean isReleased)

May be customized to perform special release processing.

Please note that this notification may be delivered while the ApplicationPool is still in an inconsistent state. A customizing pool should *not* attempt to work with the pool when handling this notification.

Customizing pools should also be careful to minimize the amount of work performed by any notification handler as this notification may be delivered while the ApplicationPool monitor is held therefore preventing other threads from using the ApplicationPool.

The notification will be delivered before the ApplicationModule is released -- though, in the case that the pool monitor is held this will not make a difference since this codepath will be single threaded.

setState

protected boolean setState(java.lang.Object appModule,
                           byte state,
                           java.util.Properties props)

setAvailable

public void setAvailable(ApplicationModule appModule)

Description copied from interface: ApplicationPool

This method may be used by clients if they are manually populating the pool with application module instances using #createInstance() to notify the pool when a new instance is ready for use by other threads. Pool clients should not use this method after an application module has been set available for the first time.

Specified by:

setAvailable in interface ApplicationPool

Parameters:

appModule - the application module which will be made available

isAvailable

public boolean isAvailable(ApplicationModule appModule)

Deprecated. Implementation detail. This method has been made protected.

Specified by:

isAvailable in interface ApplicationPool

Since:

9.0.2

getCreationTimeMillis

public long getCreationTimeMillis(ApplicationModule appModule)

Description copied from interface: ApplicationPool

Gets the time when the app module was created (in milli-secs).

Specified by:

getCreationTimeMillis in interface ApplicationPool

Parameters:

appModule - the application module instance for which you want to know the time of creation.

getTimeToCreateMillis

public long getTimeToCreateMillis(ApplicationModule appModule)

Description copied from interface: ApplicationPool

Gets the time that it will tke to create the application module (in milli-secs).

Specified by:

getTimeToCreateMillis in interface ApplicationPool

Parameters:

appModule - the application module instance for which you want to know how long it will take to create it.

getMinAvailableSize

protected int getMinAvailableSize()

getMaxAvailableSize

protected int getMaxAvailableSize()

getMaxInactiveAge

protected int getMaxInactiveAge()

getTimeToLive

protected int getTimeToLive()

getRecycleThreshold

protected int getRecycleThreshold()

createPoolLogger

protected oracle.jbo.pool.ResourcePoolLogger createPoolLogger()

getStatistics

public Statistics getStatistics()

Description copied from interface: ApplicationPool

Returns the pool statistics.

Specified by:

getStatistics in interface ApplicationPool

getMaxWaitTime

protected long getMaxWaitTime()

Determines how long a request should wait for an available application module instance when the maximum pool size has been reached. Applications may override this method to configure the wait time.

compareConnectionMetadata

protected boolean compareConnectionMetadata(ConnectionMetadata oldConnectionMetadata,
                                            ConnectionMetadata newConnectionMetadata)

Invoked by the application pool implementation when an application module instance is recycled for use by a session different than the session that had previously used that instance. The oldConnectionMetadata represents the JDBC connection metadata that was used to establish the JDBC connection for the session that previously used the application module instance. The newConnectionMetadata represents the JDBC connection metadata of the session for which the application module is being recycled. The newConnectionMetadata will be null if this is the first time that the session has acquired an application module instance from the pool.

If compareConnectionMetadata returns true then the pool assumes that the oldConnectionMetadata and the newConnectionMetadata are equal and does not attempt to connect the application module with the new session connection metadata. If compareConnectionMetadata returns false then the pool assumes that the oldConnectionMetadata and the newConnectionMetadata are note equal and will attempt to connect the application module using the new connection metadata.

If it is known at design time that the connection metadata will not change then applications may set the property, jbo.ampool.dynamicjdbccredentials, equal to false. This will prevent the potential overhead of performing a disconnect/connect whenever a new session causes the pool to recycle an application module instance.

useResource

public java.lang.Object useResource(java.util.Properties properties)

releaseResource

public void releaseResource(java.lang.Object resource,
                            java.util.Properties properties)

isDoFailover

protected boolean isDoFailover()

Deprecated. This property is specific to the SessionCookie. Extending logic should be migrated to a custom extension of: SessionCookieImpl.isFailoverEnabled()

Since:

9.0.2

See Also:

SessionCookie.isFailoverEnabled()

isDynamicJDBCCredentials

public boolean isDynamicJDBCCredentials()

isAMPoolingEnabled

public boolean isAMPoolingEnabled()

isUseExclusive

public boolean isUseExclusive()

isDoConnectionPooling

protected boolean isDoConnectionPooling()

Deprecated. This property is specific to the SessionCookie. Extending logic should be migrated to a custom extension of: SessionCookieImpl.isConnectionPoolingEnabled()

Since:

9.0.2

See Also:

SessionCookie.isConnectionPoolingEnabled()

connect

protected void connect(ApplicationModule appModule,
                       java.util.Hashtable environment)

Deprecated. Replaced by oracle.jbo.common.ampool.ConnectionStrategy#connect(ApplicationModule, SessionCookie). All extending logic that was implemented here should be implemented in a custom ConnectionStrategy class that extends DefaultConnectionStrategy.

Establish the inital application module JDBC connection. This method is invoked by the application module pool when new application module instances are instantiated. Application developers who would like to plug a custom connection framework into the application module pool may override this method.

Since:

5.0

See Also:

oracle.jbo.ConnectionStrategy#connect(ApplicationModule, SessionCookie)

reconnect

protected void reconnect(ApplicationModule appModule,
                         java.util.Hashtable environment)

Deprecated. Replaced by oracle.jbo.common.ampool.ConnectionStrategy#reconnect(ApplicationModule, SessionCookie). All extending logic that was implemented here should be implemented in a custom ConnectionStrategy class that extends DefaultConnectionStrategy.

Re-establish an application module's JDBC connection. This method is invoked by the application module pool when an application module instance is recycled by the pool. Application developers who would like to plug a custom connection framework into the application module pool may override this method.

Since:

5.0

See Also:

oracle.jbo.ConnectionStrategy#reconnect(ApplicationModule, SessionCookie)

disconnect

protected void disconnect(ApplicationModule appModule,
                          boolean retainState,
                          java.util.Hashtable environment)

Deprecated. Replaced by ConnectionStrategy.disconnect(ApplicationModule, boolean, SessionCookie). All extending logic that was implemented here should be implemented in a custom ConnectionStrategy class that extends DefaultConnectionStrategy.

Disconnect an application module from its JDBC connection. This method is invoked by the application module pool when an application module instance is checked into the pool. The method checks the application property jbo.doconnectionpooling before disconnecting the application module. Application developers who would like to plug a custom connection framework into the application module pool may override this method.

Parameters:

retainState - Indicates whether the state of the application module's caches should be retained while disconnecting. If true, the application module's Transaction should have not database state.

Since:

5.0

See Also:

oracle.jbo.ConnectionStrategy#disconnect(ApplicationModule, boolean, SessionCookie)

getConnectionStrategyClassName

protected java.lang.String getConnectionStrategyClassName()

getSessionCookieFactoryClassName

protected java.lang.String getSessionCookieFactoryClassName()

getEnvConfigurationName

public java.lang.String getEnvConfigurationName()

Description copied from interface: ApplicationPool

Return the name of the BC4J configuration that was used to initialize the pool environment. The name of the configuration will be a package qualified name. If the pool environment was not initialized by a BC4J configuration then this method will return null.

Specified by:

getEnvConfigurationName in interface ApplicationPool

getTimeCreated

public long getTimeCreated()

removeFromManager

protected boolean removeFromManager()

getResourcePoolKey

protected java.lang.Object getResourcePoolKey()