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

29.4.1 Setting Configuration Properties Declaratively

The Pooling and Scalability tab of the Configuration Editor shown in Figure 29-3 is used for seeing and setting parameters.

Figure 29-3 Pooling and Scalability Tab of the Configuration Manager

Image of the Pooling and Scalability tab

The values that you supply through the Configuration Manager are saved in an XML file named bc4j.xcfg in the ./common subdirectory relative to the application module's XML component definition. All of the configurations for all of the application modules in a single Java package are saved in that same file.

For example, if you look at the bc4j.xcfg file in the ./oracle/srdemo/model/common directory of the SRDemo application's DataModel project, you will see the two named configurations for its SRService application module, as shown in Example 29-1. The SRServiceLocalTesting configuration uses JDBC URL connections for use by the SRDemo application's JUnit tests and by the Business Components Browser. The SRServiceLocal uses JDBC Datasource names and is used by the web application.

Example 29-1 Configuration Settings for the SRService Application Module

<BC4JConfig>
   <AppModuleConfigBag>
      <AppModuleConfig name="SRServiceLocal">
         <DeployPlatform>LOCAL</DeployPlatform>
         <JDBCDataSource>java:comp/env/jdbc/SRDemoDS</JDBCDataSource>
         <jbo.project>DataModel</jbo.project>
         <jbo.locking.mode>optimistic</jbo.locking.mode>
         <AppModuleJndiName>oracle.srdemo.model.SRService</AppModuleJndiName>
         <jbo.security.enforce>Must</jbo.security.enforce>
         <ApplicationName>oracle.srdemo.model.SRService</ApplicationName>
         <jbo.server.internal_connection
           >java:comp/env/jdbc/SRDemoCoreDS</jbo.server.internal_connection>
      </AppModuleConfig>
      <AppModuleConfig name="SRServiceLocalTesting">
         <DeployPlatform>LOCAL</DeployPlatform>
         <JDBCName>SRDemo</JDBCName>
         <jbo.project>DataModel</jbo.project>
         <AppModuleJndiName>oracle.srdemo.model.SRService</AppModuleJndiName>
         <jbo.locking.mode>optimistic</jbo.locking.mode>
         <jbo.security.enforce>Must</jbo.security.enforce>
         <ApplicationName>oracle.srdemo.model.SRService</ApplicationName>
      </AppModuleConfig>
   </AppModuleConfigBag>
   <ConnectionDefinition name="SRDemo">
      <ENTRY name="JDBC_PORT" value="1521"/>
      <ENTRY name="ConnectionType" value="JDBC"/>
      <ENTRY name="HOSTNAME" value="localhost"/>
      <ENTRY name="DeployPassword" value="true"/>
      <ENTRY name="user" value="srdemo"/>
      <ENTRY name="ConnectionName" value="SRDemo"/>
      <ENTRY name="SID" value="XE"/>
      <ENTRY name="password">
         <![CDATA[{904}05708016F4BB90FC04CFE36B6C9D2BDFE5]]>
      </ENTRY>
      <ENTRY name="JdbcDriver" value="oracle.jdbc.OracleDriver"/>
      <ENTRY name="ORACLE_JDBC_TYPE" value="thin"/>
      <ENTRY name="DeployPassword" value="true"/>
   </ConnectionDefinition>
</BC4JConfig>

Note that child elements of the AppModuleConfig tag appear with tag names matching their property values. It's also important to understand that if a property is currently set to its runtime default value, then the Configuration Manager does not write the entry to the bc4j.xcfg file.

29.4.2 Setting 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.

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 J2EE container probably has a section in its own configuration files where Java system parameters can be specified for use at J2EE container startup time.

Many customers adopt the best practice technique of supplying site-specific default values for ADF configuration parameters as Java system parameters and then make sure that their bc4j.xcfg files do not include references to these parameters unless an application-module-specific exception to these global default values is required.

Using OC4J you can specify these parameters either as -D Java system parameters on the command line that starts OC4J, or provide them — one per line — in the oc4j.properties file and add the -properties oc4j.properties command line flag to OC4J at startup.

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!

29.4.3 Programmatically Setting Configuration Properties

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 29-2

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