Skip Headers
Oracle® Containers for J2EE Configuration and Administration Guide
10g (10.1.3.1.0)

Part Number B28950-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

1 Introduction to Oracle Containers for J2EE (OC4J)

This chapter provides a general introduction to Oracle Containers for J2EE (OC4J), in the following sections:

Overview of OC4J

Oracle Containers for J2EE 10g (10.1.3.1.0), 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:

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 5.0 and 1.4.2. For OPMN-managed OC4J, the JDK 5.0 is installed with the server binaries and used by default to start the OC4J instance. For standalone OC4J, the JDK must be provided. You can configure an OC4J instance to run on multiple JVMs.

The OC4J documentation is based on the assumption 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 standard J2EE specifications 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 (Complete EJB 3.0 and JPA implementation)

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


New and Changed Features in OC4J

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

New Features in OC4J

Oracle Containers for J2EE 10g (10.1.3.1.0) includes a number of new features and enhancements, as described in the following topics:

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 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 or edit a deployment plan containing the OC4J-specific configuration data needed to deploy a component into OC4J.

  • 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.

Support for Enterprise JavaBeans 3.0

OC4J 10g (10.1.3.1.0) provides complete support for the Enterprise JavaBeans 3.0 final specification, including support for EJB annotations and dependency injections. The final specification is available at the following Web site:

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


Note:

OC4J must use JDK 5.0 to enable EJB 3.0 support. This JDK is included with the current 10g (10.1.3.1.0) release, in which OC4J uses JDK 5.0 by default.

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, each job 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 types of XA resources, 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.

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.

New admin_client.jar Commands and Remote Client

The admin_client.jar utility has new commands for managing data sources and the OC4J JMS connection factories and destinations. You can use these commands through the command-line tool or through the relevant JMX MBeans to add, remove, and get information about data sources and JMS connection factories and destinations. For details, see Chapter 6, "Using the admin_client.jar Utility".

Configuration File Changes from Previous Releases

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 by default in ORACLE_HOME/j2ee/instance/config, in which instance represents the OC4J instance name.

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. For more information about <jazn>, see the Oracle Containers for J2EE Security Guide.

  • 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 through 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. The jazn-data.xml can be specified, however, at the application level to define users and roles. For more information about the jazn-data.xml and system-jazn-data.xml files, see the Oracle Containers for J2EE Security Guide.

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.

  • A <thread-pool> element has been added to the server.xml for defining thread pools for use by OC4J processes and applications deployed to OC4J instances. This element replaces the <global-thread-pool> and <work-manager-thread-pool> elements, which are deprecated in OC4J (10.1.3.1.0).

  • A <custom-thread-pool> element has been added to the server.xml file for defining separate, custom thread pools for applications.

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. For more information about the jazn-data.xml and system-jazn-data.xml files, see the Oracle Containers for J2EE Security Guide.

OC4J in a Standalone Configuration

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

The standalone OC4J configuration includes the following components:

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, 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 the Application Server Control Console installed with the instance, Ant tasks, or one of the built-in command-line utilities, such as admin_client.jar.

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

Starting, Stopping, and Restarting

In a standalone configuration, an OC4J instance is started using an oc4j command script or the executable oc4j.jar archive. Startup options and system properties are set before startup for the command script or at startup with the oc4j.jar direct execution model.

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

You can stop and restart a standalone OC4J server with the admin_client.jar or admin.jar command-line utility or an oc4j command script. For details, see "Stopping OC4J in a Standalone Environment", "Restarting an OC4J Instance in a Standalone Environment", or "Stopping and Restarting OC4J in a Standalone Environment".

Backup, Restore, and Disaster Recovery Capabilities

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

Web Communications

Web communications 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.

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.

OC4J in an Oracle Application Server Configuration

In this configuration, OC4J is installed as a component of Oracle Application Server, in a group of one or more OC4J instances within an Oracle Application Server cluster. A typical configuration includes the following components:

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

The connectivity provided within an Oracle Application Server cluster is a function of Oracle Notification Server (ONS), which manages communications between Oracle Application Server components, including OC4J and Oracle HTTP Server. The ONS server is a component of Oracle Process Manager and Notification Server (OPMN), which is installed by default on every Oracle Application Server host.

The Oracle Universal Installer provides a number of installation options:

Installation

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

Administration

Administration tasks can be performed using any of these tools:

Chapter 1, "Introduction to Oracle Containers for J2EE (OC4J)" provides overviews of these tools.

In an Oracle Application Server clustered environment, a single Application Server Control Console can be used to manage all OC4J instances in a cluster. See "Oracle Enterprise Manager 10g Application Server Control Console" for details on this application.

OC4J includes a set of Ant tasks for performing administration tasks on a group of OC4J instances within an Oracle Application Server cluster, on an OPMN-managed OC4J instance, or on a standalone OC4J server. For details about the Ant tasks and guidelines for integrating the tasks into your application build process, see "Deploying with the OC4J Ant Tasks" in the Oracle Containers for J2EE Deployment Guide.

The admin_client.jar tool provided with OC4J can be used to perform administration tasks on a group of OC4J instances within an Oracle Application Server cluster, on an OPMN-managed OC4J instance, or on a standalone OC4J server. Also, the administration client distribution, oc4j_admin_client_101310.zip, which contains the client-side jars necessary for performing administrative operations from a remote client in two ways:

See Chapter 6, "Using the admin_client.jar Utility" for instructions on using this tool.

The admin.jar tool provided with OC4J can be used to perform administration tasks only on a standalone OC4J server. See Chapter 7, "Using the admin.jar Utility" for instructions on using this tool.

Starting and Stopping

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

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, which serves as a front-end listener, and the mod_oc4j module, which forwards HTTP requests to OC4J instances using the Apache JServ Protocol (AJP) 1.3.

The request and response flow between Oracle HTTP Server and OC4J is as follows:

  1. An incoming HTTP request is received by the Oracle HTTP Server listener.

  2. Oracle HTTP Server passes the request to an OC4J instance through the mod_oc4j module. The connection between Oracle HTTP Server and OC4J uses the Apache JServ Protocol (AJP) on a port number negotiated during OC4J startup.

Description of jicon014.gif follows
Description of the illustration jicon014.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 Oracle HTTP Server and the mod_oc4j module, see the Oracle HTTP Server Administrator's Guide.

Overview of 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 10g (10.1.3.1.0). 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 except for the <jazn> and <log> tags.

You can modify the <jazn> tag as needed to specify changes to the security provider, the location of the OC4J security configuration file (system-jazn-data.xml), or both. For more information about <jazn> and the system-jazn-data.xml file, see the Oracle Containers for J2EE Security Guide.

You can modify the <log> tag to rotate the system log file.


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.

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.