Business Components

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
TypeField
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, WAIT_TIME_INCREMENT
 
Constructor Summary
ApplicationPoolImpl()
          Constructor
 
Method Summary
TypeMethod
 void addSessionCookie(SessionCookie cookie)
          Add an existing session cookie to the pool.
 void checkin(ApplicationModule appModule)
          Checks in an application instance that had previously been checked out.
 java.lang.String checkinWithSessionState(ApplicationModule appModule)
          Check-in the application module as being referenced by the invoking session thread.
 ApplicationModule checkout()
          Checks out stateless application instance from the pool.
 ApplicationModule checkout(java.lang.String cookieValue)
          Returns an application module for the specified session.
 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 cookieValue, 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)
          Invoked during pool high water mark resolution.
 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. Please see (@link oracle.jbo.common.ampool.DefaultConnectionStrategy} for more information.
 long getCreationTimeMillis(ApplicationModule appModule)
          Gets the time when the app module was created (in milli-secs).
 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()
          Return the maximum number of available instances that should exist in the pool after pool garbage collection.
protected  int getMaxInactiveAge()
          Return the duration in milliseconds that a resource may remain available before it is considered inactive.
 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()
          Return the minimum number of available instances that should exist in the pool after pool garbage collection.
 java.lang.String getName()
          Returns the pool's name.
 java.lang.String getPassword()
          Returns the password.
 java.lang.String getPoolName()
          Deprecated. Replaced by #getName().
protected  int getRecycleThreshold()
           
protected  java.lang.Object getResourceDetails(java.lang.Object resource)
          This method is invoked for every removal candidate when the pool high water mark is reached.
 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.
 long getTimeToCreateMillis(ApplicationModule appModule)
          Gets the time that it will tke to create the application module (in milli-secs).
 java.util.Hashtable getUserData()
          Returns the User Data hashtable.
 java.lang.String getUserName()
          Returns the user name.
 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)
          Instantiate a new pooled resource.
 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.
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.
protected  void releaseInstance(ApplicationModule instance)
          Deprecated.  
 void releaseInstances()
          Deprecated. Replaced by oracle.jbo.pool.removeResources(). Method may be confused with releaseResource.
 void releaseResource(java.lang.Object resource, java.util.Properties properties)
          Release a resource that was previously acquired from the pool with useResource(Properties).
 java.lang.Object removeResource(java.lang.Object resource)
          Remove the resource from the application pool.
 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.
 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 setAvailable(ApplicationModule appModule, boolean isAvailable)
          Deprecated. Implementation detail. Modifying an application module's available status could result in concurrency issues. setAvailable(ApplicationModule) may be invoked to set an unused application module as available.
 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. Please see (@link oracle.jbo.common.ampool.DefaultConnectionStrategy} for more information.
 void setSessionCookieFactory(SessionCookieFactory sessionCookieFactory)
          Set the factory that will be used to create new session cookie instances.
 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. Please see (@link oracle.jbo.common.ampool.DefaultConnectionStrategy} for more information.
 ApplicationModule useApplicationModule(SessionCookie cookie, boolean checkout)
          Returns an application module for the specified session cookie.
 java.lang.Object useResource(java.util.Properties properties)
          Acquire a resource from the pool for exclusive use.
 boolean validateSessionCookie(SessionCookie cookie)
          Validate that a session cookie is a valid handle for this pool.
 
Methods inherited from class oracle.jbo.pool.ResourcePool
addResource, allocateResource, createResource, dumpPoolStatistics, firePoolEvent, getAvailableResourceCount, getCreationTimeMillis, getInitializer, getResource, getResourceCount, getResourceInfo, getResources, getSyncLock, getTimeToCreateMillis, initialize, isAvailable, seekLRUAvailableResource, seekMRUAvailableResource, 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
 

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
Following copied from interface: oracle.jbo.common.ampool.ApplicationPool
See Also:
#isValidSessionCookie(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
Following copied from interface: oracle.jbo.common.ampool.ApplicationPool
Parameters:
poolName - the name of the application module pool.
applicationModule - 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
Overrides:
getMaxPoolSize in class oracle.jbo.pool.ResourcePool
Following copied from class: oracle.jbo.pool.ResourcePool
See Also:
ResourcePool.allocateResource()

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
Overrides:
getInitPoolSize in class oracle.jbo.pool.ResourcePool

createSessionCookie

public SessionCookie createSessionCookie(java.lang.String applicationId,
                                         java.lang.String cookieValue,
                                         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
Following copied from interface: oracle.jbo.common.ampool.ApplicationPool
Parameters:
applicationId - identifies the session application
cookieValue - a cookieValue from a previous request
properties - additional user properties. This parameter may be used to pass application specific information to a session cookie factory.

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
Following copied from interface: oracle.jbo.common.ampool.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. Please see (@link oracle.jbo.common.ampool.DefaultConnectionStrategy} for more information.

Specified by:
getConnectString in interface ApplicationPool
Since:
5.0
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 java.lang.Object getResourceDetails(java.lang.Object resource)
Description copied from class: oracle.jbo.pool.ResourcePool
This method is invoked for every removal candidate when the pool high water mark is reached. It provides subclassing pools an opportunity to provide more information about the target resource. This information is stored and passed back to the subclassing pool when finalizeResource is invoked.
Overrides:
getResourceDetails in class oracle.jbo.pool.ResourcePool

finalizeResource

protected void finalizeResource(java.lang.Object resource,
                                java.lang.Object details)
Description copied from class: oracle.jbo.pool.ResourcePool
Invoked during pool high water mark resolution. May be used to clean up resource state before the resource is removed from the pool.
Overrides:
finalizeResource in class oracle.jbo.pool.ResourcePool

checkin

public void checkin(ApplicationModule appModule)
Deprecated. Replaced by ApplicationModuleRef.releaseApplicationModule(boolean, boolean). Application developers should invoke SessionCookie.releaseApplicationModule(true, false) 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.

Description copied from interface: ApplicationPool
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
Since:
5.0
See Also:
ApplicationModuleRef.releaseApplicationModule(boolean, boolean), 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
Following copied from interface: oracle.jbo.common.ampool.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

checkinWithSessionState

public java.lang.String checkinWithSessionState(ApplicationModule appModule)
Deprecated. Replaced by ApplicationModuleRef.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.

Description copied from interface: ApplicationPool
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
Since:
5.0
See Also:
ApplicationModuleRef.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
Since:
5.0
See Also:
ConnectionStrategy.createApplicationModule(SessionCookie, EnvInfoProvider)

instantiateResource

public java.lang.Object instantiateResource(java.util.Properties properties)
Description copied from class: oracle.jbo.pool.ResourcePool
Instantiate a new pooled resource. Invoked by ResourcePool.useResource(Properties) if it is necessary to create a new pooled resource. Applications should implement this method to return a new instance of a pooled resource.
Overrides:
instantiateResource in class oracle.jbo.pool.ResourcePool

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.

Description copied from interface: ApplicationPool
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
Since:
5.0
See Also:
ApplicationModuleRef.useApplicationModule(), ApplicationModuleRef.releaseApplicationModule(boolean, boolean)

releaseInstances

public void releaseInstances()
Deprecated. Replaced by oracle.jbo.pool.removeResources(). Method may be confused with releaseResource.

Specified by:
releaseInstances in interface ApplicationPool
Since:
5.0
See Also:
removeResources()

releaseInstance

protected void releaseInstance(ApplicationModule instance)
Deprecated.  

Since:
5.0
See Also:
removeResource(Object)

removeResource

public java.lang.Object removeResource(java.lang.Object resource)
Description copied from interface: ApplicationPool
Remove the resource from the application pool.

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

Specified by:
removeResource in interface ApplicationPool
Overrides:
removeResource in class oracle.jbo.pool.ResourcePool

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
Overrides:
removeResources in class oracle.jbo.pool.ResourcePool

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

Description copied from interface: ApplicationPool
Returns an application module for the specified session. The session id must have been generated by a previous call to ApplicationPool.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
Since:
5.0
See Also:
ApplicationModuleRef.useApplicationModule(), ApplicationModuleRef.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
Following copied from interface: oracle.jbo.common.ampool.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
Overrides:
getName in class oracle.jbo.pool.ResourcePool

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
Following copied from interface: oracle.jbo.common.ampool.ApplicationPool
Parameters:
the - new hashtable to use for the environment information.

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. Please see (@link oracle.jbo.common.ampool.DefaultConnectionStrategy} for more information.

Description copied from interface: ApplicationPool
Returns the user name.
Specified by:
getUserName in interface ApplicationPool
Since:
5.0
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. Please see (@link oracle.jbo.common.ampool.DefaultConnectionStrategy} for more information.

Specified by:
setUserName in interface ApplicationPool
Since:
5.0
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. Please see (@link oracle.jbo.common.ampool.DefaultConnectionStrategy} for more information.

Description copied from interface: ApplicationPool
Returns the password.
Specified by:
getPassword in interface ApplicationPool
Since:
5.0
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. Please see (@link oracle.jbo.common.ampool.DefaultConnectionStrategy} for more information.

Specified by:
setPassword in interface ApplicationPool
Since:
5.0
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
Following copied from interface: oracle.jbo.common.ampool.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.


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.
Specified by:
validateSessionCookie in interface ApplicationPool
Following copied from interface: oracle.jbo.common.ampool.ApplicationPool
See Also:
ApplicationPool.getSignature()

setAvailable

public void setAvailable(ApplicationModule appModule,
                         boolean isAvailable)
Deprecated. Implementation detail. Modifying an application module's available status could result in concurrency issues. setAvailable(ApplicationModule) may be invoked to set an unused application module as available.

Specified by:
setAvailable in interface ApplicationPool
Since:
5.0
See Also:
#setAvailable(appModule)

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
Following copied from interface: oracle.jbo.common.ampool.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:
5.0

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
Following copied from interface: oracle.jbo.common.ampool.ApplicationPool
Parameters:
instance - 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
Following copied from interface: oracle.jbo.common.ampool.ApplicationPool
Parameters:
instance - the application module instance for which you want to know how long it will take to create it.

getMinAvailableSize

protected int getMinAvailableSize()
Description copied from class: oracle.jbo.pool.ResourcePool
Return the minimum number of available instances that should exist in the pool after pool garbage collection. Pool garbage collection will remove inactive, available resources until there are no inactive, available resources to be removed or until the minimum available pool size has been reached.

An available resource is defined as inactive if it has not been used for a duration longer than the pool's maximum inactive age.

Overrides:
getMinAvailableSize in class oracle.jbo.pool.ResourcePool
Following copied from class: oracle.jbo.pool.ResourcePool
See Also:
ResourcePool.getMaxInactiveAge()

getMaxAvailableSize

protected int getMaxAvailableSize()
Description copied from class: oracle.jbo.pool.ResourcePool
Return the maximum number of available instances that should exist in the pool after pool garbage collection. Pool garbage collection will remove available resources until there are no available resources to be removed or until the maximum available pool size has been reached.
Overrides:
getMaxAvailableSize in class oracle.jbo.pool.ResourcePool

getMaxInactiveAge

protected int getMaxInactiveAge()
Description copied from class: oracle.jbo.pool.ResourcePool
Return the duration in milliseconds that a resource may remain available before it is considered inactive. Inactive resources are always removed from the pool until the pool minimum available size has been reached.
Overrides:
getMaxInactiveAge in class oracle.jbo.pool.ResourcePool
Following copied from class: oracle.jbo.pool.ResourcePool
See Also:
ResourcePool.getMinAvailableSize()

getRecycleThreshold

protected int getRecycleThreshold()

createPoolLogger

protected oracle.jbo.pool.ResourcePoolLogger createPoolLogger()
Overrides:
createPoolLogger in class oracle.jbo.pool.ResourcePool

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.
Overrides:
getMaxWaitTime in class oracle.jbo.pool.ResourcePool
Following copied from class: oracle.jbo.pool.ResourcePool
See Also:
ResourcePool.getMaxPoolSize(), ResourcePool.allocateResource()

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)
Description copied from class: oracle.jbo.pool.ResourcePool
Acquire a resource from the pool for exclusive use. Attempts to acquire an existing, available resource if one exists. Otherwise, attempts to create a new pooled resource for the request.
Overrides:
useResource in class oracle.jbo.pool.ResourcePool

releaseResource

public void releaseResource(java.lang.Object resource,
                            java.util.Properties properties)
Description copied from class: oracle.jbo.pool.ResourcePool
Release a resource that was previously acquired from the pool with ResourcePool.useResource(Properties). Throws an exception if the resource was not checked out from the pool.
Overrides:
releaseResource in class oracle.jbo.pool.ResourcePool

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:
5.0
See Also:
SessionCookie.isFailoverEnabled()

isDynamicJDBCCredentials

public boolean isDynamicJDBCCredentials()

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:
5.0
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()

Business Components