7.5 JVM Pooling Management

7.5.1 About Managing JVM Controllers from Enterprise Manager Application Server Control

Enterprise Manager Application Server Control provides a Web-based environment to manage all available JVM pooling options. Enterprise Manager Application Server Control interacts with the JVM controller so that administrators can manage JVM pooling. It is the central place for internally managing all of the JVMs for a JVM controller. It also lists all JVM controllers in your environment and allows you to (remotely) manage them. For example, you can start and stop JVM controllers; add new ones; or reconfigure existing ones. In addition, Enterprise Manager Application Server Control also provides metric information such as resources (memory and CPU) that are consumed by JVM controllers.

Use the JVM page in Application Server Control to manage JVM pooling tasks:

• Section 7.5.3, "Creating a New JVM Controller"

• Section 7.5.5, "Editing JVM Controller Properties with Enterprise Manager Application Server Control"

• Section 7.5.6, "Specifying Default JVM Controller Properties"

• Section 7.5.4, "Deleting a JVM Controller"

• Section 7.5.7.1, "Starting or Restarting a JVM Controller"

• Section 7.5.8.3, "Stopping a JVM Controller"

• Section 7.6, "JVM Controller Logging Management"

Table 7-1 describes the information that is displayed on the JVM Overview page:

7.5.2 About Managing JVM Controllers from the Command Line

If you manage JVM controllers from the command line, you must know the options to start and stop them, as well as specify the environment. You can only access the JVM controllers on the same computer from which they are running.

7.5.3 Creating a New JVM Controller

After you've created a new JVM controller, you'll need to start it, as described in Section 7.5.7.1, "Starting or Restarting a JVM Controller".

To create a new JVM controller:

1. Click Create JVM Controller.

   The Create New JVM Controller page appears.

2. Enter the following information for the new JVM, as described in Table 7-2, "Options for Creating a New JVM Controller":

   Table 7-2 Options for Creating a New JVM Controller

   Option	Description
   Name	Enter a name for this JVM. This name must contain a legal Oracle identifier that starts with a letter and contains an alphanumeric character, '_', '$' or '#' . An Oracle identifier has a length of 30 bytes. Hint: You may want to enter a name based on the application that will be accessing it. You cannot change the name of this JVM controller later.
   Maximum Sessions per JVM	Specifies the maximum number of concurrent Oracle Forms sessions this JVM will serve before a new JVM is spawned. This value will override any set for the default JVM controller.
   Classpath	When you specify a classpath, it will override the system classpath or any classpath specified in your environment or any classpath set for the default JVM controller.
   JVM Options	Enter any valid options to pass to the JVM. This value will override any set for the default JVM controller. Refer to the Sun Java documentation for a list of valid JVM startup parameters.
   Log Directory	Leave Log Directory blank to use the log location for the default JVM controller. If any other directory is set, the log file cannot be viewed through Enterprise Manager.
   Logging	On, Off, or Default. Setting to On or Off overrides the default JVM logging behavior. Setting to Default tells the new JVM to inherit default logging properties from the default JVM.
   Comment	Add any comments about this JVM in this text area.

   
   

3. Click Apply to create the JVM with these settings.

   The Forms JVM Controllers page reappears.

4. Restart the JVM. See Section 7.5.7.1, "Starting or Restarting a JVM Controller" for more information.

7.5.4 Deleting a JVM Controller

Oracle recommends stopping a JVM controller before deleting it. If you delete it without stopping it, the JVM will not be removed from the JVM controllers page.

To delete a JVM controller:

1. Click the radio button to the left of the target JVM controller.

2. Click Edit.

   The Edit JVM Controller page appears.

3. Click Delete.

   The Confirmation page appears.

4. Click Yes to delete it.

   The Forms JVM Controllers page reappears without the deleted JVM controller.

7.5.5 Editing JVM Controller Properties with Enterprise Manager Application Server Control

You edit the properties for a JVM controller with Enterprise Manager Application Server Control, which provides an HTML-based graphical user interface.

To edit JVM controller properties:

1. Click the radio button to the left of the target JVM controller.

2. Click Edit.

   The Edit JVM Controller page appears.

3. Edit the following information for the new JVM, as described in Table 7-3, "JVM Controller Property Settings":

4. Table 7-3 JVM Controller Property Settings

   Setting	Description
   Maximum Sessions per JVM	Specifies the maximum number of concurrent Oracle Forms sessions this JVM will serve before a new JVM is spawned. This value will override any other that is set for the default JVM controller.
   Classpath	When you specify a classpath, it will override the system classpath or any classpath specified in your environment or any classpath set for the default JVM controller.
   JVM Options	Enter any valid options to pass to the JVM. This value will override any set for the default JVM controller. Refer to the Sun Java documentation for a list of valid JVM startup parameters.
   Log Directory	Leave Log Directory blank to use the default log location for the default JVM controller. If any other directory is set, the log file cannot be viewed through Enterprise Manager.
   Logging	On, Off, or Default. Setting to On or Off overrides the default JVM logging behavior. Setting to Default tells the new JVM to inherit default logging properties from the default JVM.
   Comment	Add any comments about this JVM in this text area.

   
   

5. Click Apply to commit the JVM property settings.

   The Forms JVM Controllers page reappears.

7.5.6 Specifying Default JVM Controller Properties

You can use the default JVM controller as a way for new JVM controllers to inherit predefined properties.

To edit the default JVM controller properties:

1. Click the radio button to the left of the default JVM controller.

   The Edit JVM Controller page appears.

2. Edit the following information for the default JVM:

   Table 7-4 Default JVM Controller Options

   Option	Description
   Maximum Sessions per JVM	Specifies the maximum number of concurrent Oracle Forms sessions the default JVM will serve before a new JVM is spawned.
   Classpath	When you specify a classpath, it will override the system classpath or any classpath specified in your environment.
   JVM Options	Enter any valid options to pass to the JVM. Refer to the Sun Java documentation for a list of valid JVM startup parameters.
   Log Directory	Leave Log Directory blank to use the log location for the default JVM controller. If any other directory is set, the log file cannot be viewed through Enterprise Manager.
   Logging	On or Off.
   Comment	Add any comments about this default JVM in this text area.

   
   

3. Click Apply to change the default JVM property settings.

   The Forms JVM Controllers page reappears.

7.5.7 Starting and Stopping JVM Controllers with Enterprise Manager Application Server Control

Enterprise Manager Application Server Control is the recommend tool for managing Oracle Forms Services, such as starting, stopping, and restarting a JVM controller.

7.5.8 JVM Controller Usage Commands

The JVM controller takes a command and various options. You must supply the name of the JVM controller as an argument for the JVM controller you want to manage. The executable name for the JVM controller is dejvm. It is used to start and stop the JVM controller, as well as manage what it does. The format of the command line is:

dejvm -<command> jvmcontroller=<controllerName> [options]

where:

• command is the command you are issuing to JVM controller.

• controllerName is the name of the JVM controller you are referring to.

• options is zero or more options available for the command you have chosen. See

  See Section 7.5.10, "JVM Controller Command Examples" for the list of available commands and options.

7.5.9 The JVM Controller Configuration File

The JVM controller configuration file is used by Enterprise Manager and may optionally be used as a convenience for administrators at the command line. The name and location of the configuration file is:

ORACLE_HOME/tools/jvm/jvmcontrollers.cfg

It works similarly to the Forms configuration file (formsweb.cfg) in that it contains name-value pairs, has a default section, and has named sections. The parameters contained in jvmcontrollers.cfg correspond to the start parameters of the JVM controller.

When you start a JVM controller, it can take its settings from the configuration file, rather than having to be entered on the command line. You may specify none, some, or all options in this file, both in the default section and in named sections.

An example jvmcontrollers.cfg file might look like this:

# # This is the default section. These parameters will # apply unless overridden in a named section (lower down) # or on the command line. # [default] jvmoptions=-Xms512m -Xmx1024m maxsessions=50
# # Below are the named sections. # [hrJVM] jvmoptions=-Xms256m -Xmx512m classpath=/myJava/hrClasses

7.5.10 JVM Controller Command Examples

Here are some command line examples. It is assumed that the jvmcontrollers.cfg file is similar to the previous example:

• dejvm -start jvmcontroller=hrJVM

  Starts a JVM controller with ID hrJVM. The controller name hrJVM is defined as a named section in the configuration file. Therefore, JVM options and classpath parameters are taken from the configuration file. maxsessions will be 50 as defined in the Default section, and other parameters take their default values.

• dejvm -start jvmcontroller=myJVM

  Starts a JVM controller with ID is myJVM. Since no option was specified, and there is no named section in jvmcontrollers.cfg, the JVM options parameter is "-Xms512m -Xmx1024m" and maxsessions=50 as set in the Default section. The other parameters take on their default values. For instance, the CLASSPATH value will be the system CLASSPATH.

• dejvm -start jvmcontroller=hrJVM jvmoptions="-Xms128m -Xmx256m" maxsessions=75

  Sets the classpath to /myJava/hrClasses as defined in the named section. JVM options will be "-Xms128m -Xmx256m" because the command line overrides the jvmcontrollers.cfg file. Similarly, maxsessions will be 75. All other parameters take on their default values.

• dejvm -start jvmcontroller=myJVM maxsessions=100 classpath=/myJava/myClasses;/moreJava/moreClasses

  The controller will have jvmoptions="-Xms512m -Xmx1024m" as defined in the default section of jvmcontrollers.cfg. maxsessions will be 100 which overrides the default section, and classpath is /myJava/myClasses;/moreJava/moreClasses. All other parameters take on their default values.

• dejvm -stop jvmcontroller=hrJVM

  Stops the hrJVM controller. It must already be started for you to issue this command successfully.

7.5.11 Forms Configuration File Settings

This section describes the JVM pooling parameters that are used in the Forms configuration file (formsweb.cfg). The parameter names are not case-sensitive. Remember, you can use Enterprise Manager to administer the Forms configuration file. Table 7-6, "Oracle Forms JVM Controller Startup Parameters" describes the startup options that you can place in the formsweb.cfg file:

7.5.12 Startup Example

The following is a snippet from a formsweb.cfg file the shows the startup flow:

# System settings [default] jvmcontroller=commonJVM
[ordersApp] form=orders.fmx userid=orders/orderspw@orcl[hrApp] form=hr.fmx userid=hr/hrpw@orcl jvmcontroller=hrJVM[salesApp] form=sales.fmx userid=sales/salespw@orcl

If a user starts an ordersApp application, and the application executes Java code, the Oracle Forms Runtime Process will route the request to the JVM controller named commonJVM. Because the [ordersApp] application section doesn't specify which JVM controller to use, the Oracle Forms Runtime Process uses the global one. If the JVM controller isn't started, it will be dynamically started. If a second user starts the same application, it too will attach to commonJVM.

When a user starts an hrApp application and it executes Java code, the Oracle Forms Runtime Process sends the request to the JVM controller named hrJVM because the [hrApp] application section overrides the global setting. If the JVM controller isn't started, it will be dynamically started. When a second user starts the same application, it too will attach to hrJVMWhen a user starts a salesApp application and it executes Java code, the Oracle Forms Runtime Process starts an in-process JVM in the same way the Java Importer works without JVM pooling. When a second user starts the same application, the application will get their own in-process JVM, thus consuming more memory, as shown in Figure 7-4:

Figure 7-4 Multiple JVMs for multiple applications

In Figure 7-4, the commomJVM controller, its in-process JVM, and any child JVM is represented as a single box, as well as the hrJVMcontroller.

7.5.13 About Multiple JVM Controllers

The JVM pooling architecture allows you to have multiple JVM controllers, each of which may have child JVMs. You would use multiple JVM controllers if:

• You want each application to have its own JVM controller so that it can be started and stopped independently of others.

• Different applications require different settings. For example, you may not want to mix classpaths or JVM settings between different controllers.

• You want to monitor resource usage of the JVM controllers from Enterprise Manager. If different JVM controllers are used by different applications and/or groups of users, you can determine how resources are being consumed by your Java Importer code.

• You have multiple development, test, or production environments on the same computer.

• You don't want different applications to share static data.

7.5.14 About Child JVMs

When the performance of a JVM degrades significantly, it probably means it is servicing too many requests. In that case, it is possible to have multiple "child" JVMs for the same JVM controller which get created dynamically as needed.

The JVM parameter maxsessions specifies how many Oracle Forms Runtime Processes are allowed to attach to a JVM before a new child JVM is created. When a child JVM is started, it inherits the same parameters as the JVM controller.

If any JVM has maxsessions connections, it will not take any request from new Oracle Forms Runtime Processes. When a new Oracle Forms Runtime Process first attempts to execute Java code, it will attach to a JVM that is available, i.e. has fewer maxsessions connections. The method of choosing the JVM is entirely arbitrary; there is no load balancing or round-robin algorithm.

If a JVM reaches maxsessions connections, but another JVM has not, then no new JVM is created. If all JVMs have simultaneously reached maxsessions connections, another child JVM is created, and so on.

Child JVMs are not automatically removed when the load is reduced. So if you want to remove some child JVMs, the JVM controller must be stopped, which also stops all child JVMs. Then the JVM controller can be restarted.

The scope of a child JVM is within the context of a JVM controller namespace. For example, if you have two JVM controllers, ordersJVM and hrJVM, then ordersJVM and its child JVMs do not affect – nor are not affected by – hrJVM or its child JVMs.