Skip Headers
Oracle® Application Server Containers for J2EE User's Guide
10g Release 2 (10.1.2)
Part No. B14011-02
  Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index


1 OC4J Overview

This chapter describes OC4J and demonstrates how to install OC4J with the Oracle Application Server installation.

This chapter includes the following topics:

1.1 Introduction to OC4J

Oracle Application Server provides a complete Java 2 Enterprise Edition (J2EE) environment written entirely in Java that executes in the Java virtual machine (JVM) of the standard Java Development Kit (JDK). You can run Oracle Application Server Containers for J2EE (OC4J) on the standard JDK that exists on your operating system. Refer to the certification matrix on

OC4J is J2EE certified and provides all the containers, APIs, and services that J2EE specifies. OC4J is based on technology licensed from Ironflare Corporation, which develops the Orion server—one of the leading J2EE containers. Although OC4J is integrated with the Oracle Application Server infrastructure, the product and some of the documentation still contains some reference to the Orion server.

OC4J supports and is certified for the standard J2EE APIs, as listed in Table 1-1.

Table 1-1 OC4J J2EE Support

J2EE 1.3 Standard APIs Version Supported

JavaServer Pages (JSP)




Enterprise JavaBeans (EJB)


Java Transaction API (JTA)


Java Message Service (JMS)


Java Naming and Directory Interface (JNDI)


Java Mail


Java Database Connectivity (JDBC)

2.0 Extension



J2EE Connector Architecture (JCA)




The OC4J documentation assumes that you have a basic understanding of Java programming, J2EE technology, and Web and EJB application technology. This includes deployment conventions such as the /WEB-INF and /META-INF directories.

1.1.1 Examples Provided with OC4J

Oracle Application Server 10g (9.0.4) includes one demo per component. Additional demos are available for download from OTN at the following URL:

Drill down from this index page to the component areas that contain the additional demos that you need.

1.2 JDK 1.4 Considerations: Cannot Invoke Classes Not in Packages

Among the migration considerations in moving to a Sun Microsystems JDK 1.4 environment, which is the environment that is shipped with Oracle Application Server 10g, there is one of particular importance to servlet and JSP developers.

As stated by Sun Microsystems, "The compiler now rejects import statements that import a type from the unnamed namespace." (This was to address security concerns and ambiguities with previous JDK versions.) Essentially, this means that you cannot invoke a class (a method of a class) that is not within a package. Any attempt to do so will result in a fatal error at compilation time.

This especially affects JSP developers who invoke JavaBeans from their JSP pages, as such beans are often outside of any package (although the JSP 2.0 specification now requires beans to be within packages, in order to satisfy the new compiler requirements). Where JavaBeans outside of packages are invoked, JSP applications that were built and executed in an OC4J 9.0.3 / JDK 1.3.1 environment will no longer work in an Oracle Application Server 10g / JDK 1.4 environment.

Until you update your application so that all JavaBeans and other invoked classes are within packages, you have the alternative of reverting back to a JDK 1.3.1 environment to avoid this issue.


  • The javac -source compiler option is intended to allow JDK 1.3.1 code to be processed seamlessly by the JDK 1.4 compiler, but this option does not account for the "classes not in packages" issue.

  • Only the JDK 1.3.1 and JDK 1.4 compilers are supported and certified by OC4J. It is possible to specify an alternative compiler by adding a <java-compiler> element to the server.xml file, and this might provide a workaround for the "classes not in packages" issue, but no other compilers are certified or supported by Oracle for use with OC4J. (Furthermore, do not update the server.xml file directly in an Oracle Application Server environment. Use the Oracle Enterprise Manager 10g.)

For more information about the "classes not in packages" issue and other JDK 1.4 compatibility issues, refer to the following Web site:

In particular, click the link "Incompatibilities Between Java 2 Platform, Standard Edition, v1.4.0 and v1.3".

1.2.1 Migrating Source Code from JDK 1.4 to JDK 1.3

bug 2811379 Java does not support compiling Java code under JDK 1.4 and running it under JDK 1.3 (bug 2811379). If you try anyway, Java may throw one of the following error messages at runtime:

  • Unsupported major.minor version 48.0.

  • The major.minor version '48.0' is too recent for this tool to understand.

However, if you must generate class files using JDK 1.4 and run them using JDK 1.3, then you can use the following command to force a JDK 1.4 compiler to generate a class file that is compatible with JDK 1.3:

% javac -target 1.3

1.2.2 Migrating Source Code from JDK 1.3 to JDK 1.4

When you upgrade from JDK 1.3 to JDK 1.4, put all classes into packages. The JDK 1.4 specification explicitly prohibits a class within a package from invoking a class not within a package. For this reason, some Java source code that compiles in JDK 1.3 will not compile in JDK 1.4. This error is identified by the following compiler message:

 '.' expected import myClass

This message means that the Java compiler expects to find a package and class name and cannot parse a line that contains only a class name.

For details, see the Sun Microsystems compatibility document supplied with the JDK.

1.3 Navigating the OC4J Documentation Set

Most of the location of J2EE subject matter is obvious. For example, you can find out how to implement and use servlets within the Oracle Application Server Containers for J2EE Servlet Developer's Guide. Table 1-2 shows each J2EE subject matter and where you can find the information in the OC4J documentation set.

1.4 OC4J Installation

OC4J is a lightweight container that is J2EE-compliant. It is configured with powerful and practical defaults and is ready to execute after installation. OC4J is installed with Oracle Application Server; therefore, see the Oracle Application Server Installation Guide for details on OC4J installation.

1.5 Using OC4J in an Enterprise or Standalone Environment

OC4J is installed within Oracle Application Server with the goal of managing J2EE enterprise systems. Oracle Application Server can manage multiple clustered OC4J processes. Oracle Application Server, which includes OC4J, is managed and configured through the Oracle Enterprise Manager 10g, which can manage and configure your OC4J processes across multiple application server instances and hosts. Thus, you cannot locally manage your OC4J process using the admin.jar tool or by hand editing a single OC4J process' configuration files. This undermines the enterprise management provided by the Oracle Enterprise Manager 10g.

You can still execute OC4J as you have in the past. For those who want a single OC4J instance for development environments or simple business needs, you can download OC4J in standalone mode—complete with documentation.

This following sections discusses both management options in the following sections:

Also, the following section describes how to understand the OC4J documentation set:

1.5.1 Managing Multiple OC4J Instances in an Enterprise Environment

You manage Oracle Application Server, including OC4J, using Oracle Enterprise Manager 10g within an enterprise system. This includes clustering, high availability, load balancing, and failover.

You configure each OC4J instance and its properties—within the context of an application server instance—using Oracle Enterprise Manager 10g. After configuration, you start, manage, and control all OC4J instances through Oracle Enterprise Manager 10g. You can group several OC4J processes in a cluster. You must use either the Oracle Enterprise Manager 10g management tool or its command-line tools for starting, stopping, restarting, configuring, and deploying applications.


You cannot use the OC4J standalone tool—admin.jar—for managing OC4J instances created in an application server instance.

You can modify the XML files locally. If you do so, you must notify Oracle Enterprise Manager 10g that these files have been hand edited through the Distributed Configuration Management (DCM) component tool—dcmctl. The following is the command that you execute after hand editing an XML file:

dcmctl updateconfig -ct oc4j

DCM controls and manages configuration for Oracle Application Server instances and its Oracle HTTP Server and OC4J components. For more information on DCM, see the Distributed Configuration Management Administrator's Guide.

This book discusses how to start, stop, manage, and configure OC4J in an enterprise environment.

1.5.2 Managing a Single OC4J Instance

You can still use a single OC4J—outside of the Oracle Application Server environment. After downloading OC4J in from OTN, you can start, manage, and control all OC4J instances through oc4j.jar and the admin.jar command-line tool. You configure either through the admin.jar command or by modifying the XML files by hand.

Any standalone OC4J process is not managed by Oracle Enterprise Manager 10g and cannot be used within an Oracle Application Server enterprise environment. Typically, you would use standalone for development or for a simple single OC4J instance Web solution.

Download the OC4J Standalone User's Guide for information on how to start, stop, configure, and manage your standalone process.

1.5.3 Using JDK With OC4J

You must have only one Java Developer's Kit (JDK) installed on your system. Make sure that it is a version that OC4J supports:

  • JDK 1.3.1

  • JDK 1.4.1

  • JDK 1.4.2

OC4J Standalone does not include a JDK. If you are using OC4J Standalone, then you must provide your own JDK installation.

Some suppliers bundle a JDK with their products. If necessary, remove any old version(s), replace them with a supported version, and update the appropriate environment variables. Make sure that your PATH, CLASSPATH, and LD_LIBRARY_PATH (or LIB on Windows) variables are all set to the officially supported version of JDK.


Due to a logging implementation dependency issue, OC4J fails to start when using JDK 1.3. The solution to this problem is to remove or comment out the following entry in the ORACLE_HOME/j2ee/home/config/server.xml configuration file:
<j2ee-logging-config path="./j2ee-logging.xml" />

1.5.4 OC4J Documentation Set Assumptions

Aside from this book, the rest of the OC4J documentation set was written with a standalone mindset. These other books may refer to modifying XML files by hand for managing the instance. This book provides a good overview and familiarization of the Oracle Enterprise Manager 10g configuration pages. It also guides you to understand the relationship of each Oracle Enterprise Manager 10g page to its XML counterpart. Use the familiarity of the Oracle Enterprise Manager 10g when reading the other OC4J books. You should be able to look at an XML representation and match it to the relevant Oracle Enterprise Manager 10g field names.

Also, the Distributed Configuration Management (DCM) utility, dcmctl, provides a command-line alternative to using Oracle Enterprise Manager 10g for some management tasks. The dcmctl tool uses the same distributed architecture and synchronization features as Oracle Enterprise Manager 10g, thereby providing identical functionality in a format that is ideal for scripting and automation.

The following functions can be managed through DCM:

  • administration

  • managing application server instances

  • managing components

  • managing clusters

  • deploying applications

For other DCM commands that relate to OC4J, see the Distributed Configuration Management Administrator's Guide.

1.6 OC4J Communication

For HTTP applications, OC4J is preconfigured to execute behind the Oracle HTTP Server (OHS). You use the Oracle HTTP Server as a front-end listener and OC4J as the back-end J2EE application server.

However, for RMI-based applications—such as EJB and JMS—clients should send their requests directly to OC4J. See "Understanding and Configuring OC4J Listeners" for directions.

1.6.1 HTTP Communication

For all incoming HTTP communication within the application server environment, you use the OHS as a front-end listener and OC4J as the back-end J2EE application server. Figure 1-1 illustrates this as follows:

  1. A browser accesses the OHS listener for all HTTP requests. The Oracle HTTP Server is an Apache server. The default port number is 7777.

  2. OHS, through the mod_oc4j module, passes the request to the OC4J server. The connection between the OHS and OC4J uses the Apache JServ Protocol (AJP) on a port number negotiated during OC4J startup. AJP is faster than HTTP, through the use of binary formats and efficient processing of message headers.

Figure 1-1 HTTP Application Listener

Description of Figure 1-1  follows
Description of "Figure 1-1 HTTP Application Listener"

The mod_oc4j module is preconfigured to direct all incoming HTTP requests under the j2ee/ Web context to OC4J. Thus, if you want to use the default routing, you can deploy your Web application into a servlet context that includes as its prefix j2ee/. However, any URL mapping you provide in the deployment wizard is automatically added to the mod_oc4j module. See "Configuring Oracle HTTP Server With Another Web Context" for information on what is added to mod_oc4j for you during deployment. For additional information on the mod_oc4j module, see the Oracle HTTP Server Administrator's Guide.


In Oracle9iAS version, the default OC4J Web site did not use the Oracle HTTP Server as a front-end, and it listened using the HTTP protocol on port 8888.

1.6.2 Requirements

For optimum performance, run OC4J with the JDK that is installed with Oracle Application Server Release 2, which is JDK 1.4.2.

It is not necessary to add anything to your CLASSPATH to run OC4J, because it loads the Java JAR and class files directly from the installation directory, from the lib/ subdirectory, and from the deployed application EAR files.