Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

Oracle Containers for J2EE (OC4J)

by Debu Panda

With the release of version of its 9i Application Server, Oracle introduced a fast, scalable, developer-friendly J2EE container. OC4J, as it is popularly known, was licensed from Ironflare, makers of the Orion server, and was enhanced by Oracle and integrated with other components in the application server stack.

A future article will discuss the just-released developers' preview version of OC4J 2.0. 9iAS release 2 includes complete support for Enterprise JavaBeans (EJB) 2.0, Servlets 2.3, JavaServer Pages (JSP) 1.2, JTA 1.0, JNDI 1.2, JMS 1.0, JDBC 2.0, JavaMail 1.2, JAF 1.0, JAXP 1.1, Connector 1.0, and JAAS 1.0. OC4J also supports standard services such as JSP Tag libraries, and provides advanced clustering facilities to support both stateless and stateful application failover of servlets and EJBs. This article only discusses the features provided in the version of 9iAS Oc4J.

OC4J is a J2EE-1.2-certified application server. OC4J provides the performance, scalability, and features (like HTTP clustering and load balancing) necessary for deployment as an enterprise application server. In addition, it boasts several features to make developers' lives easier during the development phase. In this article, I will cover the ease-of-use and developer features that make OC4J an attractive option for developing and deploying J2EE applications.

Ease of Installation and Configuration

OC4J can either be installed from 9iAS software distribution or downloaded from the Oracle Technology management Web site. OC4J is developed purely in Java and hence the same distribution works for most of its platforms (Windows, Linux, Solaris, HP).

The installation of the J2EE container is very simple and takes only few minutes. You need JDK 1.2.2 or higher installed on your machine and java binaries included in your path. If the unzip utility is not available in your environment, you can use the jar utility to install the server from the oc4j.zip file.

Following are the steps involved in installing OC4J:

$ cd ias 
$ unzip oc4j.zip (or jar xvf oc4j.zip) 
$ cd j2ee/home 
$   java -jar orion.jar  -install 
Enter an admin password to use: debu 
Confirm admin password: debu Installation done

The application server configuration files consists of seven XML files residing in the $IAS_HOME/j2ee/home/config directory; the names of the XML files are self-explanatory.

The following list provides a brief description about the configuration files.

Main configuration file containing directives that apply globally across the container.
Configuration for the default HTTP listener.
Allows generic naming for a number of data sources and how and where these are accessed.
data jms.xml
Configuration for the Java Messaging Service, including queues, topics, and port.
Configuration for Remote Method Invocation, including ports.
Configuration for the default application.
Directives for all Web applications deployed.

By default, OC4J has a Web server configured to listen for HTTP requests at port 8888; you can change the port by editing default-web-site.xml.

The OC4J server can be started with a single command and the process runs in a single JVM. After the OC4J server is started, you can invoke your Web site as http://<servername>:8888. The command to start and shutdown OC4J is:

$ java -jar orion.jar Oracle9iAS ( 
Containers for J2EE initialized 
$ java -jar admin.jar ormi://localhost admin debu -shutdown 

J2EE Application Deployment

Related Reading

Java Servlet Programming, 2nd EditionJava Servlet Programming, 2nd Edition
By Jason Hunter with William Crawford
Table of Contents
Sample Chapter
Full Description

OC4J provides J2EE-standard EAR and WAR file deployment. The greatest benefit of OC4J is that you can deploy J2EE-compliant EAR as is, with no changes or repackaging required. Just point to the location of the EAR file, and OC4J will automatically deploy the application to the application server. The deployment process is quite developer-friendly, as it automatically deploys the EJB-JARs and WARs included in the EAR file. The EJB deployment process automatically generates the stubs; for CMP beans, it generates the finder methods.

OC4J is certified with Oracle8i and 9i databases out of the box and comes with Oracle's Type 4 JDBC driver. OC4J is also certified with Merant JDBC Drivers for connecting to non-Oracle databases (SQLServer, DB2, etc). DataSources can be configured using data-sources.xml. Following is a typical example of a DataSource:

<!--   An example/default DataSource that uses   
Oracle JDBC-driver to create the connections.
This tag creates all the needed kinds of data-sources, 
transactional, pooled and EJB-aware sources. The source 
generally used in application code is the "EJB" one - 
it provides transactional safety and connection   
pooling. Oracle thin driver could be used as well,   
like below.   url="jdbc:oracle:thin:@host:port:sid" -->   
<data-source class="com.evermind.sql.DriverManagerDataSource"
  name="OracleDS" location="jdbc/OracleCoreDS"
  xa-location="jdbc/xa/OracleXADS" ejb-location="jdbc/OracleDS"
  username="scott" password="tiger"
  inactivity-timeout="30"  />  

You can deploy a J2EE application, i.e., an EAR file, either by making an entry in the server.xml file for the application or by using command-line options. For example, we have our application packaged as timecard.ear and it has an EJB called work-ejb.jar and WAR called work.war. We deploy the the application as follows:

C:\oracle\iSuites\j2ee\home> java -jar admin.jar ormi://localhost 
  admin debu -deploy -deploymentName TimeCardApp 
  -file c:\time\ear\timecard.ear

  C:\oracle\iSuites\j2ee\home\applications\timecard.ear... done.
  C:\oracle\iSuites\j2ee\home\applications\timecard\work.war... done.
Auto-deploying TimeCardApp (New server version detected)...
Auto-deploying work-ejb.jar (No previous deployment found)...
Auto-creating table: create table work_ejb_WorkHours (email 
  VARCHAR2(255) not null, monthEnding DATE not null, workHours 
  double precision null, trainingHours double precision null, 
  vacationHours double precision null, otherHours double precision 
  null, primary key (email, monthEnding))


The EJB deployment process will automatically generate the stubs and automatically create the table for the CMP entity bean if the table does not exist in the database.

As the timecard application has a WAR module called work.war the context URI for the Web module can be set by either modifying default-web-site.xml or as in the following command:

C:\oracle\iSuites\j2ee\home>java -jar admin.jar 
  ormi://localhost admin debu  -bindWebApp TimeCardApp
  work default-web-site /time

Now we would be able to access the Web module by accessing http://<servername>:8888/time.

OC4J does not explicitly require an EAR or WAR file, and it supports an open extended directory structure similar to the directory structure in an EAR or WAR file. You can specify the parent directory of the open extended directory to be the location of your application. This is very helpful during the development phase of a project, and you don't always have to build the EAR/WAR file for every code change. Whenever there is a change in a servlet class or JSP, you can just change the time stamp of web.xml (by the Unix touch command or some other method) for the Web application, and the Oc4J server will flagged about the code change. It will re-deploy the application, so you don't have to bounce your server for every code change.

Automatic Finder Methods Generation

OC4J automatically generates finder methods for CMP beans. For simple finder methods, you don't have to do anything; these are automatically generated during deployment. For example, say you have a finder method called findByemail where email is one of the cmp-fields in your entity bean. If you have a complex finder method, however, you need a finder method to be documented in the vendor-specific deployment descriptor, i.e., orion-ejb-jar.xml as follows. This is for a finder method called findExpensiveEmployees, which finds all employees making a salary above a certain amount.

<finder-method query="$salary > ;  $1"> 

The easiest thing to do is to deploy the EJB once, get orion-ejb-jar.xml generated in the application -deployments directory, make modifications in this file per your requirements, and then package this in your ejb-jar.

Auto-compile Features

The most promising feature for developers is that OC4J can automatically detect code changes and automatically compile them for you. In order to achieve this functionality, you have to specify the "development=true" attribute in the global-web-application.xml file for all deployed applications, or orion-web-application.xml for a particular application. Also, you can set source-directory to tell the OC4J server where to look for sources for servlet classes for auto-compiling. By default, Oc4J server will use the WEB-INF/src directory if it exists; otherwise, it will use the WEB-INF/classes directory.

<?xml version="1.0"?>
<!DOCTYPE orion-web-app PUBLIC 
 "-//Evermind//DTD Orion Web Application 2.3//EN"


When this configuration is set, you can also look at the intermediate Java code for a JSP. The generated servlet code will be saved in the persistence directory for your application. The persistence directory can be found in the $ORACLE_J2EE_HOME/application-deployments/application directory, where application is the name of the application you are using.

Logging and Debugging

Logging and debugging are very crucial for an application during its life cycle. Oc4J provides several facilities for logging of activities in the server and features to help debug problems encountered in an application.

Oc4J provides the following types of logging:

Server-level logging; normally contains server startup, shutdown, and internal server errors.
Application-level logging for each of the deployed applications; contains all events related to an application.
Web access log
Contains all Web access information.
RMI log
Logs RMI events and errors.
JMS log
Logs JMS events and errors.

Generally, developers put a lot of System.out.println statements in their code to perform application debugging. Normally, all standard outputs and error outputs are routed to the console where the OC4J server is started. If you want to capture the standard output and error outputs to files for logging/debugging purposes, then you can use the -out and -err options while starting up the Oc4J server to specify which files to use.

Some issues are difficult to track down; sometimes you might need to debug at different sub-system levels in the application server. OC4J provides a number of system properties and you can use these in the comand line while starting to enable this system-level debugging. For example, if you want to enable HTTP session-level debugging, start the OC4J server as follows:

java  -Dhttp.session.debug=true -jar orion.jar

Debu Panda is a Senior Principal Product Manager of the Oracle Application Server development team.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.