Configuration Utilities and Options

The OC4J wizards initially configure OC4J at installation time. Therefore, applications can generally be deployed to the server "out of the box." However, default settings for both the OC4J instance and deployed applications can be modified. Although changes can be made by manually editing the XML configuration files and using dcmctl and opmnctl , the web-based Application Server Control (ASC) utility is easiest . In this section, we'll cover the tools to configure the OC4J instance and its processes. Modifying specific properties for a deployed application will be covered in Chapter 18.

As covered in Chapter 16, ASC is started with the emctl command and is accessed via http://hostname.domain:1810 with the ias_admin user account. Once you're at the mid- tier instance home page, each OC4J instance within that installation has a link to its home page. Click the home OC4J container link. This brings up the OC4J:home instance home page, as shown in Figure 17-4.

Figure 17-4: OC4Jhome instance home page

This page provides up or down status, start time, and CPU and memory utilization metrics for the instance. It also provides statistics for JDBC usage and response-time metrics for Servlets, JSPs, and EJBs. If the OC4J instance doesn't use any of these components , the values will be 0. Buttons to stop and start and restart just this individual OC4J instance are located in the center of the page. From this page there are links to applications and administration.

The JVM 1 indicates that there's one OC4J process for this OC4J instance. It also implies that there's one JVM for this instance because there is a one-to-one ratio of JVMs to OC4J processes. This number acts as a clickable link to the Virtual Machine Metrics page shown in Figure 17-5.

Figure 17-5: Virtual Machine Metrics page

This page shows the same CPU and memory utilization statistics and active request information for Servlets, JSPs, and EJBs as the instance home page. However, what makes it useful is that it also shows the process ID (PID) for each OC4J process for this instance and the island it belongs to. You can see that PID 30154 is servicing the OC4J instance home and you can confirm it on the command line, as shown here:

 $ ps -efl  grep 30154  grep -v grep 000 S oracle   30154     1  0  75   0    - 69803 rt_sig Feb01 ?        00:00:01 /u01/app/oracle/product/9.0.4mt1/OraHome1/jdk/bin/java -server -Djava.security.p 040 S oracle   30155 30154  0  75   0    - 69803 schedu Feb01 ?        00:00:12 /u01/app/oracle/product/9.0.4mt1/OraHome1/jdk/bin/java -server -Djava.security.p $ 

The PID 30154 is the fourth column. We also see that PID 30154 has spawned a child process called 30155. Being able to associate a PID with a specific OC4J instance is useful in cases in which a utility such as top shows a busy process, but you don't necessarily know what component it's supporting.

The Applications link on the OC4J home instance home page takes you to the Deployed Applications page shown in Figure 17-6.

Figure 17-6: Deployed Applications page

This page shows which applications are deployed to this particular OC4J instance. Here you can see that one Web Cache and two Business Components for Java (BC4J) applications have been deployed by default to the home instance. Metrics for each application are displayed. Buttons to add a new application in the form of an EAR or WAR file exist. Additionally, you'll see Edit, Undeploy (remove), or Redeploy buttons to be used on any of the existing applications. These options are covered in greater detail in Chapter 18.

The Administration link on the OC4J home instance home page takes you to the Administration page shown in Figure 17-7.

Figure 17-7: Administration page

The Administration page is composed of three sections: Instance Properties, Application Defaults, and Related Links. Tools available in the Application Defaults section will be covered in Chapter 18. The Related Links section has only one link to the BC4J configuration. Your main interest is the following utility pages available in the Instance Properties section:

• Server Properties

• Website Properties

• JSP Container Properties

• Replication Properties

• Advanced Properties

The Server Properties link is a large page shown in Figures 17-8 and 17-9. It's informational and allows for configuration changes. The first two key sections, General and Multiple VM Configuration, are displayed in Figure 17-8.

Figure 17-8: Server Properties General and Multiple VM Configuration sections

Figure 17-9: Server Properties page Command Line Options section

The General section lists the name of the instance ( home ) and paths to key configuration files such as server.xml . It identifies the server root location as $ORACLE_HOME/j2ee/home/config . Configuration files are located in this directory, but as you'll see, you can edit these files via ASC in the Advanced Properties page. The Application and Deployed Application directories listed are relationally located from the Server Root directory, so they would exist in $ORACLE_HOME/j2ee/home/config .

The Multiple VM Configuration section allows you to create additional islands and specify additional processes for the instance. This is where the default of one process (with the 1 JVM) could be modified. Simply edit the value (we increased it to 4 as a test), click the Apply Changes button at the bottom of the page, and then restart the OC4J instance from the home instance home page. Once the home instance has restarted, the new value for processes and the PIDs will be reflected in the Virtual Machine Metrics page.

Additional islands of process can be created with the Add Another Row button within Multiple VM Configuration. After clicking the button, enter the name of the island and the number of processes for it. We called it island_2 with three processes (for a total of three JVMs). After clicking the Apply button at the bottom of the page the new island is supposed to be started automatically, however we also restarted the OC4J container. The Virtual Machine Metrics page now shows each island ( default_island and island_2 ) and the PIDs for each. There are now four default_island processes and three island_2 processes, as can be seen in Figure 17-9.

One good feature of 10g AS is the increased flexibility with port allocation. Instead of being hard-coded to use only one specific port, a range of ports is defined. OC4J will start at the low end of the range and try each port until it finds one that's available. This reduces contention problems for an individual port because 10g AS is "smart" enough to use another if its first choice is already taken. As you can see in the figure, there are large port ranges defined for RMI, JMS, and AJP. Ports can also be defined for Internet Inter-Orb Protocol (IIOP).

The Command Line Options section of the Server Properties page is shown in Figure 17-9.

OC4J can be started with special options and environment variables . These would be useful in debugging situations or if you wanted to use a different Java executable. You can also increase maximum and minimum Java memory heap size for each JVM. For example, placing the following text in the Java Options box would set the JVM size to a minimum 256 MB with a maximum size of 512 MB for each process:

 -server -Xms256m -Xmx512m 

Be sure to specify the -server option to force the more robust server JVM instead of the smaller client JVM. Of course, you also need to make sure your total JVM size doesn't exceed the memory resources available on your machine. Other options controlling stack size, thread synchronization, and performance-metrics collections are also available.

The Website Properties page, shown in Figure 17-10, lists the URLs for each deployed application with links to the application-specific configuration page. It also has a column called Load on Startup with check boxes. This allows application code classes to be loaded into memory at OC4J startup rather than the first time the application is executed. It's essentially a performance boost for the first user of an application.

Figure 17-10: Website Properties page

Settings for JSP components are shown in Figure 17-11. This page is actually located in the Web Module: Global Web Module page in the Application Defaults section, but the link is within the Instance Properties.

Figure 17-11: JSP Properties page

From this page you can turn debugging on or off for JSPs. You can also specify whether or not to recompile the JSP, just reload the classes, or simply run in the default mode within the JSP container. Precompilation and XML validation are additional features that can be turned on. You can also specify a different compiler to be used with JSPs.

In clustered configurations with OC4J islands, it's desirable to replicate the session state of an application across the instances. This is to allow fault tolerance for failed processes. This configuration can be seen in Figure 17-12.

Figure 17-12: Replication Properties page

Replication of state can be set for Servlets and JSPs under the Web Applications section. Notice that by setting up this replication, the applications will be automatically loaded on instance startup. EJBs require a different setup and have a separate configuration section.

Although the ASC tool is convenient , it's sometimes desirable to edit configuration files directly, especially when making advanced configuration changes. Due to the necessity of synchronizing files on the file system with the repository, you shouldn't manually edit these files with a text editor such as Notepad or vi. For this purpose, the ASC provides the Advanced Server Properties page, as shown in Figure 17-13.

Figure 17-13: Advanced Server Properties page

This page provides the file system path and links to open and edit the following files shown in Table 17-2.

Table 17-2: Configuration File Descriptions

File	Description
jms.xml	JMS configuration file
global-web-application.xml	OC4J settings for all web modules
rmi.xml	RMI port and log directory configuration file
server.xml	Master configuration file for OC4J; calls all other files
default-web-site.xml	Lists each application, name, load-on-startup flag, and root location

After editing a file, click Apply for the changes to be saved. It's necessary to restart the OC4J instance for the changes to take effect. These and other configuration files are located in $ ORACLE_HOME/j2ee/home/config if you need to review them manually.