29.5 How Many Pools are Created, and When?

There are two kinds of pools in use when running a typical ADF web application, Application Module pools and database connection pools. It's important to understand how many of each kind of pool your application will create.

29.5.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 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 an ADF web application in each Java VM where a root application module of that type is used by the ADF controller layer.

29.5.2 Database Connection Pools

ADF web applications always use a database connection pool, but which one they use for your application modules depends on how they define their connection:

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

• JNDI Name for a Datasource (e.g. java:comp/env/jdbc/YourConnectionDS)

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 supply the JNDI name of a JDBC Datasource 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 Datasources looked-up by JNDI from your J2EE Web and/or EJB container, consult the documentation for your J2EE 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.

29.5.3 Understanding Application Module and Connection Pools

Section 29.5.3.1, "Single Oracle Application Server Instance, Single OC4J Container, Single JVM" and Section 29.5.3.2, "Multiple Oracle Application Server Instances, Single OC4J Container, Multiple JVMs" illustrate how application module pools and connection pools are created in different scenarios. Both of these sections make the following assumptions:

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

Consider how many pools of which kinds are created for this application in both a single JVM and multiple JVM runtime scenario.

29.5.3.1 Single Oracle Application Server Instance, Single OC4J Container, Single JVM

If you deploy this application to a single Oracle Application Server instance, configured with a single OC4J container having a single Java VM, 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.

29.5.3.2 Multiple Oracle Application Server Instances, Single OC4J Container, Multiple JVMs

Next consider a deployment environment involving multiple Java VMs. Assume that you have installed Oracle Application Server 10g (version 9.0.4) onto two different physical machines, with a hardware load-balancer in front of it. On each of these two machines, imagine that the Oracle Application Server instance is configured to have one OC4J container with two JVMs. As users of your application access the application, their requests are shared across these two Oracle Application Server instances, and within each Oracle Application Server instance, across the two JVMs that its OC4J container has 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 Application Server Instances) x (2 OC4J JVMs each)

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

  (1 PayablesModule root application module) x (2 Oracle Application Server Instances) x (2 OC4J JVMs each)

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

  (1 appuser DB connection pool) x (2 Oracle Application Server Instances) x (2 OC4J 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 Application Server Instances) x (2 OC4J 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 29.6, "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 request across the multiple JVMs where 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 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.