57 Tuning Application Module Pools

This chapter describes how ADF Business Components application module pools work and how you can tune application module pools to optimize application performance.

This chapter includes the following sections:

• About Application Module Pooling

• Setting Pool Configuration Parameters

• Initializing Database State and Pooling Considerations

57.1 About Application Module Pooling

An ADF application module pool is a collection of instances of a single application module type which are shared by multiple application clients. The amount of time between submitting web pages enables a smaller number of application module components to serve a larger number of active users. This reduces memory usage and improves performance.

An application module pool is a collection of application module runtime instances of the same type. To provision a number of users visiting it, the Fusion web application can be configured to provide one or more application module instances from the pool to service users at runtimee.

Each application module instance in a pool is shared by multiple browser clients whose typical "think time" between submitting web pages allows optimizing the number of application module components to be effectively smaller than the total number of active users working on the system. For example, twenty users visiting the website from their browser might be able to be serviced by 5 or 10 application module instances instead of having as many application module instances as you have browser users. Therefore, not only can the pool service more users than the number of application modules available, but in addition the middle tier requires less memory to service this smaller set of application modules allowing ADF applications to scale further on limited hardware resources.

Through your design-time configuration, application modules can be used to support Fusion web application scenarios that are completely stateless, or they can be used to support a unit of work that spans multiple browser pages. As a performance optimization, when an instance of an application module is returned to the pool in "managed state" mode, the pool tracks session references to the application module. The application module instance is still in the pool and available for use, but it would prefer to be used by the same session that was using it the last time because maintaining this "session affinity" improves performance.

So, at any one moment in time, the instances of application modules in the pool are logically partitioned into three groups, reflecting their state:

• Checked into the pool and unconditionally available for use

• Checked into the pool and available for use, but referenced for session affinity reuse by an active user session

• Checked out of the pool and unavailable, inasmuch as it's currently in use (at that very moment) by some thread in the web container

Understanding what happens behind the scenes is essential to make the most efficient use of application module pooling. For details about session state management of application modules, see Managing When Passivation and Activation Occurs.

For details about the configuration parameters that can be set at design time to affect the behavior of the application module pool, see What You May Need to Know About Application Module Pool Configuration Parameters.

57.1.1 Application Module Pools

Application Module components can be used at runtime in two ways:

• As an application module the client accesses directly

• As a reusable component aggregated (or "nested") inside of another application module instance

When a client accesses it directly, an application module is called a root application module. Clients access nested application modules indirectly as a part of their containing application module instance. It's possible, but not common, to use the same application module at runtime in both ways. The important point is that ADF Business Components only creates an application module pool for a root application module.

The basic rule is that one application module pool is created for each root application module used by a Fusion web application in each Java VM where a root application module of that type is used by the ADF Controller layer. For advanced topics related to the number of application module pools your application may need, see Deployment Environment Scenarios and Pooling.

57.1.2 Deployment Environment Scenarios and Pooling

The number of pools and the type of pools that your application will utilize will depend upon how the target platform is configured. For example, will there be more than one Java Virtual Machine (JVM) available to service the web requests coming from your application users and will there be more than one Oracle WebLogic Server domain? To understand how many pools of which kinds are created for an application in both a single-JVM scenario and a multiple-JVM runtime scenario, review the following assumptions:

• Your Fusion web application makes use of two application modules HRModule and PayablesModule.

• You have a CommonLOVModule containing a set of commonly used view objects to support list of values in your application, and that both HRModule and PayablesModule aggregate a nested instance of CommonLOVModule to access the common LOV view objects it contains.

• You have configured both HRModule and PayablesModule to use the same JDeveloper connection definition named appuser.

57.1.2.1 Single Oracle WebLogic Server Domain, Single Oracle WebLogic Server Instance, Single JVM

If you deploy this application to a single Oracle WebLogic Server domain, configured with a single Oracle WebLogic Server instance, there is only a single Java VM available to service the web requests coming from your application users.

Assuming that all the users are making use of web pages that access both the HRModule and the PayablesModule, this will give:

• One application module pool for the HRModule root application module

• One application module pool for the PayablesModule root application module

This gives a total of two application module pools in this single Java VM.

Note:

There is no separate application module pool for the nested instances of the reusable CommonLOVModule. Instances of CommonLOVModule are wrapped by instances of HRModule and PayablesModule in their respective application module pools.

57.1.2.2 Multiple Oracle WebLogic Server Domains, Multiple Oracle WebLogic Server Instance, Multiple JVMs

Next consider a deployment environment involving multiple Java VMs. Assume that you have configured four different physical machines as two Oracle WebLogic Server domains, with a hardware load-balancer in front. On these four machines, each Oracle WebLogic Server instance will have a single JVM. As users of your application access the application, their requests are shared across these two Oracle WebLogic Server domains, and within each domain, across the two JVMs that its Oracle WebLogic Server instances have available.

Again assuming that all the users are making use of web pages that access both the HRModule and the PayablesModule, this will give:

• Four application module pools for HRModule, one in each of four JVMs.

  (1 HRModule root application module) x (2 Oracle WebLogic Server domains) x (2 Oracle WebLogic Server JVMs each)

• Four application module pools for PayablesModule, one in each of four JVMs.

  (1 PayablesModule root application module) x (2 Oracle WebLogic Server domains) x (2 Oracle WebLogic Server JVMs each)

This gives a total of eight application module pools spread across four JVMs.

As you begin to explore the configuration parameters for the application module pools in What You May Need to Know About Application Module Pool Configuration Parameters, keep in mind that the parameters apply to a given application module pool for a given application module in a single JVM.

As the load balancing spreads user requests across the multiple JVMs where Oracle ADF is running, each individual application module pool in each JVM will have to support one n ^th of the user load — where n is the number of JVMs available to service those user requests. The appropriate values of the application module pools need to be set with the number of Java VMs in mind. The basic approach is to base sizing parameters on load testing and the results of the application module pooling statistics, then divide that total number by the n number of pools you will have based on your use of multiple application server domains and multiple Oracle WebLogic Server instances. For example, if you decide to set the minimum number of application modules in the pool to ten and you end up with five pools due to having five Oracle WebLogic Server instances servicing this application, then you would want to configure the parameter to 2 (ten divided by five), not 10 (which would only serve a given application module in a single JVM).

For details about available sizing parameters, see Pool Sizing Parameters.

57.2 Setting Pool Configuration Parameters

Configuration parameters set in the ADF application allow you to control the runtime behavior of an application module pool. There are three logical categories of the application module pool configuration parameters: Pool behavior, Pool Sizing, and Pool Cleanup Behavior.

You control the runtime behavior of an application module pool by setting appropriate configuration parameters. You can set these declaratively in an application module configuration, supply them as Java System parameters, or set them programmatically at runtime.

57.2.1 How to Set Configuration Properties Declaratively

You use the Database and Scalability tab of the overview editor for application module configurations shown in Figure 57-1 for viewing and setting runtime configuration properties of individual application modules.

Figure 57-1 Database and Scalability Tab of the Edit Configuration Dialog

Description of "Figure 57-1 Database and Scalability Tab of the Edit Configuration Dialog"

Before you begin:

It may be helpful to have an understanding of application module pooling. For more information, see Setting Pool Configuration Parameters.

Familiarize yourself with the application module configuration parameters. For more information about configuration parameters for application module pool tuning, see What You May Need to Know About Application Module Pool Configuration Parameters.

For best practice guidelines that may help you to tune the Fusion web application for an expected level of usage, see the Tuning Oracle Application Development Framework chapter of Tuning Performance.

Note that if your application defines a JDBC URL connection type (legacy only), refer to the 11g release version of this guide to obtain documentation on the ADF database connection pool configuration parameters.

To edit your application module's pooling configuration:

1. In the Applications window, double-click the application module.
2. In the overview editor, click the Configurations navigation tab.
3. In the Configurations page, click the configuration hyperlink for the configuration you want to edit.
4. In the overview editor for application module configurations, click the Database and Scalability tab and edit the desired runtime properties and click OK to save the changes for your configuration.

57.2.2 What Happens When You Set Configuration Properties Declaratively

The values that you supply through the overview editor for application module configurations are saved in an XML file named bc4j.xcfg in the ./common subdirectory relative to the application module's XML definition. All of the configurations for all of the application modules in a single Java package are saved in that same file. Typically, you do not modify the bc4j.xcfg file directly and use the overview editor to change configuration settings for specific application modules. To display the application module configuration overview editor, double-click the application module in the Applications window and, in the overview editor, select the Configurations navigation tab. Then, in the Configurations page of the overview editor, click the configuration hyperlink.

For example, if you look at the overview editor for application module configurations for the BackOfficeAppModule application module in the SummitADF application (on the bc4j.xcfg file in the ./src/oracle/summit/model/services/common directory), you will see the two named configurations for the BackOfficeAppModule application module. In this case, as the following example shows, the BackOfficeAppModuleLocal and the BackOfficeAppModuleShared configurations specify JDBC URL connections for use by the Oracle ADF Model Tester. The connection details for the JDBC connections appear in the connections.xml file located in the ./.adf/META-INF subdirectory relative to the project directory.

<BC4JConfig version="11.1" xmlns="http://xmlns.oracle.com/bc4j/configuration">
...
   <AppModuleConfigBag
      ApplicationName="oracle.summit.model.services.BackOfficeAppModule">
      <AppModuleConfig 
            name="BackOfficeAppModuleLocal"
            jbo.project="oracle.summit.model.Model"
            ApplicationName="oracle.summit.model.services.BackOfficeAppModule"
            DeployPlatform="LOCAL" JDBCName="summit_adf">
         <Database jbo.TypeMapEntries="Java"/>
         <Security
            AppModuleJndiName="oracle.summit.model.services.BackOfficeAppModule"/>
      </AppModuleConfig>
      <AppModuleConfig
            name="BackOfficeAppModuleShared"
            jbo.project="oracle.summit.model.Model"
            ApplicationName="oracle.summit.model.services.BackOfficeAppModule"
            DeployPlatform="LOCAL" JDBCName="summit_adf">
         <AM-Pooling jbo.ampool.maxpoolsize="1"
                     jbo.ampool.isuseexclusive="false"/>
         <Database jbo.TypeMapEntries="Java"/>
         <Security
            AppModuleJndiName="oracle.summit.model.services.BackOfficeAppModule"/>
      </AppModuleConfig>
   </AppModuleConfigBag>
</BC4JConfig>

Note that attributes of child elements of the <AppModuleConfig> tag have names beginning with jbo that match the names of their ADF Business Components properties (for example, the <AM-Pooling> tag defines the attribute jbo.ampool.maxpoolsize that corresponds to the property jbo.ampool.maxpoolsize). It's also important to understand that if a property is currently set to its runtime default value in the application module configurations editor, then JDeveloper does not write the entry to the bc4j.xcfg file.

57.2.3 How to Programmatically Set Configuration Properties

When your application requires control over application module configuration properties at runtime, you can dynamically set these properties using ADF Business Components API. For example, in a typical ADF application, your application module may configure a static JDBC data source. However, when the application needs to display data, depending upon the user, from various databases, you might set the data source name and application module pool parameters at runtime.

You can set configuration properties programmatically by creating a Java class that implements the EnvInfoProvider interface in the oracle.jbo.common.ampool package. In your class, you override the getInfo() method and call put() to put values into the environment Hashtable passed in as shown in the following example.

package devguide.advanced.customenv.view;
import java.util.Hashtable;
import oracle.jbo.common.ampool.EnvInfoProvider;
/**
 * Custom EnvInfoProvider implementation to set
 * environment properties programmatically
 */
public class CustomEnvInfoProvider implements EnvInfoProvider {
  /**
   * Overridden framework method to set custom values in the
   * environment hashtable.
   * 
   * @param string - ignore
   * @param environment Hashtable of config parameters
   * @return null - not used
   */
  public Object getInfo(String string, Object environment) {
    Hashtable envHashtable = (Hashtable)environment;
    envHashtable.put("some.property.name","some value");
    return null;
  }
  /* Required to implement EnvInfoProvider */
  public void modifyInitialContext(Object object) {}
  /* Required to implement EnvInfoProvider */
  public int getNumOfRetries() {return 0;}
}

When creating an application module for a stateless or command-line-client, with the createRootApplicationModule() method of the Configuration class, you can pass the custom EnvInfoProvider as the optional second argument. In order to use a custom EnvInfoProvider in an ADF web-based application, you need to implement a custom session cookie factory class as shown in the following example. To use your custom session cookie factory, set the jbo.ampool.sessioncookiefactoryclass configuration property to the fully qualified name of your custom session cookie factory class.

package devguide.advanced.customenv.view;
import java.util.Properties;
import oracle.jbo.common.ampool.ApplicationPool;
import oracle.jbo.common.ampool.EnvInfoProvider;
import oracle.jbo.common.ampool.SessionCookie;
import oracle.jbo.http.HttpSessionCookieFactory;
/**
 * Example of custom http session cookie factory
 * to install a custom EnvInfoProvider implementation
 * for an ADF web-based application.
 */
public class CustomHttpSessionCookieFactory
       extends HttpSessionCookieFactory {
  public SessionCookie createSessionCookie(String appId,
                                           String sessionId, 
                                           ApplicationPool pool,
                                           Properties props) {
    SessionCookie cookie =
      super.createSessionCookie(appId, sessionId,pool, props);
    EnvInfoProvider envInfoProv = new CustomEnvInfoProvider();
    cookie.setEnvInfoProvider(envInfoProv);
    return cookie;
  }
}

57.2.4 What You May Need to Know About Configuration Property Scopes

Each runtime configuration property used by ADF Business Components has a scope. The scope of each property indicates when the property's value is evaluated and whether its value is effectively shared (i.e. static) in a single Java VM, or not. The ADF Business Components PropertyManager class is the registry of all supported properties. It defines the property names, their default values, and their scope. This class contains a main() method so that you can run the class from the command line to see a list of all the configuration property information.

Assuming JDEVHOME is the JDeveloper installation directory, to see this list of settings for reference, do the following:

$ java -cp JDEVHOME/BC4J/lib/bc4jmt.jar oracle.jbo.common.PropertyManager

Issuing this command will send all of the ADF Business Components configuration properties to the console. It also lists a handy reference about the different levels at which you can set configuration property values and remind you of the precedence order these levels have:

---------------------------------------------------------------
Properties loaded from following sources, in order:
1. Client environment [Provided programmatically
                       or declaratively in bc4j.xcfg]
2. Applet tags
3. -D flags (appear in System.properties)
4. bc4j.properties file (in current directory)
5. /oracle/jbo/BC4J.properties resource
6. /oracle/jbo/commom.jboserver.properties resource
7. /oracle/jbo/common.Diagnostic.properties resource
8. System defined default
---------------------------------------------------------------

You'll see each property is listed with one of the following scopes:

• MetaObjectManager

  Properties at this scope are initialized once per Java VM when the ADF PropertyManager is first initialized.

• SessionImpl

  Properties at this scope are initialized once per invocation of ApplicationModule.prepareSession().

• Configuration

  Properties at this scope are initialized when the application module pool is first created and the application module's configuration is read the first time.

• Diagnostic

  Properties at this scope are specific to the built-in ADF Business Components diagnostic facility.

At each of these scopes, the layered value resolution described above is performed when the properties are initialized. Whenever property values are initialized, if you have specified them in the Client Environment (level 1 in the resolution order) the values will take precedence over values specified as System parameters (level 3 in the resolution order).

The Client Environment is a hashtable of name/value pairs that you can either programmatically populate, or which will be automatically populated for you by the Configuration object when loaded, with the name/value pairs it contains in its entry in the bc4j.xcfg file. The implication of this is that for any properties scoped at MetaObjectManager level, the most reliable way to ensure that all of your application modules use the same default value for those properties is to do both of the following:

1. Make sure the property value does not appear in any of your application module's bc4j.xcfg file configuration name/value pair entries.

2. Set the property value using a Java system property in your runtime environment.

If, instead, you leave any MetaObjectManager-scoped properties in your bc4j.xcfg files, you will have the undesirable behavior that they will take on the value specified in the configuration of the first application module whose pool gets created after the Java VM starts up.

57.2.5 What You May Need to Know About Application Module Pool Configuration Parameters

The application module pool configuration parameters fall into three logical categories relating to pool behavior, pool sizing, and pool cleanup behavior. By default Fusion web applications enable application module pooling.

57.2.5.1 Pool Behavior Parameters

The application module defines configuration parameters that affect the behavior of the application module pool and whether application module instances holds onto JDBC connection that they obtain from the connection pool after an instance is removed from the application module pool.

How ADF application module pools use the database connection pool depends on the setting of the Disconnect Application Module Upon Release configuration parameter jbo.doconnectionpooling. As shown in Figure 57-1, by default the setting is disabled and the parameter has the setting jbo.doconnectionpooling=false.

.

Note:

The setting jbo.doconnectionpooling=false does not mean that there is no database connection pooling happening. What it means is that the application module is not disconnected from its JDBC connection upon check in back to the application module pool.

When an application module instance is created in the application module pool it acquires a JDBC connection. By default, ADF favors maintaining session affinity so that across the request of a single user, ADF will try and reuse the same application module instance (including its associated memory and JDBC connection and state), with the goal of speeding up performance for such users. The default setting of jbo.doconnectionpooling=false enables this behavior which enforces application module instances keep their JDBC PreparedStatement objects cached and reusable across subsequent requests by clients.

However, as the number of users who access the Fusion web application increases, so does the memory requirement on the server to hold onto the JDBC connection, prepare statement, and result sets. When the application module pool is configured to support several thousand users, the demands of not releasing JDBC connections after each request can place demands on server load with a fraction of the supported managed user sessions. This situation is particularly notable in a deployment environment configured to use database drivers that optimize performance over memory consumption, as has been the case for Oracle JDBC drivers since Oracle Database 10g.

To avoid the situation where server memory can be rapidly consumed by the JDBC driver, you can override the default application module instance connection behavior by setting jbo.doconnectionpooling=true, then each time a user session finishes using an application module (typically at the end of each HTTP request), the application module instance disassociates itself with the JDBC connection it was using on that request and it returns the connection to the JDBC connection pool. The next time that application module instance is used by a user session, it will reacquire a JDBC connection from the JDBC connection pool and use it for the span of time that application module is checked out of the application module pool (again, typically the span of one HTTP request). Since the application module instance "unplugs" itself from the JDBC connection object used to create each PreparedStatement, in this situation it follows that the prepareSession() method will fire each time the application module is checked out of the pool to reinitialize the database state. So, when releasing JDBC connections is enabled for sessions, the trade-off is slightly more JDBC overhead setup each time, in return for holding onto a smaller number of overall database connections.

The key difference is seen when many application module pools are all using the same underlying database user for their application connection.

• If 50 different application module pools each have even just a single application module instance in them, with jbo.doconnectionpooling=false there will be 50 JDBC application connections in use. If the application module pooling size parameters are set such that the application module pools are allowed to shrink to 0 instances after an appropriate instance idle timeout by setting the Minimum Available Size configuration parameter jbo.ampool.minavailablesize=0, then when the application module is removed from its pool, it will put back the connection its holding onto. This situation is optimal when the number of managed application module instances remains low, outside of peak demand times or when the application needs to support a low number of simultaneous users.

• In contrast, if 50 different application module pools each have a single application module instance and jbo.doconnectionpooling=true, then the amount of JDBC connections in use will depend on how many of those application modules are simultaneously being used by different clients. If an application module instance is in the pool and is not currently being used by a user session, then with jbo.doconnectionpooling=true it will have released its JDBC connection back to the connection pool and while the application module instance is sitting there waiting for either another user to need it again, or to eventually be cleaned up by the application module pool monitor, it will not be "hanging on" to a JDBC connection. This situation is optimal in ensuring the scalability of the Fusion web application during peak demand times or when the number of simultaneous users is expected to increase.

When you set jbo.doconnectionpooling to true, the default setting 1 for the Transaction Disconnect Level configuration parameter jbo.txn.disconnect_level ensures that all application modules, view objects and row sets remain in memory and stay valid after their corresponding references to JDBC connections are dropped. This configuration reduces the memory requirement associated with this situation where application module passivation is normally performed upon release. Instead, upon activation, the framework only needs to reexecute and synchronize the cursor positions.

Alternatively, you may be able to achieve a balance between conserving JDBC connections and holding onto connections by configuring the Connection Threshold configuration parameter jbo.ampool.connection_threshold. This parameter specifies the maximum number of connections that application modules in all application module pools combined may hold onto without releasing back to the connection pool during application module pool cleanup. Note that setting the jbo.ampool.connection_threshold parameter to a maximum number of connections (greater than 0) implies disconnecting application modules during pool cleanup is desired and therefore the configuration parameter jbo.doconnectionpooling must not be enabled. For more details about how the jbo.ampool.connection_threshold parameter affects application module pooling, see What You May Need to Know About Optimizing Application Module Pooling.

57.2.5.2 Pool Sizing Parameters

The application module defines configuration parameters that affect the sizing of the application module pool. When the pool monitor performs one of its resource cleanup passes, it will try to bring the number of application module instances into the range specified by the maximum and minimum available size parameters.

When the pool monitor cannot reduce the pool size below the maximum size by removing unused and idle application module instance, it will then remove active instances that have not timed out and passivate the state of these active application modules. The Referenced Pool Size configuration parameter jbo.recyclethreshold determines how many active application modules will remain in the pool monitor when passivation occurs. By default, the threshold over which the pool monitor will begin passivating is 10 application module instances.

You can use the Maximum Available Pool Size configuration parameter jbo.ampool.maxavailablesize to specify the upper range of the pool size after resource cleanup by the pool monitor. Typically, you override the default maximum available size 25 based on the number of concurrent users and how frequently the users need to access the services of the application module. However, when server memory is not the limiting factor for application performance, the maximum available size may be set to an arbitrarily large value to minimize the affect of passivation and activation of application module instances that are still tied to active user sessions.

Note:

Specifying a sufficiently large maximum pool size is especially important when configuring pool cleanup not to reclaim unused application module instances and to allow idle times of 30 minutes for a typical HTTP session timeout. For more information about configuring pool cleanup, see Pool Behavior Parameters.

Similarly, you can use the Minimum Available Pool Size configuration parameter jbo.ampool.minavailablesize to specify the lower range of the pool size, when the default of 5 instances is not sufficient to ensure a baseline of available application module instance. Typically, consider setting this value equal to the number of concurrent users at non-peak usage. Setting this value too low results in needless instantiation of application module instances that can affect performance.

57.2.5.3 Pool Cleanup Parameters

The application module defines configuration parameters that affect how resources are reclaimed when the pool monitor does one of its resource cleanup passes.

A single application module pool monitor per Java VM runs in a background thread and wakes up to scan through the pool to perform cleanup at the interval of 600000 milliseconds (10 minutes) by default. To change the default Pool Polling Interval, you can configure the Pool Polling Interval parameter jbo.ampool.monitorsleepinterval.

The pool monitor uses the following two, independent strategies to identify which application module instances are candidates to be removed from the pool and reclaimed as a potential new resource.

1. The application module pool monitor removes application module instances from the pool that have not been used for more than 3600000 milliseconds (which is the default value and is exactly one hour). These unused application module instances will be reclaimed regardless of the minimum available size configured for the pool. To override the maximum time to live for an application module, you can set the Maximum Instance Time to Live configuration parameter jbo.ampool.timetolive. However, for most Fusion web applications, you will not need to reclaim unused application module instance and can set this parameter value to -1.

2. The application module pool monitor removes application module instances that have remained idle for 600000 milliseconds (which is the default value and is exactly 10 minutes). This cleanup stops when the number of instances in the pool reaches the minimum available size. You can override the idle timeout for application module instances using the Idle Instance Timeout configuration parameter jbo.ampool.maxinactiveage when you want to allow idle user sessions of more than 10 minutes.

Best Practice:

When you specify the length of time between application module pool cleanup passes, set the same value for Pool Polling Interval configuration parameter jbo.ampool.monitorsleepinterval for all application modules. Since there is only a single application monitor pool monitor per Java VM, the value that will effectively be used for the application module pool monitor polling interval will be the value found in the application module configuration read by the first application module pool that gets created. Setting all application modules to use the same value ensures that this value is set in a predictable way.

57.2.6 What You May Need to Know About Optimizing Application Module Pooling

You may be able to achieve a balance between conserving JDBC connections and holding onto connections by configuring the Connection Threshold configuration parameter jbo.ampool.connection_threshold. This parameter specifies the maximum number of connections that application modules in all application module pools combined may hold onto without releasing back to the connection pool upon the next pool cleanup cycle.

When the Connection Threshold parameter jbo.ampool.connection_threshold is enabled (value greater than 0), application module connections are released during pool cleanup, not during checkin. The cleanup monitor makes a best effort to disconnect least recently-used application modules until the total number of JDBC connections falls below the specified threshold limit. Since enabling the jbo.ampool.connection_threshold parameter changes when application module pool cleanup is performed, this implies setting the parameter jbo.ampool.connection_threshold=true is not compatible.

Note:

When configuring a threshold value for disconnecting application modules during the pool cleanup cycle, be sure to disable jbo.doconnectionpooling so the value is false (default). The Connection Threshold parameter is not compatible with the setting jbo.doconnectionpooling=true since this setting causes JDBC connections to release back to the connection pool upon checkin of the application module, and the setting works in combination with the jbo.txn.disconnect_level parameter to ensure business components remain in memory. For more information about the jbo.doconnectionpooling parameter, see Pool Behavior Parameters.

For example, assume the Connection Threshold parameter is set to 10 for two application module pools, where application module pool 1 has seven application modules and pool 2 has eight application modules for a total of 15 JDBC connections. When the application module pool cleanup monitor runs, the monitor will make a best effort to reclaim five connections (15 connection resources - 10 connection threshold). The monitor disconnects application modules proportional to the total number of connected application modules for each pool. In this case, one third of the application modules connections (5/15) from each pool will be disconnected. So pool 1 will loose two connections (7/3) and pool 2 will release three connections (8/3), where the fraction of the pool size will be rounded up.

The cleanup monitor makes a best effort to disconnect application modules until the connected resource number falls below the specified limit but note that it may not be able to do so if there are not enough application modules in an available state. To ensure JDBC connections are released efficiently, you can configure the Pool Polling Interval parameter jbo.ampool.monitorsleepinterval to shorten the monitor sleep period.

57.3 Initializing Database State and Pooling Considerations

You can set database state on a per-user basis for your Fusion web application. This is of great benefit as there may be a need to call upon stored procedures to initialize database state related to a particular user's session.

Sometimes you may need to invoke stored procedures to initialize database state related to the current user's session. The correct place to perform this initialization is in an overridden prepareSession() method of your application module.

57.3.1 How to Set Database State Per User

The Fusion web application can set database state on a per-user basis. You typically create a database CONTEXT namespace, associate a PL/SQL procedure with it, and then use the SYS_CONTEXT() SQL function to reference values from the context.

For example, you can use the PL/SQL package to set and get a package-level variable that holds the name of the currently authenticated Fusion web application user as shown in the following example.

create or replace package context_pkg as
  procedure set_app_user_name(username varchar2);
  function app_user_name return varchar2;
end context_pkg;

Then your application can define the WHERE clause of a view object to reference the context_pkg.app_user_name function and query the per-user state.

To set the database state, the application module framework extension class (AppModuleImpl.java) defines a callStoredProcedure() helper method similar to the ones in How to Invoke Stored Procedure with Only IN Arguments. The custom application module class then extends this framework extension class and defines the setCurrentUserInPLSQLPackage() helper method shown in the following example. The helper method uses the callStoredProcedure() method to invoke the context_pkg.set_app_user_name() stored procedure, passing the value of the currently authenticated user as a parameter value.

// In CustomAppModuleImpl.java
public void setCurrentUserInPLSQLPackage() {
  String user = getUserPrincipalName();
  callStoredProcedure("context_pkg.set_app_user_name(?)",new Object[]{user});
}

With this helper method in place, the custom application module class then overrides the prepareSession() method as shown in the following example.

// In CustomAppModuleImpl.java
  protected void prepareSession(Session session) {
    super.prepareSession(session);
    getLoggedInUser().retrieveUserInfoForAuthenticatedUser();     
    setUserIdIntoUserDataHashtable();
    setCurrentUserInPLSQLPackage();      
  }