Skip Headers

Oracle® Containers for J2EE Configuration and Administration Guide 10g Release 3 (10.1.3) Part No. B14432-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 1 Introducing OC4J

This chapter provides a general introduction to Oracle Containers for J2EE, or OC4J. It includes the following sections:

- What Is OC4J?

- What's New or Changed in OC4J

- What Is OC4J in a Standalone Configuration?

- What Is OC4J in an Oracle Application Server Configuration?

- Understanding the Application Hierarchy in OC4J

## What Is OC4J?

Oracle Containers for J2EE 10g Release 3 (10.1.3), or OC4J, provides a complete Java 2 Enterprise Edition (J2EE) 1.4-compliant environment. OC4J provides all the containers, APIs, and services mandated by the J2EE specification.

OC4J is distributed in two configurations:

- A standalone configuration, in which OC4J is installed as a single, "standalone" instance and is managed, started and stopped directly as a self-contained component.

  See "What Is OC4J in a Standalone Configuration?" for details on this configuration.

- A managed configuration, in which OC4J is installed and managed as a component of Oracle Application Server.

  At a minimum, a managed OC4J installation will include Oracle Process Manager and Notification Server (OPMN), which manages the various Oracle Application Server components, including OC4J.

  An installation will typically also include at least one Oracle HTTP Server (OHS) instance, which provides Web communication and load balancing functionality.

  See "What Is OC4J in an Oracle Application Server Configuration?" for details.

OC4J is written entirely in Java and executes on the Java Virtual Machine (JVM) of the standard Java Development Kit (JDK). The current OC4J release can run on JDK releases 1.4.2 and 5.0. For standalone OC4J, the JDK must be provided; for OPMN-managed OC4J, the JDK 5.0 is packaged with the server binaries.

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.

### J2EE Support in OC4J

OC4J supports and is certified on the following standard J2EE specifications, as listed in Table 1-1.

Table 1-1 Supported J2EE Specifications

J2EE Specification | Version Supported By OC4J
--- | ---
JavaServer Pages (JSP) | 2.0
Servlets | 2.4
Enterprise JavaBeans (EJB) | 2.1 3.0 (Requires JDK 5.0. Support is based on the Enterprise JavaBeans 3.0 Early Draft Review specification.)
Java Management Extensions (JMX) | 1.2
J2EE Management | 1.0
J2EE Application Deployment | 1.1
Java Transaction API (JTA) | 1.0
Java Message Service (JMS) | 1.1
Java Naming and Directory Interface (JNDI) | 1.2
Java Mail | 1.2
Java Database Connectivity (JDBC) | 3.0
Java Authentication and Authorization Service (JAAS) Provider | 1.0
J2EE Connector Architecture | 1.5
Enterprise Web Services | 1.1
Java API for XML-Based RPC (JAX-RPC) | 1.1
SOAP with Attachments API for Java (SAAJ) | 1.2
Java API for XML Processing (JAXP) | 1.2
Java API for XML Registries (JAXR) | 1.0.5

## What's New or Changed in OC4J

The following topics outline new features in Oracle Containers for J2EE Release 3 (10.1.3) as well as functional changes from previous releases.

### New Features in OC4J

Oracle Containers for J2EE Release 3 (10.1.3) includes a number of new features and enhancements, as described in the following topics:

- Support for Web Services

- Support for New J2EE 1.4 Application Management and Deployment Specifications

- Support for Enterprise JavaBeans 3.0

- Support for Oracle Application Server TopLink

- OracleAS Job Scheduler

- New Two-Phase Commit Transaction Coordinator Functionality

- Generic JMS Resource Adapter Enhancements

#### Support for Web Services

OC4J provides full support for Web services in accordance with the J2EE 1.4 standard, including JAX-RPC 1.1. Web services interoperability is also supported.

- Support for the Enterprise Web Services 1.1 specification

- EJB 2.1 Web services end point model

- JSR 109 client and server deployment model

- CORBA Web services: Support for wrapping existing basic CORBA Servants as Web services and auto-generating WSDL from IDL

- Support for source code annotations to customize Web services behavior such as invocation and ending styles (RPC/literal, RPC/encoded, Doc/literal); customizing the Java to XML mapping; enforcing security.

- Database and JMS Web services

#### Support for New J2EE 1.4 Application Management and Deployment Specifications

OC4J supports the following specifications defining new standards for deploying and managing applications in a J2EE environment.

- The Java Management Extensions (JMX) 1.2 specification, which allows standard interfaces to be created for managing resources, such as services and applications, in a J2EE environment. The OC4J implementation of JMX provides a JMX client that can be used to completely manage an OC4J server and applications running within it.

- The J2EE Management Specification (JSR-77), a specification that allows standard components to be created for managing applications in a J2EE environment.

- The J2EE Application Deployment API (JSR-88), which defines a standard API for configuring and deploying J2EE applications and modules into a J2EE-compatible environment. The OC4J implementation includes the ability to create and/or edit a deployment plan containing the OC4J-specific configuration data needed to deploy a component into OC4J.

#### Support for Enterprise JavaBeans 3.0

OC4J provides support for Enterprise JavaBeans 3.0, including the new program annotation functionality, as defined in the Early Draft Review specification. The specification is available at the following link:

    http://java.sun.com/products/ejb/

Note that OC4J must use JDK 5.0 to enable EJB 3.0 support.

#### Support for Oracle Application Server TopLink

Oracle Application Server TopLink is an advanced, object persistence framework for use with a wide range of Java 2 Enterprise Edition (J2EE) and Java application architectures. OracleAS TopLink includes support for the OC4J Container Managed Persistence (CMP) container and base classes that simplify Bean Managed Persistence (BMP) development.

#### OracleAS Job Scheduler

The OracleAS Job Scheduler provides asynchronous scheduling services for J2EE applications. Its key features include capabilities for submitting, controlling and monitoring jobs, defined as a unit of work that executes when the work is performed.

#### New Two-Phase Commit Transaction Coordinator Functionality

The new Distributed Transaction Manager in OC4J can coordinate two-phase transactions between any type of XA resource, including databases from Oracle as well as other vendors and JMS providers such as IBM WebSphere MQ. Automatic transaction recovery in the event of a failure is also supported.

#### Generic JMS Resource Adapter Enhancements

The Generic JMS Resource Adapter can now be used as an OC4J plug-in for OracleAS JMS that ships with the current version of OC4J as well as for IBM WebSphere MQ JMS version 5.3.

Support for lazy transaction enlistment has been added so that JMS connections can be cached and still be able to correctly participate in global transactions.

Finally, the Generic JMS Resource Adapter now has better error handling. Endpoints now automatically retry after provider or system failures, and `onMessage()` errors are handled correctly.

### Changes from Previous Releases

The following changes have been made in Oracle Containers for J2EE 10g Release 3 (10.1.3). Functional changes in Oracle Application Server 10g Release 3 (10.1.3) that pertain to OC4J are also outlined.

#### Configuration File Changes

The following changes have been made to configuration files utilized in standalone OC4J and in OC4J instances installed as components of Oracle Application Server. All of the files noted are installed in `ORACLE_HOME``/j2ee/``instance``/config` by default.

application.xml

- The `<persistence>` element has been moved to the new `system-application.xml` file.

- The `<jazn>` element now points to the new `system-jazn-data.xml` file as the security configuration file for the OC4J instance.

- The `default-data-source` attribute of the root `<orion-application>` element now specifies "jdbc/OracleDS" as the default data source in both standalone OC4J and Oracle Application Server.

- The `<ejb-module>` element for "PortComponentLinkResolver" has been removed.

- The `<odl>` element, used to enable ODL logging for the `default` application, has been added but commented out as a subelement of `<log>`.

ascontrol-web-site.xml

- This file has been removed from both standalone OC4J and Oracle Application Server. The Application Server Control Console instance deployed to OC4J is now bound to `default-web-site.xml` by default and is accessible via the `/em` context root.

default-web-site.xml

- This file configures the default Web site used in both standalone OC4J and Oracle Application Server. All applications, including the Application Server Control Console deployed to the OC4J instance, are accessed by default through the `default` Web site using the context root specified in this file.

global-web-application.xml

- The `<dtd>` element has been removed from the Oracle Application Server version of this file.

- The `<url-pattern>` element in the rmi-tunnel servlet definition specifies `rmiTunnel/*` in both standalone OC4J and Oracle Application Server.

http-web-site.xml

- This file has been removed from both standalone OC4J and Oracle Application Server. All applications deployed to the OC4J instance are now bound to `default-web-site.xml` by default.

j2ee-logging.xml

- This new file is used to configure Java Loggers, including the `oracle` Logger.

jazn-data.xml

- This file no longer contains the security configuration for the OC4J instance. This configuration is now defined in the new `system-jazn-data.xml` file. It can be specified at the application level to define users and roles, however.

oc4j-connectors.xml

- The `location` attribute of the `<connector>` element is no longer specified for the "datasources" and "OracleASjms" connectors.

server.xml

- The `<web-site>` elements pointing to `http-web-site.xml` and `ascontrol-web-site.xml` have been removed. A single element now points to `default-web-site.xml`, the configuration file for the `default` Web site.

- Multiple `<shared-library>` elements have been added, each referencing a shared library installed with OC4J.

system-application.xml

- This is a new file, added to provide configuration for the `system` application. See "The `System` Application" for more information on this new internal component.

system-jazn-data.xml

- This new file contains the security configuration for the OC4J instance. It essentially replaces `jazn-data.xml`.

## What Is OC4J in a Standalone Configuration?

The standalone or "unmanaged" OC4J configuration offers a robust J2EE-compliant container that is easy to administer. In this configuration, a single OC4J instance is installed into a single `ORACLE_HOME` - the root directory in which Oracle software is installed.

The standalone OC4J configuration is comprised of the following components:

- Oracle Containers for J2EE 10g Release 3 (10.1.3)

- Oracle Enterprise Manager 10g Application Server Control Console, a Web-based administration application installed by default with OC4J

The Application Server Control Console is enabled immediately upon installation. See "Oracle Enterprise Manager 10g Application Server Control Console" for details on using this management interface.

Installation

The standalone OC4J distribution, which includes Application Server Control Console, is provided as a ZIP archive. See Chapter 2, "Installing Standalone OC4J" for instructions.

Administration

The OC4J instance is administered as a standalone component, using either the Application Server Control Console installed with the instance or the built-in `admin.jar` or `oc4j.cmd`/`oc4j.sh` command line utilities.

See Chapter 3, "Tools for Administering OC4J" for an overview of these tools.

Starting/Stopping

In a standalone configuration, an OC4J instance is started using either the `oc4j.jar` command line or the `oc4j.cmd`/`oc4j.sh` command line utilities. Startup options and system properties can also be set at startup on the `oc4j.jar` command line.

See "Starting OC4J in a Standalone Environment" for details.

Backup, Restore and Disaster Recovery Capabilities

The OC4J standalone configuration does not have backup, restore and disaster recovery capabilities.

Web Communication

Web communication in a standalone environment is provided through the built-in OC4J Web server, which supports HTTP and HTTPS communications natively without the use of the Oracle HTTP Server (OHS).

The default Web site is defined in the `default-web-site.xml` file, which specifies the default HTTP listener on port `8888`. Additional Web sites may be defined on different ports using variations of this file. See Chapter 13, "Managing Web Sites in OC4J" for instructions on creating additional Web sites in OC4J.

## What Is OC4J in an Oracle Application Server Configuration?

In this configuration, OC4J is installed as a component of Oracle Application Server. A typical configuration includes the following components:

- Oracle Containers for J2EE 10g Release 3 (10.1.3)

- Oracle Enterprise Manager 10g Application Server Control Console, a Web-based administration application installed by default with OC4J

- Oracle HTTP Server (OHS) 1.3, which provides front-end Web communication and load balancing functionality

- Oracle Process Manager and Notification Server (OPMN), used to start/stop and monitor the other installed components, including OC4J and OHS. OMPN includes Oracle Notification Server (ONS), which manages communications between components.

Oracle Application Server provides support for HTTP session and stateful session Enterprise JavaBean replication and load balancing across a cluster of OC4J instances. See Chapter 9, "Application Clustering in OC4J" for details.

The Oracle Universal Installer provides a number of installation options:

- Integrated Web Server, J2EE Server and Process Management

  In this configuration, all components - OC4J, OHS and OPMN - are installed into a single `ORACLE_HOME` directory.

  Multiple OC4J instances can be created within this `ORACLE_HOME` directory. Multiple host machines, each hosting one or more OC4J instances, can be included in an Oracle Application Server cluster.

- J2EE Server and Process Management

  This installation includes OC4J and OPMN. It can be utilized as a "standalone" OPMN-managed OC4J instance for development or testing purposes, or can be included within an Oracle Application Server cluster.

- Web Server and Process Management

  This installation includes OHS and OPMN only. It can be used as a "standalone" OHS instance, typically serving as the front-end Web listener for an Oracle Application Server cluster.

Installation

Installation of the various components is done using the Oracle Universal Installer. Note that OPMN must be installed in every `ORACLE_HOME` directory to enable monitoring of each installed component.

Administration

All administration tasks are performed using the Web-based Application Server Control Console user interface. In a clustered environment, a single Application Server Control Console can be used to manage all OC4J instances in the cluster.

See "Oracle Enterprise Manager 10g Application Server Control Console" for details on this application.

Starting/Stopping

In a managed environment, OPMN is used to start and stop all components, including OC4J. See "Starting OC4J in an Oracle Application Server Environment" for details.

Note that OC4J runtime options and system properties can be manually set in the OPMN configuration file, `opmn.xml`. See Chapter 4, "OC4J Runtime Configuration" for details.

Backup, Restore and Disaster Recovery Capabilities

These capabilities are available with the managed Oracle Application Server configuration.

Web Communication

A standalone OPMN-managed OC4J instance (the J2EE Server and Process Manager install type) can use the built-in OC4J Web server to directly receive and respond to HTTP[S] requests.

Web communications with OC4J can also be managed through Oracle HTTP Server (OHS), which serves as a front-end listener, and the `mod_oc4j` module, which forwards HTTP requests to OC4J server instances using the Apache JServ Protocol (AJP) 1.3.

The OHS-OC4J request/response flow is as follows:

1. An incoming HTTP request is received by the OHS listener.

2. OHS passes the request to an OC4J server instance via the `mod_oc4j` module. The connection between OHS and OC4J uses the Apache JServ Protocol (AJP) on a port number negotiated during OC4J startup.

Description of the illustration O_1014.gif

Mount points mapping request URLs to the OC4J instance serving the requested application are dynamically created in `mod_oc4j` at the time applications are deployed. Requests that come in for specific mount points are routed to the OC4J instance corresponding to that mount point.

For additional information on configuring and managing OHS and the `mod_oc4j` module, see the Oracle HTTP Server Administrator's Guide.

## Understanding the Application Hierarchy in OC4J

This section provides an overview of the application hierarchy within an OC4J instance.

### The `System` Application

The `system` application is a new internal component in Oracle Containers for J2EE Release 3 (10.1.3). It is auto-deployed to the OC4J instance the first time OC4J is started.

This application was added primarily to address issues related to deploying or redeploying applications to OC4J. It sits at the root of the application hierarchy, and provides classes and configuration required at OC4J startup. For example, it provides the shared libraries imported by default by all other deployed applications, such as the Oracle JDBC driver and XML parser implementations.

The `system` application is an OC4J internal component only. Applications cannot be deployed to it, nor can it be declared the parent of another application. The `default` application continues to serve as the default parent of all deployed applications.

The configuration for the `system` application is defined in `system-application.xml`, which is installed in `ORACLE_HOME``/j2ee/``instance``/config` by default.

Important: Because `system` is a key internal component that is critical to OC4J startup, the `system-application.xml` file should NOT be modified. The only exception is the `<jazn>` tag, which may be modified as needed to specify changes to the security provider and/or location of the OC4J security configuration file (`system-jazn-data.xml`).

### The `Default` Application

The `default` application sits just below `system` in the application hierarchy. It continues to serve as the default parent of all other J2EE applications deployed into the OC4J instance. As such, all configuration parameters defined for the `default` application are inherited by all other applications, unless explicitly overridden at the application level.

Standalone Web modules (WAR files) may also be deployed to the `default` application.

The configuration for the default application is defined in `application.xml`, which is installed in `ORACLE_HOME``/j2ee/``instance``/config` by default.

### The Global Web Application

The global Web application is the Web module component of the `default` application. It provides configuration data applied by default to all Web modules deployed to the OC4J instance. It also contains initialization parameters applied by default to all servlets.

The configuration file for the default Web application is `global-web-application.xml`, which is installed in `ORACLE_HOME``/j2ee/``instance``/config` by default. This file contains parameters that are applied by default to all Web modules deployed to the OC4J instance, as well as servlet initialization parameters applied to all servlets. Any of these parameter values can be overridden by corresponding values in a Web module's `orion-web.xml` file, however.

In a standalone OC4J installation, the root directory of the default Web application is `j2ee/home/default-web-app`. To deploy to the default Web application, place your JSP pages and class files under this directory in the standard Web application directory structure: static pages and JSP pages at the top level, servlet classes under `j2ee/home/default-web-app/WEB-INF/classes`, and library JAR files in `j2ee/home/default-web-app/WEB-INF/lib`.

### J2EE Applications

By default, an application deployed to an OC4J instance inherits configuration parameters from its designated parent application, or from the `default` application if no other parent is specified. However, a parameter value set in an application's `orion-application.xml` descriptor overrides an equivalent parameter inherited from the parent.

Note that a Web module must be contained within a parent J2EE application. A WAR file is typically packaged and deployed with the EAR file that defines the parent J2EE application. However, a WAR file can be deployed to the `default` application as a standalone Web module.