Oracle ADF Model and Business Components API Reference 10.1.2 B14022-01

oracle.jbo.common.ampool
Class ApplicationPoolImpl

java.lang.Object
  extended byoracle.jbo.pool.ResourcePool
      extended byoracle.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()

Oracle ADF Model and Business Components API Reference 10.1.2 B14022-01

 

Copyright © 1997, 2004, Oracle. All rights reserved.