10 Configuring and Managing Java Virtual Machines

This chapter contains the following sections:

10.1 Why Use Java Virtual Machine Pooling?

When a Forms application calls out to Java, a JVM is attached to each Forms process the first time the process makes a call. This JVM remains attached to each process for the remainder of the processes' lives, even though any individual process may never call out to Java again, potentially causing resource contention. JVM pooling makes provisions for sharing a limited number of JVMs among all participating Forms processes. Even though all Forms processes might at one point call out to Java, if only a subset of these call out to Java at any given point in time, only as many JVMs as are necessary at peak usage, need be started. Using JVM pooling brings the potential to significantly reduce resource usage for a Forms installation that calls out to Java.

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

Java Virtual Machine pooling is a separate process that contains the JVM controller. With JVM pooling, the JVM runs outside of the Forms runtime process. The JVM can also be shared by multiple 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 Forms Runtime process contains an in-process JVM. Using JVM pooling is optional. Administrators can choose to not use JVM pooling and have the JVM contained in the Forms runtime process.

Java Virtual Machine (JVM) pooling works in conjunction with the Java Importer. It also works with Forms' ability to call out to Reports. 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. In earlier versions of Oracle Forms, each Forms session that used the Java Importer had its own JVM instance to execute Java code. In this model, each JVM consumes memory on the server, and if there are many concurrent users, the amount of memory consumed by the multiple JVM processes becomes significant.

For more information on the Java Importer, see the Oracle Forms Developer online help.

When you enable JVM pooling, administrators can consolidate the number of running JVM instances so that the Forms sessions can share JVMs rather than each one having its own instance. The result is a large reduction in memory consumption, thus freeing up more resources on your server.

You also need to consider JVM pooling in application design and deployment. For more information, see Chapter 10, "Design-time Considerations".

10.1.1 JVM Pooling in Forms and Reports Integration

In 10g, Forms Runtime process creates a separate JVM before calling Reports and Reports uses this JVM to execute the java methods. This JVM is part of the Forms Runtime process. In 10g, the JVM pooling feature is used only by the Java Importer. However, in 11g, with JVM pooling enabled, Oracle Forms Services uses a shared JVM controller for Oracle Reports requests.

Instead of each Forms Runtime process having its own instance of the JVM, JVMs can be shared by multiple Forms Runtime processes. With JVM pooling, a process called JVM controller is available which houses the JVM. Forms Runtime processes can share this JVM. This would result in a large reduction of memory consumption, freeing more resources on the server.

A form can be configured to use a specific JVM controller using the jvmcontroller parameter. The jvmcontroller parameter indicates to the Forms Runtime process which JVM controller to use. This can be set in the Forms Configuration File, formsweb.cfg. Alternatively, this information can also be passed as a parameter in the URL for invoking the Forms Application. The parameters that need to be used during startup of the jvmcontroller have to be specified in the JVM controller's configuration file, jvmcontrollers.cfg.

For more information on using JVM pooling for Reports integration, see Section 10.10, "Integrating Forms and Reports".

10.2 About Child Java Virtual Machine Processes

Since each 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 Forms applications may want to use different JVMs with different options or classpaths. You can specify which JVM controller and Forms application should be used in the named sections of the Forms configuration file (formsweb.cfg). See Section 10.8.6, "Forms Configuration File Settings" for more information.

Figure 10-1 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 10-1 Multiple JVM Controllers with Child Processes

This image illustrates an environment with JVM pooling.

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

Figure 10-1 is conceptual only in that it shows different Forms applications using different JVM controllers. However, the 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.

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 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 does not take any request from new Forms runtime processes. When a new Forms runtime process first attempts to execute Java code, it attaches to a JVM that is available, that is, has fewer than 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, 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, ordersJVM and its child JVMs do not affect – nor are affected by – hrJVM or its child JVMs.

10.2.1 Child JVM Example

Suppose the JVM controller called ordersJVM has maxsessions=50. Each Orders application that runs sends requests to ordersJVM. Each time a new Forms runtime process sends a request to ordersJVM, a new thread is created that communicates with the 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 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 will not connect to hrJVM, only to child JVMs of ordersJVM.

10.3 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 Fusion Middleware Control. 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 do not want different applications to share static data.

10.4 JVM Pooling Usage Examples

Consider, for example, an Oracle Forms application that has a user interface button. When a user presses the button, 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. One JVM process is running to execute this Forms session.

Figure 10-2 shows how this Oracle Forms session has its own in-process JVM because JVM pooling is not enabled. In the left side of the image, there are multiple clients running their own Forms session. In the center of the image, each client makes a call to its own Forms Runtime process, which contains its own JVM process.

Figure 10-2 Forms Runtime with no JVM Pooling

This image illustrates shows the in-process JVM.
Description of "Figure 10-2 Forms Runtime with no JVM Pooling"

Figure 10-3 shows the Forms Runtime processes sharing a single JVM process when JVM pooling is enabled, as shown in the right side of the image.

Figure 10-3 Forms Runtime with JVM Pooling Enabled

JVM pooling
Description of "Figure 10-3 Forms Runtime with JVM Pooling Enabled"

In this example, five clients working in the same application through their own runtime processes are using a pooled JVM process instead of each Forms Runtime process spawning its own JVM instance. This can be a significant savings in memory usage and system resources.

10.5 Design-time Considerations

This section contains the following:

10.5.1 Re-importing Your Java Code

If you used the Java Importer feature of Oracle Forms prior to the availability of 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 generated by the Java Importer to utilize JVM pooling are different.

From Oracle Forms Services 10g and later, the Java Importer generates the "new" PL/SQL wrappers. If you want to use the Java Importer, but do not 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.

10.5.2 About Sharing Static Variables Across Multiple JVMs

One advantage of JVM pooling 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 will 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 10.2, "About Child Java Virtual Machine Processes". Prior to JVM pooling, if you changed interestRate it would not affect any other instances because each Oracle Forms 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.

10.6 Overview of JVM Configuration

To configure JVM using Fusion Middleware Control, perform the following steps:

  1. Using Fusion Middleware Control, add a new configuration section or modify an existing section in formsweb.cfg to enable or disable use of JVM controller for applications. For more information, refer to Section 10.8.6, "Forms Configuration File Settings".

  2. Ensure CLASSPATH is updated in default.env or in jvmcontrollers.cfg.

  3. Using Fusion Middleware Control, configure the JVM parameters. For more information, refer to Section 10.8.3, "Managing Parameters".

  4. Start the JVM controller. For more information, refer to Section 10.8.5, "Starting and Stopping JVM Controllers with Fusion Middleware Control".

10.7 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 Fusion Middleware Control with its user-friendly screens and online help. Fusion Middleware 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.

10.7.1 JVM Controller Command Examples

This section describes examples of JVM controller commands. For a detailed explanation on the example, see Section 10.8.7, "Startup 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 is 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 is 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 are "-Xms128m -Xmx256m" because the command line overrides the jvmcontrollers.cfg file. Similarly, maxsessions is 75. All other parameters take on their default values.

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

    The controller has jvmoptions="-Xms512m -Xmx1024m" as defined in the default section of jvmcontrollers.cfg. maxsessions is 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.

10.7.2 Command Restrictions

Keep these command restrictions 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 in Table 10-1. If you are using Enterprise Manager, there are screens that have an interface for issuing these commands. If you are using the command line, you may not be able to manage the JVM controller using the Enterprise Manager.

10.7.3 Start Command Parameters

Table 10-1 describes the JVM parameters used to start the JVM from the command line.

Table 10-1 JVM Parameters

Parameter Description

jvmcontroller

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

maxsessions

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.

jvmoptions

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

logdir

Leave Log Directory blank to use the log location for the default JVM controller. If any other directory is set, the log file may not be accessible through Enterprise Manager.

logging

On, or Off.

10.8 Managing JVM Pooling from Fusion Middleware Control

Fusion Middleware Control provides a Web-based environment to manage all available JVM pooling options. 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, Fusion Middleware Control also provides metric information such as resources (memory and CPU) that are consumed by JVM controllers, number of Forms connected, total JVMs, and so on.

While the Forms runtime process interacts directly with a JVMs, the JVM controller manages the JVM, such as starting and stopping a JVM, or getting the state of one, etc. For example, when an administrator stops the JVM controller, the JVM controller ensures that all child JVMs are terminated. You use Fusion Middleware Control to manage the JVM controller.

The JVM controller can be started in three ways:

  • From Fusion Middleware Control

  • When a Forms application that is bound to an existing JVM controller requests that the controller start up

  • From the command line

Fusion Middleware Control reads the JVM controller configuration file. It works in a similar way 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.

Note:

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

When you start a JVM controller, it takes its settings from the configuration file. You may specify none, some, or all options in this file, both in the default section and in named sections.

Use the JVM Configuration and JVM Controller pages in Fusion Middleware Control to manage JVM pooling tasks:

10.8.1 Common Tasks in the JVM Configuration Page

This section describes the common tasks that you can do to edit configuration with the sections of a JVM configuration file and their parameters.

Table 10-2 describes the tasks you can do with the configuration sections within a JVM configuration file:

Table 10-2 Tasks for Working with Configuration Sections

Task Description Comment

Create Like

Creates a copy of a configuration section.

Use to create a configuration section based on the parameters of an existing configuration section.

Edit

Opens the Edit Description dialog.

Allows editing the text description of a configuration section.

Delete

Opens the Confirmation dialog when deleting a configuration section.

Irrevocably deletes a configuration section and its contents when you press Delete in the Confirmation dialog.

Create

Opens the Create Section dialog.

Creates a new configuration section. You must supply a required name and an optional description for it.

Table 10-3 describes the tasks that you can do to modify the parameters within a named configuration section:

Table 10-3 Tasks for Working with Parameters in a Named Configuration Section

Task Description Comment

Revert

Allows you to revert back to the previous version of the configuration section.

Does not allow you to revert individual changes in a configuration section.

Apply

Applies and activates all changes made to parameters in a configuration section.

Once applied, you cannot revert changes to individual parameters.

Add

Opens the Add Parameter dialog.

Add a parameter to a configuration section based on a mandatory name and an optional value and description.

Delete

Deletes a parameter.

Use Apply to save changes or Revert to discard them. Once applied, you cannot revert changes to individual parameters.

10.8.2 Managing JVM Configuration Sections

This section describes creating, editing, duplicating, and deleting named JVM configuration sections.

10.8.2.1 Accessing the JVM Configuration Page

To access the JVM configuration page: 

  1. Start the Enterprise Manager Fusion Middleware Control.

  2. From the Fusion Middleware Control main page, click the link to the Forms Services instance that you want to configure.

  3. From the Forms menu list, select the JVM Configuration menu item.

    The JVM Configuration page (Figure 10-4) is displayed.

    Figure 10-4 JVM Configuration Page

    JVM Configuration page
    Description of "Figure 10-4 JVM Configuration Page"

10.8.2.2 Creating a New Configuration Section

You can create new configuration sections in jvmcontrollers.cfg from the JVM Configuration page of Fusion Middleware Control. These configurations can be requested in the end-user's query string of the URL that is used to run a form.

To create a new configuration section: 

  1. From the Fusion Middleware Control main page, click the link to the Forms Services instance that you want to configure.

  2. From the Forms menu list, select JVM Configuration.

  3. Click Create.

    The Create dialog appears.

  4. Enter a name and description for your new configuration section and click Create.

    The new configuration section is added.

10.8.2.3 Editing a Named Configuration Description

You can edit the description (comments) for a named configuration from the JVM Configuration page.

To edit a named configuration description:

  1. In the JVM Configuration region, select the row containing the named configuration for which you want to edit the description.

  2. Click Edit.

  3. The Edit Description dialog appears.

  4. Enter the description in the Comments field.

  5. Click Save.

    The Edit Description dialog box is dismissed, and your changes are saved and displayed.

10.8.2.4 Duplicating a Named Configuration

You can make a copy of a named configuration for backup purposes, or create new configuration sections from existing configuration sections.

To duplicate a named configuration:

  1. In the JVM Configuration region, select Create Like.

  2. In the Create Like dialog, from the Section to Duplicate menu, select the name of an existing configuration section you want to duplicate.

  3. In the New Section Name field, enter a name for the new configuration section. The name for the new configuration section must be unique.

  4. Click Create.

    A new section with exactly the same parameters, parameter values and comments of the section you are duplicating is created.

10.8.2.5 Deleting a Named Configuration

When you delete a named configuration section, you delete all the information within it. If you only want to delete specific parameters, see Section 10.8.3, "Managing Parameters".

To delete a named configuration:

  1. From the JVM Configuration region, select the row of the configuration section you want to delete.

  2. Click Delete.

    The Confirmation dialog appears.

  3. Click Delete.

    The configuration section is deleted.

    Oracle Enterprise Manager returns to the JVM Configuration page and displays the remaining configurations.

Note:

You cannot delete the Default configuration section.

10.8.3 Managing Parameters

Use Fusion Middleware Control to manage parameters within a named configuration. You can add, edit, or delete parameters using Fusion Middleware Control.

To edit a parameter in a configuration section:

  1. From the JVM Configuration region, select the row of the configuration section that contains the parameter(s) you want to edit.

  2. Select the row of the parameter you want to edit. Enter the Value and Comments.

  3. Click Apply to save the changes or Revert to discard them.

To add a parameter to a configuration section:

  1. In Fusion Middleware Control, from the JVM Configuration region, select the configuration section row for which you want to add a parameter.

  2. Click Add to add a new parameter.

    The Add dialog box is displayed.

  3. Enter the Name, Value and Comments for the parameter.

  4. Click Create to add the parameter.

  5. Click Apply to save the changes or Revert to discard them.

To delete a parameter in a configuration section:

  1. In Fusion Middleware Control, from the JVM Configuration region, select the configuration section from which you want to delete a parameter.

  2. Select the row that contains the parameter you want to delete.

  3. Click Delete.

  4. Click Apply to save the changes or Revert to discard them.

10.8.4 JVM Configuration Parameters and Default Values

Table 10-4 describes the JVM configuration parameters and their default values.

Table 10-4 JVM Configuration Parameters

Parameter Description Default Value

Maximum Sessions per JVM

Specifies the maximum number of concurrent Oracle Forms sessions the default JVM will serve before a new JVM is spawned.

65535

Classpath

When you specify a classpath, it will override the system classpath or any classpath specified in your environment.

$ORACLE_HOME/jdk/bin/java

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.

Null

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.

$ORACLE_INSTANCE/FRComponent/frcommon/tools/jvm/log

Logging

Specifies whether logging is enabled or not. Valid values: On, Off.

On

Comment

Add any comments about this default JVM in this text area.

Null

10.8.5 Starting and Stopping JVM Controllers with Fusion Middleware Control

Fusion Middleware Control is the recommended tool for managing Oracle Forms Services, such as starting, stopping, and 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. Fusion Middleware Control does this step for you.

Note:

Ensure that users have stopped the forms sessions that are using the JVM controller before you stop or restart the JVM. Users may want to restart sessions when the JVM is restarted.

To access the JVM Controller page:

  1. Start the Enterprise Manager Fusion Middleware Control.

  2. From the Forms home page, select JVM Controllers.

    The JVM Controllers page (Figure 10-5) is displayed.

Figure 10-5 JVM Controller Page

JVM Controller Page
Description of "Figure 10-5 JVM Controller Page"

To start a JVM controller that is not running:

  1. From the Forms menu, select JVM Controllers.

    The JVM Controllers page is displayed.

  2. Select the JVM controller that you want to start. A JVM that is not running is indicated by a red, down arrow.

  3. Click Start.

    When the JVM controller has started, a green, up arrow (Figure 10-5) is displayed in the Status.

To restart a running JVM controller:

  1. From the Forms menu, select JVM Controllers.

    The JVM Controllers page is displayed.

  2. Select the JVM controller to be restarted.

  3. Click Restart.

  4. Click Yes on the Confirmation dialog.

    The JVM Controller page reappears.

    When the JVM controller has restarted, a green, up arrow is displayed in the Status.

To stop a JVM Controller

  1. From the Forms menu, select JVM Controllers.

    The JVM Controllers page is displayed.

  2. Select the running JVM controller that you want to stop, indicated by a green, up arrow.

  3. Click Stop.

  4. Click Yes on the Confirmation dialog.

    When the JVM controller has been stopped, a red, down arrow (Figure 10-5) is displayed in the Status.

To view additional details of a JVM Controller

  1. From the Forms menu, select JVM Controllers.

    The JVM Controllers page is displayed.

  2. Click the plus symbol next to the JVM controller. The row is expanded to display additional details (Figure 10-5) of the JVM controller.

10.8.6 Forms Configuration File Settings

This section describes the JVM pooling parameters that are used in the Forms configuration file (formsweb.cfg) to enable or disable use of JVM controller for applications. The parameter names are not case-sensitive. You can use Fusion Middleware Control to administer the Forms configuration file.

Table 10-5, "Oracle Forms JVM Controller Startup Parameters" describes the startup options that you specify in the formsweb.cfg file.

For more information on modifying the parameters in formsweb.cfg, see Section 4.2.4, "Managing Parameters".

Table 10-5 Oracle Forms JVM Controller Startup Parameters

Parameter Description

jvmcontroller

Valid values: name of jvmcontroller. In addition, you can specify no JVM by leaving it blank.

Default value: none

Note: In order to specify this parameter in formsweb.cfg, you must first specify this parameter in otherparams in the form jvmcontroller=%jvmcontroller%. For more information on otherparams, see Table 4-13, "Advanced Configuration Parameters".

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.

If jvmcontroller does not have a value (jvmcontroller=), then the Forms runtime process will start its own in-process JVM, which means that the Java Importer uses pre-10g behavior.

allowJVMControllerAutoStart

Valid values: true, false

Default value: true

This parameter enables Oracle Forms to run the JVM controller if Forms is configured to use the JVM controller which is not already running.

10.8.7 Startup Example

This example illustrates an environment of multiple JVMs for multiple applications.

As shown in Table 10-6, formsweb.cfg is configured with four configuration sections.

Table 10-6 Multiple JVMs for Multiple Applications

Named Configuration Section JVM Configuration

default

jvmcontroller=commonJVM

ordersApp

None

hrApp

jvmcontroller=hrJVM

salesApp

jvmcontroller=

If a user starts an ordersApp application, and the application executes Java code, the Forms runtime process will route the request to the JVM controller named commonJVM. Because the [ordersApp] application section does not specify which JVM controller to use, the Forms runtime process uses the global one. If the JVM controller is not 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 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 is not started, it will be dynamically started. When a second user starts the same application, it too will attach to hrJVM.

When a user starts a salesApp application and it executes Java code, the 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 10-6:

Figure 10-6 Multiple JVMs for multiple applications

multiple JVMs for multiple applications
Description of "Figure 10-6 Multiple JVMs for multiple applications"

10.9 JVM Controller Logging

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

  • The values of the JVM parameters (maxsessions, classpath, and so on);

  • When a JVM controller starts and stops;

  • When a child JVM is spawned;

  • When an Forms runtime process starts a new connection, along with its process ID

    This is useful for knowing which Forms runtime processes are connected to which JVM controller for diagnostics or administration;

  • When an Forms runtime process session ends and disconnects from the JVM.

This section contains the following:

10.9.1 Specifying JVM Default Logging Properties

Use Fusion Middleware Control to manage the properties for JVM controller logging.

  1. In the JVM Configuration page, select the the JVM configuration section.

  2. For the Logging parameter, enter On or Off.

  3. Click Apply.

10.9.2 Specifying the JVM Log Directory Location

You can specify the log file directory in the 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:

  1. Create a JVM controller. For more information, see Section 10.8.2.2, "Creating a New Configuration Section" or Section 10.8.2.4, "Duplicating a Named Configuration".

  2. Add the Log Directory parameter. For more information, see Section 10.8.3, "Managing Parameters."

    If you have duplicated a named configuration section that has Log Directory parameter defined in it, you can edit the existing parameter as given in the Section 10.8.3, "Managing Parameters."

  3. Click Apply to save the changes.

    The JVM Configuration page reappears.

10.9.3 Accessing Log Files

When the log file exists, an icon is displayed in the Logfile column.

To access a log file:

  • Click the Log File link in the Logfile column that is available for that JVM controller.

    The Log File page appears and displays the log information.

10.9.4 Deleting a Log File for a JVM Controller

Use Fusion Middleware Control to delete log files.

To delete a log file for a JVM controller:

  1. From the JVM Controllers page, select the the target JVM.

  2. Click Delete Logfile.

    The Delete Confirmation dialog appears.

  3. Click Delete.

    The logfile is deleted and the JVM Controllers page reappears.

Note:

If you delete a log file of a JVM that is running, the log file will be available again when the JVM is restarted. Logging is possible only when the JVM is restarted.

10.10 Integrating Forms and Reports

JVM Controller (dejvm) is used for Reports integration in Forms. All requests related to Reports such as running a report on Reports Server, getting the status of a Report, getting Reports output, or cancelling the job submitted to Reports Server are routed to the dejvm for dejvm-enabled runform to make calls to Reports.

To use dejvm for reports integration, perform the following steps. These settings are not required when Oracle Forms makes Reports call directly.

To use dejvm for Reports integration:

  1. Enable JVM pooling in formsweb.cfg. For more information, see Section 10.8.6, "Forms Configuration File Settings".

  2. Two additional .jar files are required by dejvm for Reports integration. Set the classpath in jvmcontrollers.cfg to include these jars: zrcclient.jar ($ORACLE_HOME/jlib/zrclient.jar) and rwrun.jar ($ORACLE_HOME/reports/jlib/rwrun.jar).

Note:

If you want the Reports Server name to be returned when running a report using JVM controller, then the REPORTS_SERVERMAP environment variable must be defined in jvmcontrollers.cfg as shown below:

[myjvm]
jvmoptions=-DREPORTS_SERVERMAP=<value> <other-jvmoption-parameters>

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