Managing OC4J Using Enterprise Manager Oracle Application Server Tips by Burleson Consulting

Oracle recommends that you manage all instances and component parameters using Enterprise Manager (EM).  Once you log onto EM, select the link for the instance you are working on to go to the Instance Status Page.

OC4J ? Instance or Container

OC4J is Oracle?s implementation of a Java Container to hold EJBs and Web Components.  In Oracle9iAS there are a lot of instances.  Database Administrators get very confused with all the instances in Oracle9iAS.  For this reason, I will refer to the container when referring to a particular OC4J instance, and refer to the instance as the Application Server Instance to try and avoid some confusion.  Thus, an Oracle9iAS Instance contains many OC4J containers, rather than many OC4J instances.

Figure 1: Enterprise Manager Instance Status Page.

In the System Components listing in Figure 1 is a list of components installed for that instance, including a number of OC4J containers.  To look at the status page for a component, simply select the name link in the component list.  Before leaving this page however, we want to create an OC4J container for our test application. 

Creating an OC4J Container

Simply click the Create OC4J Instance button in the upper right of the System Components listing.  This starts the Create OC4J Instance wizard and asks you for a name for this container (Figure 2).

Figure 2: Create OC4J Instance Wizard.

Enter the name for this OC4J container and select Create.  The Create OC4J Instance wizard creates the container and notifies you when it is completed.

Figure 3: Creating a OC4J Container Using the Wizard.

Once the wizard is finished, select OK to return to the Instance Status Page.  The newly create OC4J container is now listed in the System Components section. 

Deleting an OC4J Container

Deleting an OC4J container is just as easy.  Select the radio button for the OC4J container to delete and then select the Delete OC4J Instance button in the upper-right of the System Components area.  EM will display a verification page; selecting OK will delete the OC4J container.  Note that if you have components deployed in this container, they are removed along with the container.  Don?t accidentally delete the wrong container!

Starting an OC4J Container

Notice that the container we just created is currently not running.  This is indicated by the red down-arrow in the Status column.  Before using the container you must start it. 

Figure 4: Application Server Instance Status Page.

Select the container?s radio button and then select Start in the upper right of the System Components area.  This is a relatively quick operation because we have not deployed our application yet.  Selecting the name link for the new container ?OC4J_Testing? will display the container?s home page. 

OC4J Home Page

Selecting the name link for an OC4J container will display the container?s home page (Figure 6).  The home page for our new OC4J container does not have much information to display because we just started it and there are no components deployed, except from transtrace.  Transtrace is an EBJ that interfaces with opmn to provide status and performance statistics.  It is deployed in every OC4J container and is preconfigured.

Figure 5: OC4J Home Page

As you scroll down to the bottom of the OC4J Home Page you find the Administration section.  Like the Instance Status Page, the Administration allows you to configure the OC4J container.  The sections map back to the server files we introduced at the beginning of this chapter.  In the Administration section of the OC4J home page, select Server Properties.  This section tracks with the server.xml file, among others.

server.xml
<?xml version="1.0"?>
<!DOCTYPE application-server PUBLIC "-//Evermind//DTD Orion Application
server//EN" "http://xmlns.oracle.com/ias/dtds/application-server.dtd">

<application-server localhostIsAdmin="true"
 application-directory="../applications"
 deployment-directory="../application-deployments"
 connector-directory="../connectors"
> 
  <rmi-config path="./rmi.xml" />
  <sep-config path="./internal-settings.xml" />
  <jms-config path="./jms.xml" />
  <javacache-config path="../../../javacache/admin/javacache.xml" />
  <log>
    <file path="../log/server.log" />
  </log>
  <transaction-config timeout="30000" />
  <java-compiler name="javac"
    in-process="false"
    extdirs="/home/oracle/oraportal904/jdk/jre/lib/ext" />
  <global-application name="default" path="application.xml" />
  <application name="transtrace"
     path="../../../diagnostics/lib/transtrace.ear"
     auto-start="true" />
  <application name="petstore"
     path="../applications/petstore.ear"
     auto-start="true" />
  <global-web-app-config path="global-web-application.xml" />
  <web-site default="true" path="./default-web-site.xml" />
  <cluster  id="-1402673903" />
</application-server>

You should not modify the flat files, rather you should user Enterprise Manager GUI to configure OC4J.  But before jumping to EM, I want to point out some important points with the server.xml file.  Notice that in the last chapter we deployed an application archived in an EAR file called petstore.  This is a J2EE application built by Sun to demonstrate the concepts of J2EE.  Oracle has modified the original application to connect to an oracle database.  It is available on Oracle Technology Network at otn.oracle.com.  Notice that one of the things that happened when we deployed the EAR file was that a number of files were updated.  In the server.xml file we find:

  <application name="petstore"
     path="../applications/petstore.ear"
     auto-start="true" />

This tells OC4J the application name and where to find it. Manually deploying a J2EE component is complicated because of the different files that need to be updated to support the application.  Always use some automated tool (dcmctl, Enterprise Manager, JDeveloper, etc) to deploy WAR and EAR files into OC4J containers. 

Like the Instance Status Page, the OC4J Home Page has an Administration section.  This is an area where you will find almost all the OC4J configuration parameters.

Figure 6: OC4J Home Page Administration Section

This section is divided into two areas, one related to the OC4J container and the other to the applications running inside the container.  Using the OC4J container we created earlier, OC4J_Testing, let?s look at how this container is configured. 

Server Properties Page

Selecting the Server Properties link takes you to the properties page in Figure 7.

Figure 7: OC4J Server Properties Page     

At the top is the Server Root, which is the location for all the configuration files for this OC4J container.  Below is a listing of the configuration files located in Server Root.

application.xml
data-sources.xml.smibak
default-web-site.xml
global-web-application.xml
http-web-site.xml
internal-settings.xml
java2.policy
jazn-data.xml
jazn-data.xml.smibak
jazn.xml
jms.xml
mime.types
oc4j-connectors.xml
oc4j.properties
principals.xml
rmi.xml
server.xml

When you make a change in EM, the change is updated to the flat file, so if you examine the server.xml file it will match the data in the EM repository.  Remember that if you edit the flat file, the change does not get propagated into the repository and could cause corruption in the repository.  Some of these files are the same as the deployment files in the EAR file, such as application.xml.  These files provide default configuration information to the OC4J container that the file in the EAR will overwrite.  The Default Application Name is ?default?.  All applications deployed into this OC4J container will be subclasses of the default application.  Next, is the Default Web Module Properties file, here defined as global-web-application.xml.  This file is located in the Server Root.  To modify the parameters defined in this file, return to the OC4J Home Page and select Website Properties and/or Advanced Properties links.  Further down, you will find the Application Directory and the Deployment directory, both off the./OC4J_Testing directory.  The Application Directory is where you can find the actual components that make up the application (the EAR components), while the Deployment directory contains all the deployment descriptor files that have had default values added to them.  Both follow the subdirectory structure of the EAR file. 

Next is the Multiple VM Configuration section, which is part of Oracle9iAS Clustering.  This will be discussed in detail in Chapter 9 High Availability.    There are two parameters listed under Islands, the Island ID and the Number of Processes.  The Island ID is the instance of the clustered OC4J container.  In this case, we are not using Oracle Clustering, so there is only one Island, the default_island.  There is also only one process for the default island.  You can increase the number of processes to add fault tolerance to the OC4J container.  If you define more than one processe and that process fails, the container will continue to support the application with the other processes.  To change the number of processes, simply change the Number of Processes and click on the Apply button at the bottom of the screen. 

The remaining parameters were set when the instance was created and should work without being changed.  The Ports section defines a range of ports to use for Remote Method Invocation (RMI), the Java Messaging Service (JMS), the Apache JSP/servlet communication API (AJP), and the RMI-IIOP.  RMI-IIOP allows interoperability between Java programs and programs written in other languages, like C++.  Each of these parameters has a range of ports defined for them.  We will discuss ports later in the chapter under OC4J Listeners. 

The Command Line Options allows you to define arguments for starting Java or the OC4J container.  The final entry allows you to specify an environmental variable for use within the container.  Examples of environmental variables can be displayed by typing ?env? at the command line in Unix/Linux and set in a Windows DOS box.  ORACLE_SID or ORACLE_HOME are good examples of environmental variables.  If our application had logging capabilities, we could use an environmental variable to tell the program what level to log, such as PET_LOG=debug during development or troubleshooting.  Once you make configuration changes, click the Apply button to make them permanent. If the container needs to be restarted, EM will automatically take care of that.

 
This is an excerpt from "Oracle 10g Application Server Administration Handbook" by Don Burleson and John Garmany.