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


1 Configuration and Deployment

This chapter demonstrates how to configure and execute OC4J as simply and quickly as possible. Within OC4J, you can execute servlets, JSP pages andEJBs. As an example of deploying an application to OC4J, this chapter describes how to configure the FAQ application demo.

This chapter includes the following topics:

1.1 Introduction to OC4J Standalone

Oracle Application Server Containers for J2EE (OC4J) Standalone provides a complete Java 2 Enterprise Edition (J2EE) 1.3 environment written entirely in Java that executes on the Java virtual machine (JVM) of the standard Java Development Kit (JDK).

OC4J is J2EE 1.3 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, so 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

Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider


J2EE Connector Architecture




OC4J Standalone is for use by development and small-medium scale production deployments. Specifically, OC4J Standalone supports HTTP and HTTPS natively without the use of Oracle HTTP Server. It does not have support for load balancing, clustering, or management through Oracle Enterprise Manager 10g. To use those features, customers must install one of the Oracle Application Server installation types, such as J2EE + WebCache. The standalone version is supported in a single instance, single JVM, and single machine configuration.

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.2 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. After downloading the file from OTN, unzip this file to install OC4J. The following sections describe how to do this:

1.2.1 Requirements

You do not need 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 applications EAR, WAR, or ejb-jar files.

1.2.2 Basic Installation

OC4J is distributed within a ZIP file named on OTN. After unzipping this file, follow instructions listed in the README.TXT. Install this ZIP file in any directory that is in the path.

You must have a Java2 version Java executable in your $PATH, preferably version 1.3.1 or 1.4.1. To install OC4J, execute the following:

% cd /your_directory
% unzip
% cd j2ee/home 
% java -jar oc4j.jar -install 

Enter an administrator password

After the install is complete, the j2ee/home directory contains all the files necessary for running OC4J with a default configuration. The installation prompts you for an administration username and password, which is used for the administration console command-line tool.


Instead of executing oc4j.jar from the j2ee/home directory, you can set a $J2EE_HOME variable (for UNIX) or the %J2EE_HOME% variable (for Windows) to j2ee/home, so that in the command line and execute oc4j.jar from any directory.

For example, in the UNIX environment use the following:

% java -jar $J2EE_HOME/oc4j.jar

1.2.3 Testing the Default Configuration

OC4J is installed with a default configuration that includes a default Web site and a default application. These are provided so you can start and test OC4J immediately.

Start OC4J by executing the following:

  1. Change directory to the OC4J installation directory (j2ee/home), and issue one of the following commands:

    • java -jar oc4j.jar

      This starts OC4J using the default configuration files, which are located in j2ee/home/config.

    • java -jar oc4j.jar -config /mypath/server.xml

      This starts OC4J using the server.xml file located in /mypath.

    The server should output an initialization string with the version number.

  2. Test OC4J by accessing "http://hostname:8888/" from a Web browser. If you changed the default port number, access the Web server using "http://hostname:portnumber/".

For example, test the Web server by connecting a Web browser to http://hostname:8888/servlet/HelloWorldServlet, which should return a "Hello World" page.

For more information on starting and stopping OC4J, see "Starting and Stopping OC4J". For more information on configuration, see "Deploying Applications".

1.3 Starting and Stopping OC4J

1.3.1 Starting OC4J

OC4J is installed with a default configuration that includes a default Web site and a default application. Therefore, you can start OC4J immediately.


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" />

To start OC4J in a standalone environment, issue the following command from the j2ee/home/ directory:

java -jar oc4j.jar options

This command starts OC4J using the default configuration files, which you can find in the j2ee/home/config directory.

Options for this command are not necessary to start OC4J. However, if you want to exercise more control, use the options listed in "Options for the OC4J Server JAR" or issue the following command from the j2ee/home directory:

java -jar oc4j.jar -help

After OC4J launches, a message is displayed on the screen to note this fact.


Instead of executing oc4j.jar from the j2ee/home directory, you can set a $J2EE_HOME variable (for UNIX) or the %J2EE_HOME% variable (for Windows) to j2ee/home, so that in the command line and execute oc4j.jar from any directory.

For example, in the UNIX environment use the following:

% java -jar $J2EE_HOME/oc4j.jar

1.3.2 Administering OC4J

After starting the OC4J server, you can administer the server using the admin.jar command-line tool, which is located in <install_directory>/j2ee/home. To use the admin.jar command, see the following syntax:

java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin_id    admin_password options

where the variables are as follows:

  • oc4j_host:oc4j_ormi_port—The host name and port of the OC4J server from which you want to deploy the application. The admin.jar tool uses the OC4J Remote Method Invocation (ORMI) protocol to communicate with the OC4J server. Therefore, the host name and port identified by these variables are defined in the rmi.xml file for the OC4J server to which you are directing the request.

    The default port number for the ORMI protocol is 23791. Configure both the host name and port number—if not using the default—in the rmi.xml file in the <rmi-server> element, as follows:

    <rmi-server port="oc4j_ormi_port" host="oc4j_host"> 
  • admin_id admin_password—The administration identity and password. Specify this identity and password for the OC4J server in its principals.xml file.

"Options for the OC4J Administration Management JAR" discusses the options for this tool. Restarting OC4J

You can designate whether the task manager in OC4J automatically detects changes made to deployed applications. Once a change is detected, then OC4J reloads these applications automatically. In this case, you do not need to restart the server when redeploying an application.

The check-for-updates attribute in the <application-server> element in the server.xml file defaults to true, which enables automatic deployment. If true, task manager checks for XML configuration file modifications. Thus, if you set this to false, you can disable automatic refreshing of the configuration to any new XML modifications. Also, setting this attribute to false stops the automatic deployment of any applications until you execute admin.jar -updateConfig. If set to false, you cause the XML configuration to refresh from the XML files and any necessary automatic deployment to occur by using the admin.jar -updateConfig option.

If you enable automatic deployment, then you do not have to restart the OC4J process each time you make a modification to the application. However, enabling automatic deployment also effects your performance. Thus, it is recommended that you enable automatic deployment only in a development environment, not in a production environment.

Even if you have automatic deployment enabled, it does not detect modifications in the global server XML configuration files. Thus, if you modify any of the container-level configuration files, such as data-sources.xml, rmi.xml, or principals.xml, you must restart the OC4J process for these modifications to be recognized.

To restart OC4J using the default parameters, change to the installation root directory, and execute the following:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin    admin_password -restart

This command connects to the OC4J RMI listener port and requests it to restart. It may not work if the JVM is not responding to signals or accepting RMI messages. In this case, stop the JVM in the UNIX environment with the following operating system command: kill process. In the Windows environment, access the Windows Task Manager to terminate the JVM.

1.3.3 Shutting Down OC4J

Shut down OC4J by executing the following:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin    admin-password -shutdown

This command provides a graceful shutdown of the container. If it does not shut down the container, force a rapid shutdown by passing the force argument, as follows:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin    admin-password -shutdown force

If this method does not work, then kill OC4J processes with your operating system commands or tool, depending on your system.

1.3.4 HTTP and RMI Communication

For HTTP applications, clients can send their requests directly to OC4J. The default port number is 8888. You can change this port number in the appropriate *-web-site.xml file, such as the http-web-site.xml file.

For RMI-based applications—such as EJB and JMS—clients should send their requests directly to OC4J. The default RMI port is 23791. Modify this port number in the rmi.xml file. See "Configuring a Listener" for directions.

1.3.5 Quick Start for JSPs and Servlets

To deploy Web applications on OC4J, do one of the following:

  • Place your servlet classes and JSP pages in the j2ee/home/default-web-app directory.

  • Deploy J2EE applications using the admin.jar tool. The J2EE application must be archived in the EAR format.

Placing servlets and JSP pages in the default-web-app directory is the easiest method to deploy applications or to migrate J2EE applications from previous versions of OC4J.

Do the following for quick deployment of servlets or JSPs:

  1. Place your servlet classes in the j2ee/home/default-web-app/WEB-INF/classes subdirectory—in a directory corresponding to their Java package. The servlet is accessible from URLs of the form: http://oc4j_host:8888/servlet/class-name

    For example, place the servlet class my.HelloServlet, as follows:


    Then it is accessible from the following URL:

  2. Place JSP pages anywhere in the j2ee/home/default-web-app directory. They are accessible with URLs of the form: http://oc4j_host:8888/path-to-JSP

    For example, a JSP page in j2ee/home/default-web-app/examples/Hello.jsp is accessible as http://oc4j_host:8888/examples/Hello.jsp.

1.4 Creating the Development Directory

When developing your application, it is good practice to use consistent and meaningful naming conventions. As an example, you could develop your application as modules within a directory named after your application. All the subdirectories under this directory could be consistent with the structure for creating JAR, WAR, and EAR archives. Thus, when you have to archive the source, it is already in the required archive format. Figure 1-1 demonstrates this structure.

Figure 1-1 Development Application Directory Structure

Description of Figure 1-1  follows
Description of "Figure 1-1 Development Application Directory Structure"

Consider the following points regarding Figure 1-1:

1.5 Configuring the FAQ Application Demo

This section describes how to configure the FAQ J2EE demo application, which provides support for managing Frequently Asked Questions (FAQs) and storing/retrieving these FAQs from an Oracle database. FAQs are broadly categorized into Specialization Areas. Each Specialization Area is further sub-categorized into Topics. Each FAQ can be associated with multiple Specialization Areas, where each area has one or more Topics associated with them.

You can generate a list of FAQs (in HTML format) for a given Specialization Area for internal or external publication.

Within the demo, Areas, Topics, and FAQs are entered or updated in the database through Input/Update screens or through a OracleAS Web Services interface. Each Area, Topic and FAQ is uniquely identified by a primary key, which is automatically generated by the system.

This application is a J2EE 1.3 compliant application, developed utilizing the following technologies:

The following sections detail how to configure and deploy the FAQ demo application. In addition, the last section demonstrates how these steps relate to any application that you may wish to configure and deploy to OC4J:

1.5.1 Environment Setup for FAQ Demo

Before you configure OC4J and deploy the FAQ demo, you need to modify the back-end database to contain tables that are necessary for executing the FAQ demo. Oracle Database

Create the database tables for the FAQ demo by executing the SQL table creation script CreateTables.sql script, which is located at http://<hostname>:8888/FAQApp/CreateTables.sql or can be downloaded with the rest of the FAQ application from OTN at in the file.

In an Oracle database environment, you can execute the SQL script through SQL*Plus, connecting to the database and schema where you want the tables to be installed and executing @CreateTables. Please refer to the Oracle database documentation for further instructions on how to use SQL*Plus, running install scripts, creating database users/schemas, and so on.

1.5.2 OC4J System Configuration for FAQ Demo

In order for the FAQ demo to execute properly, the following system modification must be implemented:

  • Modify the default data source, OracleDS, to point to the back-end database.

  • Add the FAQ user to the realm and assign it to the users role.

The directions for each of these steps are covered in the following sections: Data Source Configuration

In order to execute the FAQ application, you must have an Oracle database with the corresponding FAQ application database schema installed on it. The FAQ Application uses the default global data source named OracleDS that ships with the application server, which must be configured so that it connects to the database in which you created the FAQ tables.


An I/O exception is thrown if you do not update the global OracleDS data source appropriately.

If your back-end database uses the thin JDBC driver, is located at myhost:1521/MYSERVICE, and uses the username/password of faq/faq, then the j2ee/home/config/data-sources.xml file is modified to point to the database service at the URL jdbc:oracle:thin:@myhost:1521/MYSERVICE, as follows:

/> Security Configuration

The FAQ demo uses Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider for authentication and user access control capabilities. An application user is added to the default realm through the jazn.jar command line tool, as follows:

> java -jar jazn.jar -adduser <username> <passwd>> java -jar jazn.jar -grantrole users <username>

The previous adds your user (given the username and password) to the realm and then grants the users role to the new user. See the Oracle Application Server Containers for J2EE Security Guide for complete information on using Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider as your security provider.

1.5.3 Deploy the FAQ Demo

Download the FAQ demo application from OTN at in the > file.

  1. Unzip this file to a working directory, which is referred to as <FAQApp_Home>.

  2. Deploy the FAQ application using by either copying the EAR file to the j2ee/home/applications directory or by the admin.jar tool. The following sections explain each method.

  3. Start the OC4J server by executing java -jar oc4j.jar

  4. Execute the FAQ application in your browser, where the default port is 8888.

    http://your_machine_name:8888/FAQApp Deploy Using Automatic Deployment in a Development Environment

As discussed in "Restarting OC4J"), OC4J supports automatic deployment and redeployment of applications, which allows you to make changes to the application EAR file, which are picked up by the server without stopping and restarting OC4J. You enable this through the check-for-updates attribute in the server.xml file. When automatic deployment is enabled, simply modify the XML configuration files, rearchive the application with its XML files into an EAR file, and copy the EAR file to the applications directory. The OC4J server notices the modified date and will redeploy the application, as necessary.


Automatic deployment should only be used in a development environment. The task manager that checks for updates can be time consuming. Turn off automatic deployment in a production environment by setting the check-for-updates attribute to false.

For the first deployment of the FAQ application (locally), do the following:

  1. Copy the <FAQApp_Home>/faq/dist/FAQApp.ear file to the j2ee/home/applications directory.

  2. Modify the j2ee/home/config/server.xml and http-web-site.xml files to register the FAQ application in the j2ee/home/applications directory, as follows:

    1. In the j2ee/home/config/server.xml file, add the FAQApp entry, as follows:

      <application name="FAQApp" path="../applications/FAQApp.ear" />

      This step deploys the FAQ application on OC4J. The path is relative to j2ee/home/config. Since the FAQApp.ear file is in j2ee/home/applications, this makes the path ../applications/FAQApp.ear.

      For full details on the server.xml configuration file, see "Elements in the server.xml File".

    2. In the j2ee/home/config/http-web-site.xml file, bind the FAQ Web application by adding the FAQApp entry, as follows:

      <web-app application="FAQApp" name="FAQAppWeb" root="/FAQApp" />

      This step makes FAQ accessible from the OC4J server.

      For full details on the http-web-site.xml configuration file, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

For more information, see "Manually Adding Applications in a Development Environment", "OC4J Automatic Deployment for Applications", and "What Happens When You Deploy?". Deploy Using the Admin.JAR Tool in All Environments

In the production environment, you should set the check-for-updates attribute to false (see "Restarting OC4J" ) and then use the admin.jar tool for deploying all applications. The admin.jar tool deploys the application and modifies all of the appropriate XML files. This provides for remote deployment. Use the admin.jar command-line tool for registration and deployment, as follows:

java -jar admin.jar      ormi://oc4j_host:oc4j_ormi_port       admin welcome -deploy        -file d:\j2ee\home\applications\FAQApp.ear       -deploymentName FAQApp        -targetPath applications/

This step creates the entry in the server.xml file for the FAQ application. For a complete description of the admin.jar command-line tool, see "Options for the OC4J Administration Management JAR".

You can bind any Web application through the admin.jar tool, as follows:

java -jar admin.jar    ormi://oc4j_host:oc4j_ormi_port   admin welcome -bindWebApp    FAQApp FAQAppWeb http_web_site /FAQApp

This creates the <web-app> entry in the http-web-site.xml configuration file. For a complete description of the admin.jar command-line tool, see "Options for the OC4J Administration Management JAR".

For more information on configuring and managing Web applications, see the http-web-site.xml file, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide .

1.5.4 Deployment Details Explained

Although the development of J2EE applications is standardized and portable, the XML configuration files are not. You may have to configure multiple XML files before deploying any application to OC4J. The necessary server configuration depends on the services that your application uses. For example, if your application uses a database, you must configure its DataSource object in the data-sources.xml file.

For basic applications, such as the FAQ demo, you configure the following OC4J XML files:

  • META-INF/application.xml—The standard J2EE application descriptor for the application is contained within the application.xml file. This file must be properly configured and included within the J2EE EAR file that is to be deployed.

  • server.xml and http-web-site.xml—The application is registered in the server.xml file; the Web application and the context it uses are registered in the http-web-site.xml file (or any other *-web-site.xml file that you choose).

  • data-sources.xml—You must configure the DataSource object in the data-sources.xml file for each database used within the application.

To create and deploy simple J2EE applications, perform the following basic steps:

Basic Step FAQ Application Step Description
Create or obtain the application. Download the from OTN
Make any necessary server environment changes. Set the JAVA_HOME variable
Modify any application XML configuration files. All of the application XML files are provided for you in the FAQ ZIP file.
Update the application standard J2EE application descriptor file. The application.xml file is included in the FAQApp.EAR file.
Build an EAR file including the application—if one does not already exist. If you want to modify the FAQ demo, modify within the src directory, and use ANT to build an EAR file.
Register the application in the appropriate server XML files. Modify the server.xml and http-web-site.xml files.
Configure the database used. Modify the data-sources.xml file.

The following steps describe what modifications to make to deploy the FAQ demo application into OC4J.

  1. We asked you to download the FAQ demo application from the Oracle OTN site.

  2. Make any necessary server environment changes. You must set the JAVA_HOME variable to the base directory of the Java 2 SDK.

  3. All of the application XML files, such as web.xml, are provided for you in the ZIP file, correctly configured.

  4. Update the standard J2EE application descriptor file. The application.xml in the FAQ demo application is provided for you in the ZIP file. OC4J uses the application.xml file as the standard J2EE application descriptor file.

  5. Build an EAR file including the application. You can modify the FAQ demo application and rebuild it using the ANT command. To rebuild and deploy the FAQ demo, execute the following:

    ant deploy

    The ANT build.xml is included in the FAQ ZIP download. To learn more about the ANT file, go to the following Jakarta site:

    If you do not want to rebuild, you can copy the FAQApp.ear from the ZIP file into j2ee/home/applications. This step places the FAQ application in the OC4J server.

  6. Configure the OC4J DataSource for an Oracle database. Modify the default data source, OracleDS, to point to your back-end database, with the correct URL, username, and password.

  7. Register the J2EE application in the server.xml file and its Web application in the http-web-site.xml.

  8. Start OC4J by executing the following command from the j2ee/home/ directory:

java -jar oc4j.jar

For a complete description of all the OC4J starting options, see "Starting OC4J".

Open your Web browser and then specify the following URL:


See "Overview of OC4J and J2EE XML Files" for more information on OC4J XML configuration files.

1.6 Deploying Applications

This section describes how to deploy a J2EE application to the OC4J server and how to bind that application to the server so that you can access the application from OC4J.

1.6.1 Archive Application into an EAR File

Your J2EE application can contain the following modules:

  • Web applications

    The Web applications module (WAR files) includes servlets and JSP pages.

  • EJB applications

    The EJB applications module (EJB JAR files) includes Enterprise JavaBeans (EJBs).

  • Client application contained within a JAR file

Archive the JAR and WAR files that belong to an enterprise Java application into an EAR file for deployment to OC4J. The J2EE specifications define the layout for an EAR file.

The internal layout of an EAR file should be as follows:

Archive Directory Format

Archive these files using the JAR command in the appname directory, as follows:

% jar cvfM appname.ear .

Note that the application.xml file acts as a standard J2EE application descriptor file.

1.6.2 Deployment In a Production Environment Using ADMIN.JAR

OC4J contains a command-line deployment tool for deploying J2EE applications—the admin.jar command. The options for this command are listed in "Standalone OC4J Command-Line Options and Properties". Ensure that automatic deployment is disabled by setting the check-for-updates attribute to false (see "Restarting OC4J").

To deploy a J2EE application with the EAR file to a remote node, execute admin.jar, as follows:

java -jar admin.jar ormi://host:port  	username password  	-deploy  		-file filename -deploymentName app_name  		-targetPath path/destination


  • The host:port is the host and port of the OC4J server.

  • The username password is the administration username and password for the OC4J server.

  • The -file path/filename indicates the local directory and filename for the EAR file.

  • The -deploymentName app_name variable is a user-defined name of the application.

  • The -targetPath path/destination indicates what path on the server node in which to deploy the EAR file. Provide a target path to the directory where the EAR file is copied for deployment. The default path is the applications/ directory.


    If you have a Web application within the EAR file, bind the Web application using the admin.jar -bindWebApp option.

This deployment step creates a new entry in server.xml for the application, as follows:

<application name=app_name path=path_EARfile auto-start="true" /> 


  • The name attribute is the name of the application.

  • The path indicates the directory and filename for the EAR file.

  • The auto-start attribute indicates if this application should be automatically restarted each time OC4J is restarted.

For a description of the elements in server.xml, see "Elements in the server.xml File". Binding the Web Application

To make your J2EE Web application accessible from the OC4J Web server, bind the Web application to the OC4J server using the -bindWebApp option as follows:

java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port username password 
	-bindWebApp app_name web_app_name web_site_name context_root

where the following are the values for -bindWebApp:

  • app_name is the application name, which is the same name used in -deploymentName on the -deploy option. In addition, note that this is the same name that is saved in the <application name=app_name /> attribute in the server.xml file.

  • web_app_name is the name of the WAR file contained within the EAR file—without the .war extension.

  • web_site_name is the name of the *-web-site.xml file that denotes the Web site to which this Web application should be bound. This is the file that will receive the Web application definition.

  • context_root is the root context for the Web module. The Web context defines how the Web application is accessed.

This step creates an entry in the OC4J *-web-site.xml configuration file that is denoted in the web_site_name variable. For a listing of all the options for admin.jar, see "Options for the OC4J Administration Management JAR". Deploy Your Application Manually in a Development Environment

To deploy your application in a development environment, you can modify the XML files by hand. Ensure that automatic deployment is enabled by setting check-for-updates attribute to true. In server.xml, add a new or modify the existing <application name=... path=... auto-start="true" /> entry for each J2EE application. The path should be the full directory path and EAR filename. For our employee example, add the following to the server.xml file:

<application name="employee"  	path="/private/applications/Employee.ear"  	auto-start="true" />

If you included a Web application portion, you must do the following to bind the Web application to the Web server. In *-web-site.xml, add a <web-app ...> entry for each Web application. The application attribute should be the same value as provided in the server.xml file. The name attribute should be the WAR file, without the WAR extension, for the Web application.

For Web application binding for the employee Web application, add the following:

<web-app application="employee" name="Employee-web" root="/employee" /> 

1.6.3 Verifying Deployment

OC4J detects the addition of your application to server.xml. The OC4J server displays a message that your application has been deployed. After the message is displayed, you can invoke requests against your application.

1.6.4 Impact of Undeploying/Redeploying an Application

Undeploying a J2EE application from an OC4J instance results in the following:

  • The application is removed from the OC4J runtime and is no longer accessible.

  • All bindings for the Web applications are removed from all the Web sites to which the Web modules were bound.

  • All application files are removed from both the applications/ and application-deployments/ directories.

During a redeployment, OC4J removes the existing application (EAR/WAR) before redeploying the new EAR. This means, for example, that attempts to access an HTML file that was included in the previous application, but not the new one, will result in "File Not Found" errors.

Also note that a redeployed WAR file overlays the previously expanded WAR, meaning that some older files may persist in the new deployment and will need to be deleted. For example, static HTML files from the previous deployment that are not included in the new WAR may continue to reside in the expanded WAR directory structure, and we would have to be manually deleted.

1.6.5 Impact of "Hot Deploying" an Application

The term hot deployment refers to the process of deploying archive files - EARs, WARs, JARs, etc. - and their associated XML descriptor files on a production application server without re-starting or "bouncing" the server.

When an EAR is redeployed or "hot redeployed" on a running OC4J instance, the status of the classes loaded in the JVM from the previous application may vary. In some cases a classloader may recognize that a class or JAR file in the file system has changed, and reload the class or libary. In other cases whether a new class definition is loaded may depend on whether the JVM tuning allows the garbage collector to flush the existing class definition.

Issues may also exist with respect to serialized objects containing session data. If the class related to a session object changes, it may not be possible to cast the generic session object back to the class, since the class has changed and its variables may occupy a different memory footprint. This may result in lost session data.

Deploying a new Web module to an active OC4J instance also has a negative impact on exising sessions. Specifically, the HTTP sessions for every Web application running within the server instance will be lost by default.

You can avoid this issue on non-clustered OC4J instances by defining a "persistence directory" in each Web application's orion-web.xml file. Existing HTTP sessions will be stored in this temporary location across application deployments.

Specify a relative path to this directory as the value of the persistence-path attribute in the root <orion-web-app> element within each orion-web.xml file. For example:

<orion-web-app ...

Note that this feature is not applicable for OC4J instances within a clustered environment.

1.7 What Happens When You Deploy?

Whether you deploy the application through the admin.jar command or by editing XML files, the following occurs:

OC4J opens the EAR file and reads the descriptors.

  1. OC4J opens, parses the application.xml that exists in the EAR file. The application.xml file lists all of the modules contained within the EAR file. OC4J notes these modules and initializes the EAR environment.

  2. OC4J reads the module deployment descriptors for each module type: Web module, EJB module, connector module, or client module. The J2EE descriptors are read into memory. If OC4J-specific descriptors are included, these are also read into memory. The JAR and WAR file environments are initialized.

  3. OC4J notes any unconfigured items that have defaults and writes these defaults in the appropriate OC4J-specific deployment descriptor. Thus, if you did not provide an OC4J-specific deployment descriptor, you will notice that OC4J provides one written with certain defaults. If you did provide an OC4J-specific deployment descriptor, you may notice that OC4J added elements.

  4. OC4J reacts to the configuration details contained in both the J2EE deployment descriptors and any OC4J-specific deployment descriptors. OC4J notes any J2EE component configurations that require action on OC4J's part, such as wrapping beans with their interfaces.

  5. After defaults have been added and necessary actions have been taken, OC4J writes out the new module deployment descriptors to the application-deployments/ directory. These are the descriptors that OC4J uses when starting and restarting your application. But do not modify these descriptors. Always change your deployment descriptors in the "master" location.

  6. OC4J copies the EAR file to the "master" directory. This defaults to the applications/ directory. However, you can designate where the "master" directory is by the admin.jar -targetPath option.


    If you deploy this EAR file using admin.jar without removing the EAR file from the applications/ directory, the new deployment renames the EAR file prepended with an underscore. It does not copy over the EAR file. Instead, you can copy over the EAR file. OC4J notices the change in the timestamp and redeploys.

  7. Finally, OC4J updates the server.xml file with the notation that this application has been deployed.

1.8 Undeploying Web Applications

You can remove a J2EE Web application from the OC4J Web server using the -undeploy option with the admin.jar command-line tool. The syntax is as follows:

java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port admin adminpassword 
	-undeploy applicationName -keepFiles 

This command removes the deployed J2EE application known as applicationName and results in the following: