Fusion Middleware Documentation
Advanced Search


Developing Fusion Web Applications with Oracle Application Development Framework
Close Window

Table of Contents

Show All | Collapse

50 Tuning Application Module Pools and Connection Pools

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

This chapter includes the following sections:

50.1 About Application Module Pooling

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

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:

  • Unconditionally available for use

  • Available for use, but referenced for session affinity reuse by an active user session

  • Unavailable, inasmuch as it's currently in use (at that very moment) by some thread in the web container.

Section 50.2.5, "What You May Need to Know About Configuration Property Scopes" describes the application module pool configuration parameters and how they affect the behavior of the pool.

50.1.1 Types of Pools Created When Running the Fusion Web Application

There are two kinds of pools in use when running a typical Fusion web application, application Module pools and database connection pools. Applications typically use application module pools, but rarely use connection pools. Connection pools are only used when your application defines the JDBC URL connection type, instead of the default JNDI data source connection type. You primarily need to understand how many of each kind of pool your application will create.

50.1.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 Section 50.4, "Deployment Environment Scenarios and Pooling."

50.1.1.2 Database Connection Pools

The type of database connection pool the Fusion web application uses depends on the connection type that you configure for your application modules:

  • JDBC URL (e.g. jdbc:oracle:thin:@penguin:1521:ORCL)

  • JNDI name for a data source (e.g. java:comp/env/jdbc/YourConnectionDS)

JDeveloper configures the application module by default to use the data source connection type. A JDBC data source is a vendor-independent encapsulation of a database server connection. The JDBC data source offers advantages that the JDBC URL connection type does not. When you define a connection type based on a data source, you reconfigure the data source without changing the deployed application. The data source is also centrally defined at the application server level, whereas JDBC URL connections are not. In cases where a JDBC data source is not viable, at runtime, ADF Business Components will construct a default JDBC URL based on the data source connection information.

If you supply a JDBC URL connection while configuring your application module — which happens when you select a JDeveloper named connection which encapsulates the JDBC URL and username information — then the ADF database connection pool will be used for managing the connection pool.

If you use the default and supply the JNDI name of a JDBC data source then the ADF database connection pool will not be used and the configuration parameters described below relating to the ADF database connection pool are not relevant.

Note:

To configure the database connection pool for JDBC data sources looked-up by JNDI from your Java EE web and/or EJB container, consult the documentation for your Java EE container to understand the pooling configuration options and how to set them.

When using ADF database connection pooling, you have the following basic rule: One database connection pool is created for each unique <JDBCURL,Username> pair, in each Java VM where a <JDBCURL,Username> connection is requested by a root application used by the ADF Controller layer. For advanced topics related to the number of connection pools your application may need, see Section 50.4, "Deployment Environment Scenarios and Pooling."

50.2 Setting Pool Configuration Parameters

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.

50.2.1 How to Set Configuration Properties Declaratively

The Pooling and Scalability tab of the Edit Configuration dialog shown in Figure 50-1 is used for viewing and setting parameters.

Figure 50-1 Pooling and Scalability Tab of the Edit Configuration Dialog

Pooling and Scalability tab

Before you begin:

It may be helpful to have an understanding of connection pooling. For more information, see Section 50.2, "Setting Pool Configuration Parameters."

You may also find it helpful to understand functionality that can be added using other Oracle ADF features.

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, double-click the configuration you want to edit.

  4. In the Edit Configuration dialog, click the Pooling and Scalability tab and edit the desired runtime properties and click OK to save the changes for your configuration.

50.2.2 What Happens When You Set Configuration Properties Declaratively

The values that you supply through the Edit Configuration dialog are saved in an XML file named bc4j.xcfg in the ./common subdirectory relative to the application module's XML document. 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 Edit Configuration dialog to change configuration settings for the application module.

For example, if you look at the bc4j.xcfg file in the ./src/oracle/summit/model/services/common directory of the SummitADF application workspace, you will see the two named configurations for the BackOfficeAppModule application module, as shown in Example 50-1. In this case, 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.

Example 50-1 Configuration Settings for the BackOfficeAppModule

<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 Edit Configuration dialog, then JDeveloper does not write the entry to the bc4j.xcfg file.

50.2.3 How to Set Configuration Properties as System Parameters

As an alternative to specifying configuration properties in the bc4j.xcfg file, you can also set Java VM system parameters with the same property names. These system parameters will be used only if a corresponding property does not exist in the relevant bc4j.xcfg file for the application module in question. In other words, configuration parameters that appear in the application module configuration take precedence over parameters of the same name supplied as Java system parameters.

It may be useful to set configuration properties as Java VM system parameters when all ADF applications running on a particular Java VM require the same configuration value setting for particular parameters. In this case, you must not set the configuration properties in the bc4j.xcfg file and you should confirm that the Edit Configuration dialog displays no value for the desired property, as described in Section 50.2.1, "How to Set Configuration Properties Declaratively."

You typically set Java system parameters using the -D command line flag to the Java VM like this:

java -Dproperty=value -jar yourserver.jar

Alternatively, your Java EE container probably has a section in its own configuration files where Java system parameters can be specified for use at Java EE container startup time.

If you adopt the technique of specifying site-specific default values for Oracle ADF configuration parameters as Java system parameters, you should make sure that your application's bc4j.xcfg files do not include references to these parameters unless you want to define an application-module-specific exception to these global default values.

Caution:

The values of Idle Instance Timeout, Pool Polling Interval settings for both the Application Pool and the database Connection Pool are displayed and edited in this dialog as a number of seconds, but are saved to the configuration file in milliseconds. If you provide a value for any of these four parameters as a Java System parameter — or if you hand-edit the bc4j.xcfg file — make sure to provide these time interval values in milliseconds!

50.2.4 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 Example 50-2.

Example 50-2 Setting Environment Properties with a Custom EnvInfoProvider

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 Example 50-3. 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.

Example 50-3 Custom SessionCookieFactory to Install a Custom EnvInfoProvider

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;
  }
}

50.2.5 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 ApplicationModule 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 programatically 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.

50.2.6 What You May Need to Know About How Database and Application Module Pools Cooperate

How ADF application module pools use the database connection pool depends on the setting of the jbo.doconnectionpooling application module configuration parameter. In the Pooling and Scalability page of the Edit Configuration dialog shown in Figure 50-1, you set this parameter using the checkbox labelled Disconnect Application Module Upon Release.

Note:

The notion of disconnecting the application module upon release to the pool better captures what the actual feature is doing than the related configuration parameter name (jbo.doconnectionpooling) does. The setting of 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.

If the default setting of jbo.doconnectionpooling=false is used, then when an application module instance is created in any pool it acquires a JDBC connection from the appropriate connection pool (based on the JDBC URL in the ADF case, or from the underlying JDBC data source implementation's pool in the case of a JNDI data source name). That application module instance holds onto the JDBC connection object that it acquired from the pool until the application module instance is removed from the application module pool. During its lifetime, that application module instance may service many different users, and ADF worries about issuing rollbacks on the database connection so that different users don't end up getting pending database state confused. By holding onto the JDBC connection, it allows each application module instance to keep its JDBC PreparedStatement objects cached and reusable across subsequent accesses by clients, thereby providing the best performance.

If 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 it 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 the PreparedStatements it might have used during the servicing of the current HTTP request, those PreparedStatements are no longer usable on the next HTTP request because they are only valid in the context of the Connection object in which they were created. So, when using the connection pooling mode turned on like this, the trade-off is slightly more JDBC overhead setup each time, in return for using 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 parameters are set such that the application module pools are allowed to shrink to 0 instances after an appropriate instance idle timeout by setting jbo.ampool.minavailablesize=0, then when the application module is removed from its pool, it will put back the connection its holding onto.

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

Performance Tip:

Leave the jbo.doconnectionpooling configuration parameter set to false for best performance without sacrificing scalability and reliability. Database connection pooling is still achieved through application module pooling. The only exception is when multiple application module pools (and therefore a large number of application module instances) share the same database, making the total available database connections the highest priority.

Highest performance is achieved by not disconnecting the application module instance from its database connection on each check in to the application module pool. Accordingly, the default setting of the jbo.doconnectionpooling configuration parameter is false. The pooling of application module instances is already an effective way to optimize resource usage, and the Oracle ADF runtime is more efficient when you do not have to disconnect application module instances from their associated JDBC connection after each release to the pool. Effectively, by pooling the application modules which are related one-to-one with a JDBC connection, you are already achieving a pooling of database connections that is optimal for most Fusion web applications.

However, when minimizing the total overall number of database sessions is a priority, one situation in which it might be appropriate to use database connection pooling is when you have a large number of application module pools all needing to use database connections from the same underlying application user at the database level. In this case, the many application module pools can economize on the total overall database sessions by sharing a single, underlying database connection pool of JDBC connections, albeit at a loss of efficiency of each one. This choice would be favored only if total overall database sessions is of maximum priority. In this scenario, if a user scrolls through some, but not all rows of a view object's row set, then with jbo.doconnectionpooling=true, Oracle ADF will automatically passivate the pending application module state (including current row information) so that the next time the application module is used, the queried view object can be put back into the same current row with the same initial rows fetched. This passivation behavior may reduce performance.

To achieve a more ideal balance between conserving JDBC connections and keeping all application modules connected to the database, you can configure jbo.ampool.connection_threshold. This runtime property 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 checkin. Setting the maximum number of connections implies disconnecting application modules upon release is desired and automatically enables jbo.doconnectionpooling=true. For more details about optimizing the jbo.doconnectionpooling property, see Section 50.3.2, "What You May Need to Know About Optimizing Connection Pooling."

50.2.7 What You May Need to Know About Application Module Pool Parameters

The application module pool configuration parameters fall into three logical categories relating to pool behavior, pool sizing, and pool cleanup behavior.

50.2.7.1 Pool Behavior Parameters

Table 50-1 lists the application module configuration parameters that affect the behavior of the application module pool.

Table 50-1 Application Module Pool Behavior Configuration Parameters

Pool Configuration Parameter Description

Failover Transaction State Upon Managed Release

(jbo.dofailover)

Specifies whether to disable or enable failover. By default, failover is disabled. To enable failover, set the parameter to true. When enabled, the Oracle ADF framework performs eager passivation of the pending transaction state each time an application module is released to the pool in "Managed State" mode. See Section 49.2.2.2, "How Passivation Changes When Optional Failover Mode is Enabled" for more information.

The failover feature is disabled by default (jbo.dofailover=false) as a performance optimization when there is only one web server instance configured, thus reducing the need for passivation and activation. This allows for application module affinity to a specific user session.

Note: When enabling application module state passivation, a failure can occur when Oracle WebLogic Server is configured to forcibly release connections back into the pool. A failure of this type produces a SQLException (Connection has already been closed.) that is saved to the server log. The exception is not reported through the user interface.

To ensure that state passivation occurs and users' changes are saved, set an appropriate value for the weblogic-application.xml deployment descriptor parameter inactive-connection-timeout-seconds on the <connection-check-params> pool params element.

Setting the deployment descriptor parameter to several minutes, in most cases, should avoid forcing the inactive connection timeout and the resulting passivation failure. Adjust the setting as needed for your environment.

Row-Level Locking Behavior Upon Release

(jbo.locking.mode)

Specifies the locking mode (optimistic or pessimistic). The default is optimistic, which forces the application module pool not to create a pending transaction state on the database with row-level locks each time the application module is released to the pool. See Section 49.11.1, "How to Confirm That Applications Use Optimistic Locking" for more information.

Fusion web applications should leave the locking mode set to the default value optimistic to avoid creating the row-level locks.

This parameter is not configurable in the Edit Configuration dialog. To edit the jbo.locking.mode parameter, open the Business Components page of the overview editor for the adf-config.xml file, located in the ADF META-INF folder in the Application Resources pane of the Applications window.

This feature is enabled by default and set to optimistic.

Disconnect Application Module Upon Release

(jbo.doconnectionpooling)

Note: This parameter's name is misleading and is better understood by the name Disconnect Application Module Upon Release, as shown in the Edit Configuration dialog.

Specifies whether the application module instance can be disconnected from the database connection when the application module instance is returned to the application module pool. This enables an application to size the application module pool larger than the database connection pool. The default is false, which means that an application module instance can retain its database connection when the application module instance is returned to the application module pool. When set to true, the application module can release the database connection back to the database connection pool when the application module instance is returned to the application module pool. Note that before an application module is disconnected from the database connection, a rollback can be issued on that database connection to revert any pending database state.

See also jbo.ampool.connection_threshold to achieve an ideal balance between conserving connections and using in-memory application module passivation. See Section 50.2.6, "What You May Need to Know About How Database and Application Module Pools Cooperate" for more information.

This feature is disabled by default (false).

Disconnect Application Module Upon Reaching Maximum Connection Threshold

(jbo.ampool.connection_threshold)

Specifies whether to force application modules to hold onto their JDBC connections so they do not release back to the connection pool upon checkin until a maximum number of JDBC connections is reached for all application modules in all application module pools combined. The default is to disable this feature (jbo.ampool.connection_threshold=0) which avoids the overhead associated with normal connection pooling.

Setting a connection threshold to a limit greater than 0 enables this feature. When the threshold is reached, connections will be released on the next pool cleanup cycle starting with least recently used, available application modules.

Setting a non-zero connection threshold implies disconnecting application modules upon release is desired and automatically enables jbo.doconnectionpooling=true. See Section 50.3.2, "What You May Need to Know About Optimizing Connection Pooling" for more information.

Setting a non-zero connection threshold releases JDBC connections during application module pool cleanup instead of during application module checkin. To ensure JDBC connections are released efficiently, configure jbo.ampool.monitorsleepinterval to shorten the monitor sleep period.

This feature is disabled by default (jbo.ampool.connection_threshold=0).

Transaction Memory State Upon Release

(jbo.txn.disconnect_level)

Specifies whether the application module, view objects and row sets remain in memory and stay valid but allow their corresponding references to JDBC objects to be dropped. Passivation in memory is enabled by default (jbo.txn.disconnect_level=1). Upon activation, the framework reexecutes and synchronizes the cursor positions.

When used in conjunction with jbo.doconnectionpooling=true or jbo.ampool.connection_threshold, improves performance and reduces the memory overhead associated with this situation. See Section 50.3.2, "What You May Need to Know About Optimizing Connection Pooling" for more information.

Setting jbo.txn.disconnect_level=0, changes the application module passivation behavior so that the view objects and their row sets are closed and removed. In this case, view objects and their row sets will be re-created and reverted to their original state upon activation. Configuring jbo.txn.disconnect_level to 1 can prevent this behavior to avoid the passivation costs for this situation.

This feature is enabled by default (jbo.txn.disconnect_level=1).

Enable Application Module Pooling

(jbo.ampool.doampooling)

Specifies whether to enable application module pooling. By default application pooling is enabled (true).

Whenever you deploy your application in a production environment the default setting of jbo.ampool.doampooling set to true is the way you will run your application. But, as long as you run your application in a test environment, setting the property to false can play an important role in your testing. When this property is false, there is effectively no application pool. See Section 49.10, "Testing to Ensure Your Application Module is Activation-Safe" for more information.

This feature is enabled by default (true).

Support Dynamic JDBC Credentials

(jbo.ampool.dynamicjdbccredentials)

Specifies whether to enable additional pooling lifecycle events to allow developer-written code to change the database credentials (username/password) each time a new user session begins to use the application module.

This feature is enabled by default (true), however this setting is a necessary but not sufficient condition to implement the feature. The complete implementation requires additional developer-written code.

Reset Non-Transactional State Upon Unmanaged Release

(jbo.ampool.resetnontransactionalstate))

Specifies whether the application module resets any nontransactional state like view object runtime settings, JDBC prepared statements, bind variable values, etc. when the application module is released to the pool in unmanaged or "stateless" mode. By default application module reset is enabled (true).

Disabling this feature can improve performance, however since it does not clear bind variable values, your application needs to ensure that it systemically sets bind variable values correctly. Failure to do so with this feature disabled can mean one user might see data with another users bind variable values.)

This feature is enabled by default (true).


50.2.7.2 Pool Sizing Parameters

Table 50-2 lists the application module configuration parameters that affect the sizing of the application module pool.

Table 50-2 Application Module Pool Sizing Configuration Parameters

Pool Configuration Parameter Description

Initial Pool Size

(jbo.ampool.initpoolsize)

Specifies the number of application module instances to create when the pool is initialized. The default is 0 (zero) instances.

Creating application module instances during initialization reduces the cost of CPU processing by creating application module instances during the initialization instead of on-demand when additional application module instances are required.

A general guideline is to configure this to 10% more than the anticipated number of concurrent application module instances required to service all users.

When configuring jbo.initpoolsize, realize that any pre-initialized application module instances that are not used and that exceed the limit specified by jbo.ampool.maxinactiveage will be freed from the pool. Coordinate this parameter with jbo.ampool.minavailablesize to prevent the initialized instances from being reclaimed.

Maximum Pool Size

(jbo.ampool.maxpoolsize)

Specifies the maximum number of application module instances that the pool can allocate. The pool will never create more application module instances than this limit imposes. The default is 4096 instances.

Referenced Pool Size

(jbo.recyclethreshold)

Specifies the maximum number of application module instances in the pool that may attempt to preserve session affinity for the next request made by the session which used them last before releasing them to the pool in managed-state mode. User session affinity mechanism attempts to give back the same application module instance from the pool that the user session was using on the last request. If the application module pool is sized correctly for your typical application load, then most of the time a user session will be reunited with the application module instance it was using.

The default is to allow 10 available instances to try and remain "loyal" to the affinity they have with the most recent session that released them in managed state mode. The referenced pool size should always be less than or equal to the maximum pool size.

Configure this value to maintain the application module instance's affinity to a user's session. A general guideline is to configure this to the expected number of concurrent users that perform multiple operations with short think times. If there are no users expected to use the application with short think times, then this can be configured to 0 zero to eliminate affinity.

Maintaining this affinity as much as possible will save the CPU processing cost of needing to switch an application module instance from one user session to another.


50.2.7.3 Pool Cleanup Parameters

A single application module pool monitor per Java VM runs in a background thread and wakes up every so often to do resource reclamation. 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 for the pool. To override the maximum time to live for an application module, you can set the jbo.ampool.timetolive parameter. 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 jbo.ampool.maxinactiveage parameter.

Table 50-3 lists the parameters that affect how resources are reclaimed when the pool monitor does one of its resource cleanup passes.

Best Practice:

When you specify the length of time between application module pool cleanup passes, set all application modules to use the same Pool Polling Interval value. 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.

Table 50-3 Application Module Resource Management Configuration Parameters

Pool Configuration Parameter Description

Pool Polling Interval

(jbo.ampool.monitorsleepinterval)

Specifies the length of time in milliseconds between pool resource cleanup. Configuring a higher interval results in less frequent resource cleanups.

The default is to have the application module pool monitor wake up every 600000 milliseconds (which is 600 seconds, or ten minutes). Configuring a lower interval results in inactive application module instances being removed more frequently to save memory.

While the number of application module instances in the pool will never exceed the maximum pool size, available instances which are candidates for getting removed from the pool do not get "cleaned up" until the next time the application module pool monitor wakes up to do its job.

Maximum Available Size

(jbo.ampool.maxavailablesize)

Specifies the ideal maximum number of available application module instances in the pool when the server is under load.

The default maximum available size is 25 instances. A lower value generally results in more application module instances being removed from the pool on a cleanup. Configure this to leave the maximum number of available instances desired after a resource cleanup.

A general guideline is to configure this to 20% more than the pool size under normal load to allow for some additional growth. If this is set too low, then some users may see an error accessing the application if no application module instances are available.

When the pool monitor wakes up to do resource cleanup, it will try to remove available application module instances to bring the total number of available instances down to this ideal maximum. Instances that have been not been used for a period longer than the idle instance time-out will always get cleaned up at this time, then additional available instances will be removed if necessary to bring the number of available instances down to this size.

While application module pool tuning allows different values for the jbo.ampool.maxavailablesize | jbo.ampool.minavailablesize parameters, in most cases it is fine to set these minimum and maximum tuning properties to the same value

Minimum Available Size

(jbo.ampool.minavailablesize)

Specifies the minimum number of available application module instances that the pool monitor should leave in the pool during a resource cleanup operation, when the server is under light load.

The default is 5 instances.

Set to 0 (zero) if you want the pool to shrink to contain no instances when all instances have been idle for longer than the idle time-out after a resource cleanup.

While application module pool tuning allows different values for the jbo.ampool.minavailablesize | jbo.ampool.maxavailablesize parameters, in most cases it is fine to set these minimum and maximum tuning properties to the same value.

Idle Instance Timeout

(jbo.ampool.maxinactiveage)

Specifies the number of milliseconds after which to consider an idle application module instance in the pool as a candidate for removal during the next resource cleanup.

The default is 600000 milliseconds of idle time (which is 600 seconds, or ten minutes). A lower value results in more application module instances being marked as a candidate for removal at the next resource cleanup. A higher value results in fewer application module instances being marked as a candidate for removal at the next resource cleanup.

Maximum Instance Time to Live

(jbo.ampool.timetolive)

Specifies the number of milliseconds after which to consider an unused application module instance in the pool as a candidate for removal during the next resource cleanup regardless of whether it would bring the number of instances in the pool below minavailablesize.

The default is 3600000 milliseconds of total time to live (which is 3600 seconds, or one hour). A lower value reduces the time an unused application module instance can exist before it must be removed at the next resource cleanup. The default value is sufficient for most applications. A higher value increases the time an application module instance can exist before it must be removed at the next cleanup.

Alternatively, set the parameter value to -1 when you want to prevent removal of unused application modules by the application module pool monitor.


50.2.8 What You May Need to Know About Data Source Configuration

When you specify a JDBC data source as your application module's connection type, any configuration parameters that you have configured for the database connection pool will be ignored. To configure the connection pool for your data source, you must use the means provided by your Java EE container. In the case of Oracle WebLogic Server, you configure the data source using the Oracle WebLogic Server Administration Console.

The main steps for configuring JDBC data sources are:

  1. Create a data source for each data base that you want to connect to. When you create the data source, specify the configuration options to match the ones for ADF Business Components database connection pools described in Table 50-4. The configuration settings that you specify will depend on your database and the capacity planning that you need anticipate for your application.

    For details about configuring JDBC data sources and connection pool capacity planning, see Administering JDBC Data Sources for Oracle WebLogic Server.

  2. Optionally, configure transaction options for the data source.

  3. Optionally, configure connection testing options for the data source.

  4. Optionally, target the data source to additional servers and clusters.

For detailed procedures for each of these steps, see the topic "Configure JDBC data sources" in the Administration Console Online Help.

Table 50-4 Equivalent Oracle WebLogic Server Data Source Parameters

ADF Business Components Parameter \Oracle WebLogic Server Parameter

Initial Pool Size

(jbo.initpoolsize)

Initial Capacity

Maximum Pool Size

(jbo.maxpoolsize)

Maximum Capacity

Pool Polling Interval

(jbo.poolmonitorsleepinterval)

No equivalent for Oracle WebLogic Server.

Maximum Available Size

(jbo.poolmaxavailablesize)

Maximum Capacity

Minimum Available Size

(jbo.poolminavailablesize)

Maximum Capacity

Idle Instance Timeout

(jbo.poolmaxinactiveage)

Shrink Frequency Seconds


50.2.9 What You May Need to Know About Database Connection Pool Parameters

If you are using a JDBC URL for your connection information so that the ADF database connection pool is used, then configuration parameters listed in Table 50-5 can be used to tune the behavior of the database connection pool. A single "database connection pool monitor" per Java VM runs in a background thread and wakes up every so often to do resource reclamation. The parameters in Table 50-3 include the ones that affect how resources are reclaimed when the pool monitor does one of its resource cleanup passes.

Note:

The configuration parameters for database connection pooling have MetaObjectManager scope (described in Section 50.2.5, "What You May Need to Know About Configuration Property Scopes" earlier). This means their settings are global and will be set once when the first application module pool in your application is created. To insure the most predictable behavior, leave the values of these parameters in the Connection Pool section of the Pooling and Scalability tab at their default values — so that no entry for them is written into the bc4j.xcfg file — and to instead set the desired values for the database connection pooling tuning parameters as Java System Parameters in your Java EE container.

Table 50-5 Database Connection Pool Parameters

Pool Configuration Parameter Description

Initial Pool Size

(jbo.initpoolsize)

Specifies the number of JDBC connection instances to created when the pool is initialized.

The default is an initial size of 0 instances.

Maximum Pool Size

(jbo.maxpoolsize)

Specifies the maximum number of JDBC connection instances that the pool can allocate.

The pool will never create more JDBC connections than this imposes. The default is 4096 instances.

Each connection request will wait up to jbo.poolrequesttimeout and, if no connection becomes available, raises: JBO-28102: A request was timed out while waiting for a resource to be returned to the resource pool, null.

Pool Polling Interval

(jbo.poolmonitorsleepinterval)

Specifies the length of time in milliseconds between pool resource cleanup.

The default is 600000 milliseconds of idle time (which is 600 seconds, or ten minutes). Configuring a lower interval results in inactive connection instances being removed more frequently to save memory. Configuring a higher interval results in less frequent resource cleanups.

While the number of JDBC connection instances in the pool will never exceed the maximum pool size, available instances which are candidates for getting removed from the pool do not get "cleaned up" until the next time the JDBC connection pool monitor wakes up to do its job.

Maximum Available Size

(jbo.poolmaxavailablesize)

Specifies the ideal maximum number of JDBC connection instances in the pool when the server is under load.

The default is an ideal maximum of 25 instances (when not under load).

When the pool monitor wakes up to do resource cleanup, it will try to remove available JDBC connection instances to bring the total number of available instances down to this ideal maximum. Instances that have been not been used for a period longer than the idle instance time-out will always get cleaned up at this time, then additional available instances will be removed if necessary to bring the number of available instances down to this size.

Minimum Available Size

(jbo.poolminavailablesize)

Specifies the minimum number of available JDBC connection instances that the pool monitor should leave in the pool during a resource cleanup operation, when the server is under light load.

The default is to not let the minimum available size drop below 5 instances.

Set to zero (0) if you want the pool to shrink to contain no instances when all instances have been idle for longer than the idle time-out.

Idle Instance Timeout

(jbo.poolmaxinactiveage)

Specifies the number of seconds after which to consider an inactive JDBC connection instance in the pool as a candidate for removal during the next resource cleanup.

The default is 600000 milliseconds of idle time (which is 600 seconds, or ten minutes).

Request Timeout

(jbo.poolrequesttimeout)

Specifies the number of seconds to wait for a JDBC connection instance in the pool, after which raises ADF: Adding the following JSF error message: A request was timed out while waiting for a resource to be returned to the resource pool, null.

Configure this parameter for the expected load. If set too low under load, the server may not have a chance to respond. If set too high, from the user's perspective the application hangs until timeout.

The default is 30000 milliseconds of idle time (which is 30 seconds).


Notice that since the database connection pool does not implement the heuristic of session affinity, there is no configuration parameter for the database connection pool which controls the referenced pool size.

50.3 Initializing Database State and Pooling Considerations

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.

50.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 Example 50-4.

Example 50-4 CONTEXT_PKG PL/SQL Package

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 Section 16.5.2, "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 Example 50-5. 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.

Example 50-5 Method to Call Context_Pkg.Set_App_User_Name Stored Procedure

// 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 Example 50-6.

Example 50-6 Overridden afterConnect() and prepareSession() to Set Database State

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

50.3.2 What You May Need to Know About Optimizing Connection Pooling

The default setting for jbo.doconnectionpooling is false. This means the application module instance hangs onto its JDBC connection while it's in the application module pool. This is the most efficient setting because the application module can keep its JDBC prepared statements open across application module checkouts/checkins.The application module instance will trigger its prepareSession() method each time a new user session begins using it.

If you set jbo.doconnectionpooling to true, then on each checkout of an application module from the pool, that application module pool will acquire a JDBC connection from the database connection pool and use it during the span of the current request. At the end of the request when the application module is released back to the application module pool, that application module pool releases the JDBC connection it was using back to the database connection pool.

It follows that with jbo.doconnectionpooling set to true the application module instance in the pool may have a completely different JDBC connection each time you check it out of the pool. In this situation, the prepareSession() method will fire each time the application module is checked out of the pool to give you a chance to reinitialize the database state.

When you set jbo.doconnectionpooling to true, the default setting for 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 overhead associated with this situation where application module passivation is normally performed upon release. Instead, upon activation, the framework reexecutes and synchronizes the cursor positions.

To achieve a more ideal balance between conserving JDBC connections and keeping all application modules connected to the database, you can configure jbo.ampool.connection_threshold to specify 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 checkin. Setting the threshold to a limit greater than 0, forces the cleanup monitor to release JDBC connections during application module pool cleanup instead of during application module checkin.

This is an important difference with application module connection threshold enabled; application modules are disconnected during pool cleanup, not during checkin. The cleanup monitor makes a best effort to disconnect application modules until the total number of JDBC connections falls below the specified threshold limit. Note that it may not be possible if there are not enough application modules in the available state. To ensure JDBC connections are released efficiently, you can configure jbo.ampool.monitorsleepinterval to shorten the monitor sleep period.

The configure jbo.ampool.connection_threshold property is not exposed by JDeveloper property editors and is intended to be configured at runtime, strictly as a Java option for Oracle WebLogic Server. For example, in your deployment environment, the system administrator may define the property as -Djbo.ampool.connection_threshold=limit using the startup script for Oracle WebLogic Server, such as setWLSEnv.cmd.

When testing your application in JDeveloper, you can specify the property as a JVM system property. For example, specify JDeveloper launch settings for JVM using the Edit Run Configuration dialog, as shown in Figure 50-2. In JDeveloper, open the Edit Run Configuration dialog from the Run/Debug page of the Project Properties dialog.

Figure 50-2 Specifying Application Module Connection Threshold as a JDeveloper Launch Setting

Launch setting for application module connection threshold

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

  • In both HRModule and PayablesModule you have configured jbo.passivationstore=database (the default) and configured the ADF Business Components "internal connection" (jbo.server.internal_connection) used for state management persistence to have the value of a fully qualified JDBC URL that points to a different username than the appuser connection does.

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

  • One DB connection pool for the appuser connection

  • One DB connection pool for the JDBC URL supplied for the internal connection for state management.

This gives a total of two application module pools and two database 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.

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

  • Four DB connection pools for appuser, one in each of four JVMs.

    (1 appuser DB connection pool) x (2 Oracle WebLogic Server domains) x (2 Oracle WebLogic Server JVMs each)

  • Four DB connection pools for the internal connection JDBC URL, one in each of four JVMs.

    (1 internal connection JDBC URL DB connection pool) x (2 Oracle WebLogic Server domains) x (2 Oracle WebLogic Server JVMs each)

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

As you begin to explore the configuration parameters for the application module pools in Section 50.2.7, "What You May Need to Know About Application Module Pool 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 and DB connection 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 Table 50-2 and Table 50-5.