|
Oracle® Application Server Forms Services Deployment Guide
10g Release 2 (10.1.2) B14032-03 |
|
 Previous |
 Next |
|
Oracle® Application Server Forms Services Deployment Guide
10g Release 2 (10.1.2) B14032-03 |
|
|
Previous |
Next |
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
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:
Table 7-1 describes the information that is displayed on the JVM Overview page:
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 |
Displays comments about the JVM controller. For example, start time: 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. |
|
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. |
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. |
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:
Click Create JVM Controller.
The Create New JVM Controller page appears.
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. |
Click Apply to create the JVM with these settings.
The Forms JVM Controllers page reappears.
Restart the JVM. See Section 7.5.7.1, "Starting or Restarting a JVM Controller" for more information.
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:
Click the radio button to the left of the target JVM controller.
Click Edit.
The Edit JVM Controller page appears.
Click Delete.
The Confirmation page appears.
Click Yes to delete it.
The Forms JVM Controllers page reappears without the deleted JVM controller.
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:
Click the radio button to the left of the target JVM controller.
Click Edit.
The Edit JVM Controller page appears.
Edit the following information for the new JVM, as described in Table 7-3, "JVM Controller Property Settings":
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. |
Click Apply to commit the JVM property settings.
The Forms JVM Controllers page reappears.
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:
Click the radio button to the left of the default JVM controller.
The Edit JVM Controller page appears.
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. |
Click Apply to change the default JVM property settings.
The Forms JVM Controllers page reappears.
Enterprise Manager Application Server Control is the recommend 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. Enterprise Manager Application Server Control does this step for you.
To start a JVM controller that is not running:
Click the radio button to the left of the target JVM controller.
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:
Click the radio button to the left of the target JVM controller.
Click Restart.
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
Click the radio button to the left of the target JVM controller.
Click Stop.
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.
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.
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.
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 |
|---|---|
|
|
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 |
|
|
The maximum number of Forms runtime processes that a JVM can service before creating a child JVM. If 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. |
|
|
Location for the log file. The log filename will be automatically generated and will be |
|
|
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. |
|
|
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. |
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.
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.
|
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:
The JVM controller looks in the default section of jvmcontrollers.cfg and applies any options that are specified there.
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.
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.
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.
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 |
|---|---|
|
|
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. |
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:
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.
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.
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.
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.
