Oracle9iAS Containers for Java Oracle Application Server Tips by Burleson Consulting

The heart of Oracle9iAS is the Oracle Container for Java (OC4J).  This container runs on Java version 1.4.1_03 or later, thereby leveraging the feature and performance enhancements this release provides for different operating systems.  As we saw in the previous chapter, OC4J provides a servlet container and a JSP Translator.  OC4J is also J2EE certified and provides all the required J2EE Standard Interfaces.   Of course, OC4J also provides support for Enterprise JavaBeans, including standard deployment of EAR and WAR archives.  The OC4J container provides EJB services, including database access, transaction support, security, caching, and concurrency.     Entity EJBs can use OC4J Container Managed Persistence (CMP) to access persistent storage (databases) through the container without using the JDBC API.  OC4J?s ability to transparently map an Entity EJB to the database relieves the programmer from creating this connection.  OC4J provides support for both simple and complex Object ? Relational mapping, including objects like BLOBs, CLOBs, and collections (nested tables and VARRAYs).  Container managed persistence is also enhanced by using Toplink.  Database connectivity is discussed in Chapter 8 Object Relational Mapping with Oracle9iAS.

Management of OC4J

There are a number of configuration files needed to manage the OC4J container.  Some, like application.xml and web.xml, are J2EE standard packaging files and are used to establish default values that may be overwritten by the files deployed in an EAR or WEB file.  Some are application configuration files, while the rest configure OC4J itself.  Many are updated when EAR and WAR files are deployed, which is why most development programs use an automated method to deploy the application (like using Enterprise Manager (EM) in the last chapter).  The following table contains a listing of some of the standard configuration files.

Server Configuration

	server.xml	Used to Configure OC4J, identify other configuration files and application names
	application.xml	Defines Web and EJB default parameters for components within a J2EE application.
J2EE Package Files	application.xml	Same as above except deployed in an EAR file.  During the deployment it is updated to contain default values that it does not overwrite.
	web.xml	Deployment descriptors for JSPs and Servlets
	ejb-jar.xml	Deployment descriptors for EBJs within a JAR
	application-client.xml	Contains JNDI Information
OC4J Deployment Files	orion-application.xml	Configures default application parameters such as data sources, security role mappings and JNDI access rules
	orion-web.xml	Deployment descriptor for mapping Web settings
	orion-ejb-web.xml	OC4J specific deployment descriptor for EBJs in a JAR
	orion-application-client.xml	OC4J specific file JNDI mappings of client information.

You do not need to know what each of these files does or the data it contains because you should not be directly editing any of these files.  Your development environment should automate the creation and maintenance of deployment descriptor files within the EAR and WAR archives, and you should always use Enterprise Manager or the dcmctl utility to configure OC4J parameters.  Manually changing configuration files will corrupt the configuration repository, possibly causing you to reinstall the application server.  If you do manually update configuration files, execute the command:

dcmctl ?updateConfig ?ct oc4j

This will update the configuration repository.  Or, use EM?s advanced properties pages to edit the files internal to EM, allowing EM to automatically update the repository.  Editing configuration files directly or inside EM could also cause the instance to not be able to start because of a typo or a missing XML tag.  For developmental purposes you can obtain a stand-alone version of OC4J, however, we do not cover the stand-alone version except to mention that it is available. 

Managing OC4J using the DCMCTL/OPMNCTL Utilities

There are times when you need to maintain OC4J from the command line.  An example of this is the creation of scripts that start Oracle9iAS when the server starts. Bringing instances down for backup or maintenance is another.  That is where the DCMCTL and OPMNCTL utilities are useful. 

OPMNCTL

The easiest and recommended way to start and stop instances is with the OPMNCTL utility. 

export ORACLE_HOME=/home/oracle/oraportal904
export PATH=$PATH:$ORACLE_HOME/bin:$ORACLE_HOME/dcm/bin: \
    $ORACLE_HOME/webcache/bin:$ORACLE_HOME/opmn/bin
export ORACLE_SID=iasdb
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib
$ORACLE_HOME/opmn/bin/opmnctl startall

After setting the environment, we execute opmnctl startall. The opmn script will start the instance, in this case ?oraportal904?, which will automatically start the OC4J containers contained in oraportal904.  Once this command completes, you can start the Enterprise Manager web site and connect to EM for maintenance.

$ORACLE_HOME/bin/emctl start em

This was covered in greater detail in chapter 1. One issue with emctl is that to stop Enterprise Manager you must provide a password, which cannot be provided on the command line.  Insure that Enterprise Manager is stopped before shutting down the server.

Distributed Configuration Management

The Distributed Configuration Management can be used instead of EM for some management activities, but not all.  The dcmctl utility only manages the OHS/OC4J portion of the instance.  It can be used within scripts to automate maintenance functions.  If you are working with one instance, you will need to either pass dcmctl, the instance?s ORACLE_HOME variable, or set it before executing the command.  To avoid confusion, I always set my environmental variables in the script before executing either opmnctl or dcmctl.  In a cluster environment, failure to set the appropriate ORACLE_HOME could result in making changes to the wrong instance.  You can also used the environment variable ORACLE_DCM_JVM_ARGS to pass arguments to the Java Virtual Machine.

The dcmctl utility can be started so that commands can be directly entered using the command shell.

$ dcmctl shell
dcmctl> createcomponent -ct oc4j -co OC4J_T2
dcmctl> exit
$

Dcmctl also has an extensive help listing obtained with the help argument.

$ dcmctl help

Dcmctl arguments are made up of a one word command and a set of options, all of which are case insensitive.  Options start with a dash, followed by the option in short or long format, followed by the option?s arguments.  In the example above, the command is createcomponent and the options are ?ct and ?co.  First, let?s discuss the options available and then introduce the commands.  Options have a long and short format.

-a    -application      Application Name
-cl   -cluster          Cluster Name
-co   -component        Component Name
-ct   -componenttype    Component Type
-i    -instance         Instance Name (Oracle9iAS Instance)
-d    -debug            Print Stack Trace on Exception
-l    -logdir           Location for the error log log.xml
-o    -oraclehome       ORACLE_HOME for that command
-t    -timeout          Max time to complete command (default: 45sec)
-v    -verbose          Verbose listing of state and error messages

Now that we have the options defined, we can begin using the commands.  Since dcmctl is used mostly within scripts, we need to be able to start and stop the instances/components. 

$ dcmctl start -i porta904.appsvr.localdomain.com

Current State for Instance:porta904.appsvr.localdomain.com

    Component               Type          Up Status     In Sync Status
=======================================================================
1   HTTP_Server             HTTP_Server   Up            True
2   OC4J_Demos              OC4J          Up            True
3   OC4J_Portal             OC4J          Up            True
4   OC4J_Testing            OC4J          Up            True
5   OC4J_Wireless           OC4J          Up            True
6   home                    OC4J          Up            True

The command above started the porta904 instance.  Notice I used the fully qualified instance name.  The dcmctl utility started the instance and then provided a listing of the current state.  To stop the instance I have two options, the stop command or the shutdown command.  The shutdown command is used to stop the instance and OPMN/DCM, and is used to shut everything down before restarting or shutting down the server.  The restart command will start an already down system, or shut down and restart a running system.  Lastly, the getstate command returns the state of the instance/component.

$ dcmctl stop -co OC4J_Testing

Current State for Instance:porta904.appsvr.localdomain.com

    Component               Type          Up Status     In Sync Status         
=======================================================================
1   OC4J_Testing            OC4J          Down          True

Here, we stopped the OC4J_Testing container using dcmctl.  One dcmctl command has already been introduced a number of times in previous chapters and at the beginning of this chapter.  If you manually change a configuration file, you must update the repository using the updateConfig command. 

$dcmctl updateconfig

This command reads the configuration files and updates the repository data.  You can specify the container as OHS or OC4J with the ?co option.  The default is both.

The dcmctl utility has a number of useful commands to allow you to maintain components inside the application server instances.  To list the component types contained in an instance, use the listcomponenttypes command.  Remember, I have already defined the ORACLE_HOME environment variable.

$ dcmctl listcomponenttypes  
OC4J
Portal
Wireless
HTTP_Server
WebCache

I could have also requested the component type of a component by using the getcomponenttype with a ?co option to define the component.  You can create a component using dcmctl, such as creating an OC4J container in the example below.

$ dcmctl createcomponent -ct OC4J -co OC4J_New
1  HTTP_Server:HTTP_Server
2  OC4J:OC4J_Demos
3  OC4J:OC4J_New
4  OC4J:OC4J_Portal
5  OC4J:OC4J_Testing
6  OC4J:OC4J_Wireless
7  OC4J:home
8  WebCache:WebCacheAdmin
9  WebCache:WebCache

Once created, dcmctl can remove a component.  Note that if you remove an OC4J container that contains web components and EJBs, those components will also be removed.  There is no verification notice to warn you that the container you are removing is not empty.  To remove a component, pass in the component name option.

$ dcmctl removecomponent -co OC4J_New

Now that we can add and remove components, let?s look at how we add applications to a component.  First, after restarting the OC4J_Testing container, list the currently installed applications.

$ dcmctl listapplications -co OC4J_Testing
1  petstore

The OC4J_Testing container has one application installed, called perstore.  It is contained in an EAR file.  In the last chapter we demonstrated deploying an EAR file using Enterprise Manager.  Now let?s deploy the same application, using dcmctl, into the OC4J_New container we just created.

dcmctl deployapplication -file petstore.ear -a petstore -co OC4J_New
$ dcmctl listapplications -co OC4J_New
1  petstore

A script for deploying an application to all containers in a cluster was provided in Chapter 1.

Before leaving the dcmctl utility, there is another useful function that allows you to backup and restore your instances.  It is useful to backup an instance before making changes in case there is a problem.  The saveinstance command will save the instance configuration and any application contained in the instance, including clustering information.  After making changes, you can restore the instance using the restoreinstance command.  This command restores the instance to the state it was saved in.  If you do not specify a directory where the saved state is located, dcmctl will restore the instance to the original installed state.  If the instance is part of a cluster, it will remove it from the cluster when it is restored, so you will need to add it back to the cluster.  We can create a script that saves the state of our instance before we start making changes.

# Customize ORACLE_HOME and ORACLE_SID for this Instance
export ORACLE_HOME=/home/oracle/oraportal904
export PATH=$PATH:$ORACLE_HOME/bin:$ORACLE_HOME/dcm/bin: \
             $ORACLE_HOME/webcache/bin:$ORACLE_HOME/opmn/bin
export ORACLE_SID=iasdb
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib
dcmctl saveInstance -dir /home/oracle/saveDir
ls ?l /home/oracle/saveDir

The file listing command at the end of the script produces the following output:

total 44
drwxrwx---    4 oracle   oracle       4096 Aug 19 11:20 dcm
-rw-rw----    1 oracle   oracle         37 Aug 19 11:19 inst_id
-rw-rw----    1 oracle   oracle      20952 Aug 19 11:20 opmn.xml
-rw-rw----    1 oracle   oracle      11377 Aug 19 11:20 sysmgmtProperties.xml

As you have just seen, the dcmctl utility provides a powerful commandline capability to configure and maintain an instance and its internal components.  Using scripts, you can automate functions that apply to instances across multiple servers within the clustered application server environment.   However, the recommended method to manage instances and components is with Enterprise Manger.

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