Creating, Copying, and Managing OC4J Instances

In this second part of a multi-part series covering the management of OC4J and configuring J2EE applications with Oracle 10g Application Server, we focus in on OC4J instances. This article is excerpted from chapter eight of the Oracle 10g Application Server Exam Guide, written by Sam Alapati (McGraw-Hill; ISBN: 0072262710).


Creating an OC4J Instance

Each OracleAS instance is created with a default OC4J instance named home, as shown here:

$ opmnctl status
Processes in Instance:
ias-component | process-type | pid | status
LogLoader     | logloaderd   | N/A | Down
DSA           | DSA          | N/A | Down HTTP_Server   | HTTP_Server  |3744 | Alive dcm-daemon    | dcm-daemon   |7176 | Alive OC4J          | home         |6268 | Alive OC4J          | oca          |9164 | Alive OC4J          | OC4J_SECURITY|7596 | Alive OID           | OID          |7172 | Alive $

You can create a new OC4J instance either by using the command-line utility dcmctl, or by using the Application Server Control. Let’s review the creation of a new OC4J instance using both methods in the following subsections.

Using the dcmctl Utility

You can use the dcmctl command-line utility to perform several OC4J administration tasks, including the following:

  1. Deploying and undeploying an application
  2. Creating and destroying an OC4J instance
  3. Listing applications
  4. Resynchronizing an OC4J instance
  5. Starting and stopping an OC4J instance
  6. Updating an OC4J instance configuration

You use the dcmctl utility with the createComponent option to create a new OC4J instance. The standard syntax for using the dcmctl command is as follows:

  $ ORACLE_HOME/dcm/bin/dcmctl command [options]

You can use the dcmctl command with various options. You use the createComponent option to create a new OC4J instance, as shown here:

  $ dcmctl createComponent -ct oc4j -co component_name

In the dcmctl command, the two options denote the following:

  • -ct (component type) is a scope option that specifies that the dcmctl command be applied to the named component type, which in our case is oc4j.
  • -co (component name) is also a dcmctl scope option; it designates the name of a component during the creation of that component.

Here’s an example showing how to create a new OC4J instance (the command type is oc4j, of course, and the component name—that is, the name of our new OC4J instance—is OC4J_Test):

  $ dcmctl CreateComponent -ct oc4j -co OC4J_Test
  Component Name: OC4J_Test
  Component Type: OC4J
  Instance: $

To check that the new OC4J instance, OC4J_Test, has been successfully created, use the ListComponents option of the dcmctl utility, as shown here:

  C:OraHome_2dcmbin> dcmctl ListComponents
  Component Name: home
  Component Type: OC4J
  Component Name: HTTP_Server
  Component Type: HTTP_Server
  Component Name: oca
  Component Type: OC4J
  Component Name: OC4J_SECURITY
  Component Type: OC4J
  Component Name: OC4J_Test
  Component Type: OC4J
  Component Name: OID
  Component Type: OID

The dcmctl listComponents command returns a list of all OracleAS components within the scope you specify. If you don’t specify the scope (i.e., use the command without any arguments), you’ll get a list of all OracleAS components in that instance. If you’re using dcmctl shell, you can limit the list of components using a pattern. In the following example, I use "4" as a pattern matcher in order to get a list of all OC4J instances within an OracleAS instance:

  $ dcmctl listComponents *4*

To remove an OC4J instance with the dcmctl utility, use the dcmctl command with the removeComponent option (co again stands for the component name):

  $ dcmctl removeComponent -co nameOfOC4JInstance

on the job:  When you create a new OC4J instance, the OC4J instance isn’t automatically started. You must start the new instance either through Application Server Control or through the opmnctl utility.

Sometimes, you may have to remove an entire OracleAS instance using operating system commands (by removing the files and directories belonging to the OracleAS installation). When you adopt this much wider-scoped procedure to remove an OC4J instance instead of using the removeComponent command just shown, the DCM repository will continue to retain the removed OC4J instance’s information. This information may potentially hurt you during a subsequent reinstallation of OracleAS. You can use the destroyInstance command to clear the repository of all information pertaining to the removed OracleAS instance, as shown here (-i stands for the OracleAS instance name):

When you execute the following command, the dcm.conf file, the targets.xml file, and the repository directory are all automatically purged of all the OracleAS instance–related information:

  $ dcmctl destroyInstance -i instance1

{mospagebreak title=Using the Application Server Control}

Using the Application Server Control is the recommended way to create a new OC4J instance. You can create a new OC4J instance using the Application Server Control by following these steps:

  1. Go the System Components table and click the Create OC4J Instance button, which is shown in the upper right-hand corner of Figure 8-1.
  2. Provide a name for the new OC4J instance in the page that comes up.
  3. Click the Create button.
  4. Application Server Control will confirm that the new OC4J instance was created.

When you create a new OC4J instance, either through the dcmctl utility or through the Application Server Control, a new directory will be created with the name of the new OC4J instance under the $ORACLE_HOME/j2ee directory. In our case (refer to the OC4J creation example using the dcmctl utility), this directory’s name would be OC4J_Test.

Figure 8-1.  Creating an OC4J Instance

{mospagebreak title=CERTIFICATION OBJECTIVE 8.04}

Managing the OC4J Instance

You can manage OC4J with the Application Server Control or OPMN, in addition to the DCMCTL utility. The recommended approach is to use the Application Server Control for performing day-to-day management of the OC4J instances. The Application Server Control makes the creation and management of OC4J instances a snap. However, you can also use the command-line utilities opmnctl and dcmctl to manage the OC4J instances noninteractively. These tools are ideal when you are using scripts to perform batch jobs, or for scheduled maintenance jobs. Let’s start by reviewing OC4J instance management using the two command-line utilities opmnctl and dcmctl, and then go on to learn how to use the Application Server Control for managing an OC4J instance.

Using OPMN

You use the opmnctl command-line utility to stop and start OC4J instances. As you may recall from Chapter 3, when you use the opmnctl utility with the ias-component option, you start or stop all subprocesses of a component. In this case, using the ias_component option, you can start and stop all OC4J instances running in an OracleAS instance, as shown here:

  $ opmnctl startproc ias_component=OC4J
  $ opmnctl stopproc ias_component=OC4J

These two commands will start and stop all the OC4J instances in an OracleAS instance.

By using the process-type option, you can start and stop a specific OC4J instance. Here I show how you would start and stop a specific OC4J instances (named oc4J_Test) using opmnctl:

  $ opmnctl startproc process_type=OC4J_Test
  $ opmnctl stopproc process_type=OC4J_Test

Note that these two commands will start and stop the single OC4J instance, OC4J_Test, respectively.


Earlier in this chapter you learned how to create and delete OC4J instances using the dcmctl utility. You also learned how to use the listComponents command to list all the applications deployed in an OC4J instance. The dcmctl utility contains commands you can use to deploy an OC4J application, as you’ll see later in this chapter.

{mospagebreak title=Using the Application Server Control}

Every OC4J instance, including the new OC4J instance OC4J_Test that you created earlier, will have its own OC4J home page. You can perform the following OC4J management tasks using the Application Server Control Console:

  • Start an OC4J instance.
  • Configure an OC4J instance.
  • Manage the data sources and security.
  • Monitor the availability, usage, and performance of the OC4J instance.
  • Stop an OC4J instance.
  • Restart an OC4J instance.
  • Disable and enable an OC4J instance.

Figure 8-2 shows the OC4J home page in the Application Server Control Console.

Following are the main sections of the OC4J home page:

  • The General section shows a snapshot of the status of the OC4J server and also lets you stop and start the OC4J server.
  • The Status section shows a summary of the performance of the server, including CPU and memory usage.
  • The JDBC Usage section shows information about the open JDBC connections and active transactions, rollbacks, and commits.
  • The Response–Servlets and JSPs section shows details about the response times for processing requests, the active sessions, and the active requests.
  • The Response-–EJBs section shows EJB transactional details.

    Figure 8-2.  The Application Server Control OC4J Home Page

You can start and stop the OC4J instance from either the Application Server Control Instance home page or the OC4J home page, by clicking on the Start and Stop buttons. Note that you can also start and stop OC4J instances from the Oracle Application Server Control Instance home page as well. If you wish to disable an OC4J instance, you can do so by clicking the Enable/Disable Components in the OracleAS Instance page. Similarly, you can reenable a disabled OC4J instance from the Enable/Disable Components page by removing the selected instance from the disabled components table. However, note that an enabled component won’t start automatically.

You perform most OC4J configuration and management tasks from the OC4J home page. Each of the OC4J instances will have its own home page. You drill down to any OC4J instance home page by selecting the name of the OC4J instance in the System Components table. The OC4J home page has two tabs: Applications and Administration. Clicking on the Applications tab will take you to the OracleAS Console Applications page and clicking on the Administration page will take you to the OracleAS Console Administration page. Let’s briefly review these two pages.

Testing the Default OC4J Instance

To test the default OC4J configuration, specify the following URL in your Web browser:


In the URL, hostname stands for the name of the server on which your Oracle HTTP Server is running, and 7777 is, of course, the default port number for the OHS. If you type the following URL, you should see a "Hello World" greeting. The HelloWorldServlet is part of the OC4J installation.

{mospagebreak title=OC4J Administration Page}

Using the OC4J Administration page, you can perform various OC4J server configuration tasks. You can also access other pages so you can set the directory and file paths for the default application and the configuration file. Under the Instance Properties section, you’ll see a set of links that will take you to the relevant page for configuring the OC4J server, the Web site, and the like. You can edit the key OC4J configuration file (the server.xml XML file) either by using the Server Properties link or by clicking on the Advanced Properties link. Under the Application Defaults section, there are links that enable the configuration of data sources, security, and JMS providers.

Let’s take a brief look at three important links under the Instance Properties section: Server Properties Page, Website Properties, and Advanced Properties.

Server Properties  You can view and edit the OC4J server properties from the Server Properties page, as shown in Figure 8-3. You’ll find the following sections in the Server Properties page:

  • General   Contains the name, server root, and configuration file names, which you can’t change after creating the OC4J instance. The default Web module properties field contains the global-web-applications.xml file. The Applications Directory field is the default directory for the EAR files of deployed applications. The deployment directory field lets you specify the default directory for placing modified module deployment descriptors.

    Figure 8-3.  Server Properties Page
  • Multiple VM Configuration   Helps you configure multiple OC4J Java Virtual Machines.
  • Ports   Enables the configuration of various ports. These ports include Remote Method Invocation (RMI), Java Message Services (JMS), AJP, and RMI-IIOP ports. The JMS, RMI, and RMI-IIOP were explained earlier in this chapter and AJP (Apache Java Protocol) is explained a little later in the chapter. The mod_oc4j module uses the AJP protocol to talk to an OC4J instance.
  • Command-line options   Lets you configure Java executable commands.
  • Environment variables   Helps set the environment for the OC4J instance.

Website Properties   The Website Properties home page lets you specify which Web applications are loaded when you start the OC4J instance. The parameters you specify are stored in the configuration file named web-site.xml. The following list gives the two major sections on this page:

  • Default Web Module  This section contains three nonconfigurable fields representing the name of the Web application, the name of the parent J2EE application, and whether the applications should be loaded when you start OC4J. Loading the applications at startup time improves application response time when the application is invoked for the very first time.
  • URL Mappings for Web Modules  This is a table that provides information about all the Web modules contained in the OC4J container. Each module’s name, the URL to which it’s mapped, and whether it should be loaded on OC4J instance startup is specified in this section.

Advanced Properties  You can view and edit any OC4J configuration file using the Advanced Properties page, as shown in Figure 8-4. As you can see, the Advanced Properties page contains a list of all the configurable files along with their locations. Click on server.xml (this configuration file is explained in detail later in

Figure 8-4.  The OC4J Advanced Properties Page

this chapter), for example, if you wish to edit that file. That will take you to the Edit Server.xml page, which you can edit, thus modifying the configuration of the OC4J instance.

You can configure the following configuration files from the Advanced Properties page:

  • server.xml
  • default-web-site.xml
  • rmi.xml
  • jms.xml
  • global-web-application.xml

In addition to the foregoing configuration files, you can edit the following files if you access the Advanced Properties page from an application:

  1. You can edit the application.xml, oc4j-connectors.xml, principals.xml and data-sources.xml files if you access the Advanced Server Properties page from the default application.
  2. You can edit the principals.xml and the orion-application.xml files if you access the Advanced Server Properties page from any deployed application.

All the files mentioned here are discussed later in this chapter.

exam watch:  If you want to modify the global definitions of the data-sources.xml and principals.xml files, you must  modify them under the default application. If you want to modify them only locally, you must modify them under the deployed application

{mospagebreak title=OC4J Applications Page}

The OC4J Applications page lets you deploy and maintain Web applications. Using this page, you deploy WAR files or new OC4J applications. When you deploy a new WAR file, the WAR application is automatically wrapped by the Application Server Control into a J2EE application—that is, into a .ear file. This .ear file is used to deploy the Web application’s WAR file. After you deploy a new WAR application,

exam watch:  The default application is the parent application for all applications in an OC4J instance.

its name will appear in the form of a .ear file in the Deployed Applications table on the OC4J Server Applications page. The Deployed Applications table shows the name, path, and parent application of all deployed applications as well as the application’s performance metrics, such as the number of active requests and request processing time.

You can deploy a new .ear file to a single OracleAS instance, or it can be simultaneously deployed to several OC4J instances that are part of a cluster.

You can undeploy a WAR file by using the OC4J Applications page. If you wish to redeploy an application, you can’t use the Applications page directly. In order to redeploy an application, you must first undeploy the application and deploy it again. Here are the steps for redeploying a WAR file:

  • Click the Applications tab in the OC4J home page.
  • Select the application you wish to deploy from the Deployed Applications table.
  • Click the Undeploy button.
  • Click the Deploy WAR file. You must use the name of the original application you undeployed before performing this step.

    on the job:  You can’t manage OC4J instances using the OC4J standalone tool admin.jar. However, you can manually modify the XML configuration files and then use the dcmctl tool to notify the Application Server that the files were edited by you directly. The dcmctl command to do this is dcmctl updateconfig -ct oc4j.

exam watch:  In order to deploy, redeploy, or undeploy a J2EE application, the application files must be archived in an EAR or WAR file archival format.

You will learn how to deploy Web and J2EE applications using the OC4J Applications page later in this chapter.

{mospagebreak title=CERTIFICATION OBJECTIVE 8.05}

Configuring OC4J

When I mention configuring OC4J, I mean something broader than merely configuring the OC4J server itself. Our main motivation in learning about the OC4J server is to learn how to deploy J22 applications with it. Thus, configuring OC4J involves the configuration of the OC4J server itself, as well as the configuration of the J2EE applications framework. In addition, you must configure the mod_oc4j module, which lets the Oracle HTTP Server communicate with the OC4J server instance.

An OC4J instance has three groups of configuration files: mod_oc4j configuration files, OC4J server configuration XML files, and the J2EE application deployment XML files. As you can tell, you use the first set of files to configure the interaction of the mod_oc4j module with the Oracle HTTP Server. You use the second set of files to configure the OC4J server proper, and the last set of configuration files to configure the deployment of J2EE applications via the OC4J server. These three groups of configuration files are reviewed in the following subsections.

on the job:  Port number 7777 is the default port for the Oracle Web listener. You must specify the port number if you are using a non-default port number. However, OracleAS Web Cache uses port 7777, and the HTTP server will actually be listening on port 7778.

on the job:  You can’t modify J2EE XML files such as web.xml and ejb-jar.xml after deploying an application. You can, however, modify the OC4J-specific XML files of the application.

The mod_oc4j Configuration Files

The mod_oc4j HTTP server module facilitates communication between the Oracle HTTP Server and the OC4J instance and enables access to HTTP clients. The mod_oc4j module runs within the HTTP server and performs the following functions:

  • Identifying the requests it needs to serve
  • Determining the particular OC4J instance it should route the request to
  • Communicating with the selected OC4J instance backend processes

OPMN keeps mod_oc4j aware of the status of the instances, and thus, oc4j will route jobs only to the running processes. Because mod_oc4j is aware of the OracleAS

exam watch: The mod_oc4j module is embedded in the Oracle HTTP Server module and is in charge of forwarding OC4J requests from clients. The mod_oc4j.conf file configures the mount points or virtual paths specifying the contexts that it should forward to the OC4J instance. 

Clusters and OC4J islands (an OC4J island is a set of OC4J processes that replicates session state among all the OC4J processes that are part of the island) the OC4J processes can run on multiple nodes, and its routing is calculated to provide transparent failover as well.

By default, the mod_oc4j module will direct all j2ee/ context-bound applications to the OC4J server. You can, however, add other mount points for this context in the mod_oc4j. conf file, if you plan on using other contexts (for example, test/). Once you start your Oracle HTTP Server, the context changes will be in effect and all new requests for the test/ context will be sent to the OC4J server.

The mod_oc4j configuration files are located in the following directory:


Here’s a typical mod_oc4j configuration file, named oc4j.conf:

########################################## # Oracle iAS mod_oc4j configuration file: mod_oc4j.conf ########################################## LoadModule oc4j_module modules/ApacheModuleOc4j.dll
<IfModule mod_oc4j.c>
    <Location /oc4j-service>
         SetHandler oc4j-service-handler
         Order deny,allow
         Deny from all
         Allow from localhost ntl-alapatisam
Oc4jMount /j2ee/*
Oc4jMount /forms90 FORMS_PROD

Let’s briefly analyze the oc4j.conf file, which is called as part of the Oracle HTTP Server configuration file httpd.conf.

  1. The LoadModule directive tells the Oracle HTTP Server that the oc4j_module should be loaded each time the Oracle HTTP Server starts.
  2. The <IfModule> directive tells the HTTP server what it should do when it encounters the oc4j_module in the httpd.conf file, which is the configuration file for the Oracle HTTP Server.
  3. The <Location> directive specifies the virtual path /oc4j-service, which will launch the oc4j-service handler, but only if the URL comes from the address specified within the Location directive.
  4. The lines starting with the Oc4jMount command help set the URL mapping. The Oc4jMount command lines specify the virtual paths for mod_oc4j to route to a particular OC4J instance. For example the virtual path /j2ee/* belongs to the OC4J home instance. Any request that contains the regular expression /j2ee/* is then routed to the home OC4HJ instance. In this example, the URL mapping for this OC4J instance makes the Oracle Application Server route all requests for /forms90 FORMS_PROD to this OC4J instance. You can look at this as the rough mod_oc4j equivalent of an OHS Alias. All deployed J2EE applications must be associated with a "root context" (an URL prefix), which serves to identify the requests that need to be handled by mod_oc4j. The Oc4jMount command maps the root context to the particular OC4J instance to which an application is deployed.

Please check back next week for the continuation of this article.

Google+ Comments

Google+ Comments