Skip Headers

Oracle® Application Server Forms Services Deployment Guide 10g Release 2 (10.1.2) B14032-02 |
| Library | Product | Contents | Index

Previous | Next |

# 7 JVM Pooling

This chapter contains the following sections:

- Section 7.1, "Overview"

- Section 7.2, "JVM Pooling Examples"

- Section 7.3, "Design-time Considerations"

- Section 7.4, "About The JVM Controller"

- Section 7.5, "JVM Pooling Management"

- Section 7.6, "JVM Controller Logging Management"

- Section 7.7, "JVM Pooling Error Messages"

## 7.1 Overview

JVM pooling allows administrators to consolidate the number of JVMs that are used so that the Forms sessions can share JVMs, rather than each one having its own instance. JVM pooling results in a large reduction of memory consumption, thus freeing up more resources on your server.

JVM pooling works in conjunction with the Java Importer. The Java Importer allows developers at design-time to reference Java classes from PL/SQL within the Forms Builder. At runtime, Forms uses a Java Virtual Machine (JVM) to execute Java code. JVM pooling expands the capabilities of a Forms application because it can now do operations that can't be done natively in Oracle Forms. For more information on the Java Importer, see the Oracle Forms Developer online help.

## 7.2 JVM Pooling Examples

Take for example an Oracle Forms application that has a user interface button. When the button is pressed, Oracle Forms takes the value from a field on the screen, and passes it to Java (using the Java Importer feature) to do some complex calculation which cannot be done in PL/SQL. The result is then returned and displayed in a field in the Form.

When JVM pooling is not enabled, the Forms Runtime Process operates as described in Figure 7-1, where each Oracle Forms session has its own instance of the JVM which is called an in-process JVM.

Figure 7-1 Forms Runtime with no JVM Pooling

When JVM pooling is enabled, ideally, one JVM can be used for multiple Forms processes, as described in Figure 7-2:

Figure 7-2 Forms Runtime with JVM Pooling Enabled

In this example, five JVM instances have been reduced to one, thereby reducing memory usage.

## 7.3 Design-time Considerations

This section contains the following:

- Section 7.3.1, "About Previous Versions of the Java Importer"

- Section 7.3.2, "Re-importing Your Java Code"

- Section 7.3.3, "About Sharing Static Variables Across Multiple JVMs"

### 7.3.1 About Previous Versions of the Java Importer

When the Java Importer was added to Oracle Forms, each Forms session that used the Java Importer had its own instance of the JVM to execute Java code. Each JVM consumes memory on the server, and if there are many concurrent users, the amount of memory consumed by the multiple JVM processes could become significant.

### 7.3.2 Re-importing Your Java Code

If you used the Java Importer feature of Oracle Forms prior to JVM Pooling, you will need to reimport your Java classes before using JVM pooling. When you originally imported your Java classes, PL/SQL wrappers for the Java classes were generated, which you can see in the Program Units that were created in your Form. However, the PL/SQL wrappers that are needed by the Java Importer are different.

From Oracle Application Server Forms Services 10g and onwards, the Java Importer generates the "new" PL/SQL wrappers. If you want to use the Java Importer, but don't wish to take advantage of JVM pooling, the in-process JVM will work with the new PL/SQL wrappers. It will also continue to work with the older-style PL/SQL wrappers.

If you use Java in your application, but don't wish to use JVM pooling, then you do not need to re-import your Java classes. The in-process JVM will work with previously generated PL/SQL wrappers and with newly generated PL/SQL wrappers.

Note: With an in-process JVM, the JVM is part of the Oracle Forms Runtime Process itself, and is not a separate process. When JVM Pooling is used, the JVM is a separate, external process to the Forms Runtime Processes.

### 7.3.3 About Sharing Static Variables Across Multiple JVMs

If you used the Java Importer feature prior to JVM pooling, each Forms Runtime Process had its own in-process JVM that is separate from all of the others. With JVM pooling, you have multiple Forms runtime processes running Java code within the same JVM. One advantage is the ability to share data between instances of a class by using static variables. However, static variables will be shared between instances of the same class within a JVM, but not across JVMs. You'll need to plan accordingly.

For example, suppose your loan class has a static variable called `interestRate` because all instances use the same interest rate in calculations. If you are using only one JVM, and one of the instances of your loan class changes `interestRate`, all of the other instances will be affected (which is what you want).

However, if the JVM controller has one or more child JVMs, there may be at least two JVMs. If interestRate changes in one JVM, the loan instances in the other JVMs won't see this new value. For more information about managing child JVMs, see Section 7.5.14, "About Child JVMs". Prior to JVM pooling, if you changed interestRate it wouldn't affect any other instances because each Oracle Forms Services Runtime Process had its own in-process JVM.

If you rely on static variables to share information between instances of your class, ensure that no child JVM is spawned by setting `maxsessions` to `65535`.

## 7.4 About The JVM Controller

For each Oracle Forms session, there is one Oracle Forms Runtime Process on the application server. This process is where Oracle Forms actually runs, as well as manages the database connection; queries and updates data; runs any PL/SQL in the Form; executes triggers; and so on.

The Oracle Forms Runtime Process also contains the JVM to run Java in your application. As an optimization feature, the JVM is only started if the Oracle Forms application uses the Java Importer. For applications that do not use it, there is no extra memory consumption for the JVM.

JVM pooling is a new process that contains the JVM controller. With JVM pooling, the JVM runs outside of the Oracle Forms Runtime Process. The JVM can also be shared by multiple Oracle Forms Runtime Processes. The JVM controller process is not a JVM itself, but a container that contains a JVM in a similar way that the Oracle Forms Runtime Process contains an in-process JVM.

Note: Use of JVM pooling is optional. Administrators can choose to not use JVM pooling and have the JVM contained in the Oracle Forms Runtime Process.

When an Oracle Forms Runtime Process needs to execute Java, it sends a message to the JVM that is contained in the JVM controller. The JVM creates a new thread for that Oracle Forms Runtime Process. The JVM then continues to listen for the next new request from a different Oracle Forms Runtime Process while the newly created thread processes the request and sends the results back to the Oracle Forms Runtime Process. For the life of this Oracle Forms session, the Oracle Forms Runtime Process communicates directly with that thread.

Since each Oracle Forms Runtime Process has its own thread within the JVM, there is concurrency. If the JVM reaches a specified number of concurrent requests, it will spawn a child JVM to share the load. Moreover, it's possible to have multiple JVM controllers, each of which may have multiple child JVMs.

For example, different Oracle Forms applications may want to use different JVMs with different options or classpaths. You can specify which JVM controller an Oracle Forms application should use in the named sections of the Oracle Forms configuration file (formsweb.cfg). See Section 7.5.14, "About Child JVMs" for more information.

Figure 7-3 shows an example of what an environment might look like using JVM pooling. There are two JVM controllers: the first one is using only its in-process JVM, the second one is using three JVMs.

Figure 7-3 Multiple JVM Controllers with Child Processes

Although it's not shown in Figure 7-3, each JVM controller has a unique name which is used in starting and stopping, or for referencing in the Oracle Forms configuration file.

Figure 7-3 is conceptual only in that it shows different Oracle Forms applications using different JVM controllers. However, the Oracle Forms Runtime Process does not communicate with the JVM controller, but directly with one of the available JVMs. Therefore, the first two clients in the diagram can only use the in-process JVM; the rest have three available JVMs to work with.

## 7.5 JVM Pooling Management

While the Oracle Forms Runtime Process interacts directly with the JVMs, the JVM controller takes commands from an administrator, such as stopping the JVMs, or enabling or disabling logging, etc. For example, when an administrator issues a stop command, the command ensures all child JVMs are terminated.The JVM controller can be managed in two ways:

- From Enterprise Manager Application Server Control (the recommended method by Oracle)

- From the command line

### 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"

The information that is displayed on the JVM Overview page includes:

Table 7-1 Application Server Control Overview Information for JVM Pooling

Item | Description
--- | ---
Total Memory Usage (%) | Shows memory usage statistics for private, shared, and total usage. Example: Private 0.8519 Shared 3.4226 Total 4.2745
Show All Details | When expanded, the following information displays for all JVM instances: Classpath
JVM Options Displays options that have been enable for this JVM | Log Directory Displays complete path to log file.
Comment | Start Time, example: Fri Aug 20 03:58:57 2004 PDT.
Hide All Details | Collapses all displayed information for all JVM instances.
Select | Use this radio button to select the target JVM you want to manage.
Details | Click Show (+) to expand or Hide (-) to collapse the selected JVM instance information.
Name | Displays the name of this JVM controller when it was created.
Status | Indicates whether the JVM controller is running or not.
Comment | Displays comments about the JVM controller.
CPU Usage (%) | Displays statistics for CPU usage as a percentage.
Private Memory Usage (%) | Displays private memory usage as a percentage.
JVMs | Displays the number of running instances of the target JVM.
Current Sessions | Displays the number of sessions attached to the target JVM.
Maximum Sessions per JVM | Displays the specified limit of number of sessions that can attach to a JVM.
Logging | Indicates whether or not logging is enabled for this JVM.
Log File | When logging is enabled, this icon provides a link to the log file for viewing.

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

Note: The mechanics for controlling the JVM controller as described in this chapter are mostly relevant at the command line. It is easier to use Enterprise Manager Application Server Control with its user-friendly screens and online help.Enterprise Manager Application Server Control users are still urged to read through the following information, however, to understand what the different fields and options mean, and how the JVM controller works.

### 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.7.1 Starting or Restarting a JVM Controller

If a JVM controller is down, you can start it. If a JVM controller is already running, you can restart it without first having to manually stop it. Enterprise Manager Application Server Control does this step for you.

To start a JVM controller that is not running:

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

2. Click Start.

   When the JVM controller has started, you will see a confirmation note at the top of the Forms JVM Controllers page.

To restart a running JVM controller:

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

2. Click Restart.

3. Click Yes on the Confirmation page.

   The Forms JVM Controller page reappears

   When the JVM controller has restarted, you will see a confirmation note at the top of the Forms JVM Controllers page.

To Stop a JVM Controller

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

2. Click Stop.

3. Click Yes on the Confirmation page.

   When the JVM controller has been stopped, you will see a confirmation note at the top of the Forms JVM Controllers page.

### 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.8.1 Command Restrictions

Keep these command restriction in mind:

- The commands are case sensitive.

- You can only issue one command at a time to a JVM controller.

- You can only issue a command to one JVM controller at a time.

The available commands for the JVM controller (or the `dejvm` process) are specified below. If you are using Enterprise Manager Application Server Control, there are screens that have an interface for issuing these commands.

#### 7.5.8.2 Starting a JVM Controller at the Command Line

Use the `-start` command and the following parameters to start a JVM controller, as described in Table 7-5, "Start Command Parameters":

Table 7-5 Start Command Parameters

Parameter | Description
--- | ---
`jvmcontroller` | Refers to the name of the JVM controller you wish to issue the command. This is also how the Forms Runtime Process identifies the JVM controller to send its requests to. It must be unique within a computer, but another JVM controller on a different computer may use the same name.The format of this parameter has the same restrictions as a filename. For instance, it cannot contain special characters such as `"/", ":", "*",` etc.This parameter is required.
`maxsessions` | The maximum number of Forms runtime processes that a JVM can service before creating a child JVM. If `maxsessions` is exceeded, the JVM controller will automatically spawn a new child JVM process with the same settings as the JVM controller. When maxsessions is 65535, this means unlimited connections -- no child JVM will ever be spawned. This is useful if you discover through experience or research that a JVM can only handle a certain number of Forms runtime processes before performance of the JVM degrades.This parameter is optional. Default is 65535.
`logdir` | Location for the log file. The log filename will be automatically generated and will be `<jvm controller>.log`, where <jvm controller> is the name of the JVM controller. If you override this value, then you will not be able to view the log from Enterprise Manager. If you use the default log location (recommended), then you can view the log file from Enterprise Manager.This parameter is optional. The default is `ORACLE_HOME/tools/jvm/log`.
`classpath` | Classpath of the JVM. If you specify the classpath, the system classpath will be ignored, and only the classpath you specified will be used.This parameter is optional. The default is the system classpath or the classpath of the current environment.
`jvmoptions` | JVM options to specify. Refer to the Sun Java documentation for a list of valid JVM startup parameters.This parameter is optional. There is no default value.When specifying this parameter on the command line, use quotes around the value if it contains spaces. When specifying this value in the jvmcontrollers.cfg, do not use quotes, even if the value contains spaces.
logging | Specifies logging as ON or OFF. Default is ON.

#### 7.5.8.3 Stopping a JVM Controller

Use the `-stop` command to stop the JVM controller. You must supply the name of the JVM controller as an argument for the JVM controller you want to stop. You will receive an error if a JVM controller with the specified name is not running. There is no additional option. See Section 7.5.10, "JVM Controller Command Examples" for more information.

### 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`

Note: You cannot change the location or name of the JVM controllers configuration file.

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

Note: It's only when the`-start` command is used that the JVM controller uses the jvmcontrollers.cfg file. For all other commands, the jvmcontrollers.cfg file is not used.

#### 7.5.9.1 Priority of Startup Options

This section describes the priority of how the startup options are applied. When you start a JVM, you must specify the `jvmcontroller` parameter. The JVM controller then follows these steps:

1. The JVM controller looks in the default section of jvmcontrollers.cfg and applies any options that are specified there.

2. The JVM controller looks in `jvmcontrollers.cfg` to see if there is a named section that corresponds to the jvmcontroller parameter. If so, it will take any options that are specified, overriding any it may have found in step 1.

3. The JVM controller then examines the command line arguments. Any options specified there override the options from steps 1 and 2.

This means that the command line parameters have the highest priority, followed by named sections in the JVM controller configuration file, followed by the default section, followed by default values or system settings (e.g. classpath).

For any commands not specified in the above steps, they will take their default values.

### 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:

Table 7-6 Oracle Forms JVM Controller Startup Parameters

Parameter | Description
--- | ---
`jvmcontroller` | Valid values: See Section 7.5.8.2, "Starting a JVM Controller at the Command Line". In addition, you can specify no JVM. Default value: none This parameter can be set globally in the default section, or any application section can choose to override it. This tells the Forms runtime process which JVM controller to use. It corresponds to the jvmcontroller parameter for the dejvm executable (see section 2.3, table 1). If jvmcontroller does not have a value, then the Oracle Forms Runtime Process will start its own in-process JVM, which means that the Java Importer uses pre-10g behavior.

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

#### 7.5.14.1 Child JVM Example

Suppose the JVM controller called ordersJVM has `maxsessions=50`. Each Orders application that is running sends requests to ordersJVM. Each time a new Oracle Forms Runtime Process sends a request to ordersJVM, a new thread is created that communicates with the Oracle Forms Runtime Process. The JVM controller then returns to listening for new requests. As users end their sessions, the threads in the JVM are also terminated.

When the ordersJVM controller receives the 50th concurrent request (not necessarily the first 50 users because some of them may have quit before the later users started) it will spawn a child JVM. Since it inherits its parent's settings, `maxsessions` for this child JVM will also be `50`. At this stage, the JVM controller has 50 connections, and the child JVM has none.

As new users start this Oracle Forms application and execute Java code, the Oracle Forms Runtime Process attaches to a JVM that is listening within the JVM controller namespace. Since the JVM controller has 50 connections, it is unavailable and the child JVM receives the request. Later, when the parent JVM controller has fewer connections because some users have quit their applications, it is available to receive new requests as long as it has not reached `maxsessions` connections.

While all this is going on, the `hrJVM` is operating independently. Overflow connections from ordersJVM not connect to hrJVM, only to child JVMs of ordersJVM.

## 7.6 JVM Controller Logging Management

When logging is enabled, the JVM controller logs certain information to the logfile:

- The values of the JVM parameters (maxsessions, classpath, etc.);

- When a JVM controller starts and stops;

- When a child JVM is spawned;

- When an Oracle Forms Runtime Process starts a new connection, along with its process ID

  This is useful for knowing which Oracle Forms Runtime Processes are connected to which JVM controller for diagnostics or administration;

- When an Oracle Forms Runtime Process session ends and disconnects from the JVM.

### 7.6.1 Enabling and Disabling Logging

This section contains the following:

- Section 7.6.1.1, "Specifying Default Logging Properties"

- Section 7.6.1.2, "Specifiying the Log File Directory Location"

- Section 7.6.1.3, "Accessing Log Files"

- Section 7.6.1.4, "Deleting a Log File for a JVM Controller"

#### 7.6.1.1 Specifying Default Logging Properties

1. Select the default JVM controller.

2. Click Edit.

3. The Edit JVM Controller page appears.

4. From the logging dropdown box, select On or Off.

5. Click Apply.

   The Forms JVM Controllers page reappears.

#### 7.6.1.2 Specifiying the Log File Directory Location

You can specify the log file directory when you create or edit a JVM controller. You can also specify the default JVM controller log file location for other JVM controllers to use.

To specify the log file directory location when creating or editing a JVM controller:

1. Click Create JVM Controller when creating a new controller, or select the radio button next to the target JVM controller.

   The Create New JVM Controller page appears or the Edit JVM Controller page appears.

2. Enter the following information for the JVM log file location:

   Log Directory

   Leave Log Directory empty 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.

3. Click Apply to create the JVM with these settings. The new JVM is automatically started.

   The Forms JVM Controllers page reappears.

#### 7.6.1.3 Accessing Log Files

When logging is enabled for a JVM controller, a clickable icon in the Log File column will appear. When logging is disabled, the log file entry for that JVM controller is empty. See Section 7.6.1, "Enabling and Disabling Logging" for more information.

To access a log file:

1. Click the Log File icon in the Log File column that is available for that JVM controller.

   The Log File page appears and provides the following information:

Table 7-7 Log File Page Information

Item | Description
--- | ---
Log File | Contains the name of the selected JVM controller
Component Name | Displays the name of the JVM controller
Component Type | Displays the application type
Modified | Displays the last time the log file was updated
Size | Displays the log file size in bytes
Log File Contents | Table that contains the most recent log entries. A maximum of 2000 lines is retrieved.
Log Text | Displays the latest entries in the log file

#### 7.6.1.4 Deleting a Log File for a JVM Controller

To delete a log file for a JVM controller:

1. From the JVM Controllers page, select the radio button next to the target JVM.

2. Click Delete Logfile.

   The Delete Confirmation page appears.

3. Click Yes.

   The JVM Controllers page reappears.

## 7.7 JVM Pooling Error Messages

PDE-JM001: Unable to communicate with the JVM Controller: <jvm_name>.

Cause: Failed to start the JVM controller or connect to an existing JVM controller.

Action: Notify your administrator.