14 Using Automatic Deployment in OC4J

This chapter discusses automatic deployment functionality in OC4J, which enables you to automatically reload only modified files within an application to an OC4J instance, rather than requiring that the entire application be redeployed.

This chapter includes the following topics:

Overview of Automatic Deployment in OC4J
Using an Auto-Deployment Directory
Using the Check-for-Updates Feature
Forcing a One-Time Redeployment Using admin.jar

Overview of Automatic Deployment in OC4J

Automatic deployment, or OC4J polling, is a task management feature that automatically checks for changes made to currently deployed applications and modules, and reloads those files that have been modified. This functionality is a tremendous benefit for developers, eliminating the need to go through the deployment process every time code is updated.

By default, OC4J checks for files to deploy every second. This interval is configurable through the taskmanager-granularity attribute of the <application-server> element in the server.xml configuration file. See the Oracle Containers for J2EE Configuration and Administration Guide for details on task manager configuration.

How to Redeploy Updated Files As Needed

In addition to automatic polling, the admin.jar command-line utility includes an -updateConfig option that forces OC4J to check for updated files. You can use this feature in a production environment to check for and reload updated files on an as-needed basis. See "Forcing a One-Time Redeployment Using admin.jar" for details on this feature.

When to Use Automatic Deployment

Automatic deployment is recommended only for standalone OC4J instances in a development environment. It is not recommended for use in production environments.

The reason is that the polling mechanism is invoked by the task manager on a regular schedule and uses system resources. In addition, automatic deployment carries the risk of putting OC4J in an inconsistent state, and errors may result if requests try to execute against OC4J.

Using an Auto-Deployment Directory

Automatic deployment can be initiated by dropping an EAR file into a designated auto-deployment directory within the OC4J instance. This feature should be used only in a standalone OC4J development environment.

The directory must be created on the server hosting the OC4J instance; it is not created by OC4J. An existing directory within OC4J, such as ORACLE_HOME/j2ee/instance/applications, can also be used.

The location of the directory must then be specified in the application-auto-deploy-directory attribute, which must be added to the root <application-server> element in ORACLE_HOME/j2ee/instance/config/server.xml.

The following server.xml entry sets ORACLE_HOME/j2ee/instance/applications as the auto-deployment directory:

<application-server ... 
 application-directory="../applications" check-for-updates="adminClientOnly"
 deployment-directory="../application-deployments"
 application-auto-deploy-directory="../applications">
...
</application-server>

Note:

If the check-for-updates feature is not enabled, OC4J must be restarted for configuration changes made in server.xml to take effect.

Once configured, OC4J will poll the directory for new or updated EAR files every time the task manager is executed. The server compares the timestamp on an EAR file to determine if a redeployment should be initiated. If it should, the EAR will be deployed automatically. Any Web modules packaged as WAR files within the EAR will be bound automatically to the default Web site.

The auto-deployment directory feature is completely independent of OC4J polling. Archives dropped in this directory will be deployed regardless of whether OC4J polling is enabled or disabled.

Using the Check-for-Updates Feature

The check-for-updates feature enables you to redeploy files to an OC4J instance, as the following topics describe:

Enabling or Disabling Check for Updates
Redeploying Configuration Files, Deployment Descriptors, and WAR Files Automatically
Impact of Redeploying a Modified Configuration File Automatically

Note:

An EAR or WAR file copied to the ORACLE_HOME/j2ee/instance/applications directory will be deployed or redeployed by default upon OC4J startup, regardless of whether auto-deployment is enabled.

Enabling or Disabling Check for Updates

You can enable the check-for-updates feature through one of the following methods:

The check-for-updates attribute of the root <application-server> element in ORACLE_HOME/j2ee/instance/config/server.xml. For example:
```
<application-server ... check-for-updates="all" ... />
```
Setting the checkForUpdates system property on the oc4j.jar command line. For example:
```
java -DcheckForUpdates=all -jar oc4j.jar
```

Notes:

The following notes apply to the checkForUpdates system property:

All system properties are prefaced on the command line with a -D.
The value set for this property overrides the value set in server.xml.

Table 14-1 contains the values that can be set for checkForUpdates using either option.

Table 14-1 Valid Values for checkForUpdates

Value Description

Value	Description
`all`	Enables OC4J polling, which starts automatically at the interval specified in the OC4J task manager configuration. The default interval is every 1 second. This option should not be used in Oracle Application Server or production environments. This value also allows the `-updateConfig` option to be passed on the `admin.jar` command line, which forces OC4J to perform a one-time check for updated files. See "Forcing a One-Time Redeployment Using admin.jar" for details on this feature.
`adminClientOnly`	This is the default value set in both standalone OC4J and Oracle Application Server installations. It allows the `-updateConfig` option to be passed on the `admin.jar` command line, which forces OC4J to do a one-time check for updated files, and reload any that have changed. See "Forcing a One-Time Redeployment Using admin.jar" for details on this feature.
`none`	Completely disables OC4J polling, including the `-updateConfig` option.

all

Enables OC4J polling, which starts automatically at the interval specified in the OC4J task manager configuration. The default interval is every 1 second.

This option should not be used in Oracle Application Server or production environments.

This value also allows the -updateConfig option to be passed on the admin.jar command line, which forces OC4J to perform a one-time check for updated files.

See "Forcing a One-Time Redeployment Using admin.jar" for details on this feature.

adminClientOnly

This is the default value set in both standalone OC4J and Oracle Application Server installations. It allows the -updateConfig option to be passed on the admin.jar command line, which forces OC4J to do a one-time check for updated files, and reload any that have changed.

See "Forcing a One-Time Redeployment Using admin.jar" for details on this feature.

none

Completely disables OC4J polling, including the -updateConfig option.

Redeploying Configuration Files, Deployment Descriptors, and WAR Files Automatically

The following files can be automatically redeployed to an OC4J instance:

Modified OC4J-specific XML configuration files in the ORACLE_HOME/j2ee/instance/config directory, including server.xml.
Modified deployment descriptors packaged in an updated EAR file copied to the ORACLE_HOME/j2ee/instance/applications directory.
The following files packaged within an updated WAR file. The WAR can be packaged in an EAR file copied to the ORACLE_HOME/j2ee/instance/applications/ directory, or copied directly to the Web module's ORACLE_HOME/j2ee/instance/applications/webAppName directory.
- Modified deployment descriptors
- Updated files in the WEB-INF/lib/ or WEB-INF/classes/* paths within the WAR
- Updated JSP tag library (TLD) files

Note:

This feature does not currently provide automatic detection of EJB or data source-related configuration changes. This means, for example, that modified files in an EJB JAR file will not be automatically redeployed. OC4J must be restarted to detect such configuration changes and apply them appropriately.

Impact of Redeploying a Modified Configuration File Automatically

The following tables describe the impact of modifying or updating various files when checkForUpdates is set to all, indicating that the feature is enabled. See "Enabling or Disabling Check for Updates" for instructions on enabling OC4J polling.

Table 14-2, "Impact of Modifying OC4J Configuration Files" describes the impact of modifying OC4J configuration files within the ORACLE_HOME/j2ee/instance/config directory in an OC4J instance.

Table 14-2 Impact of Modifying OC4J Configuration Files

Modified File	Action Initiated
`server.xml`	Modifying the OC4J server configuration file causes the OC4J server to be restarted.
`global-web-application.xml`	Modifying this file, used to configure OC4J servlet and JSP containers, forces all Web modules bound to all Web sites within the instance to be restarted.
`application.xml`	Modifying this file, which contains common settings for all applications in this OC4J instance, forces all deployed applications to be restarted.
`*-web-site.xml`	Modifying a Web site configuration file causes the Web site to be restarted. Incoming requests will not be serviced during the restart.

Impact of Redeploying a Modified Deployment Descriptor Automatically

Table 14-3, "Impact of Modifying Files in an EAR" describes the impact of modifying one or more deployment descriptors within an updated EAR file copied to the ORACLE_HOME/applications directory.

Table 14-3 Impact of Modifying Files in an EAR

Modified File	Action Initiated
`application.xml`	Modifying the J2EE standard application deployment descriptor within an EAR forces a restart of the application.
OC4J deployment descriptors	Modifying an OC4J proprietary deployment descriptor packaged within a deployed EAR, such as `orion-application.xml`, causes the EAR to be redeployed and then restarted with the updated configuration.

Impact of Redeploying Modified Files in a War Automatically

Table 14-4, "Impact of Modifying Files in a WAR" describes the impact of modifying files or deployment descriptors within an updated WAR file deployed as part of an application. The updated WAR file can either be packaged in an EAR or be copied to the Web module's ORACLE_HOME/j2ee/instance/applications/webAppName directory.

OC4J checks the timestamp of each file and redeploys only those that have a different timestamp from the other files.

Table 14-4 Impact of Modifying Files in a WAR

Modified File	Action Initiated
`web.xml` or `orion-web.xml`	Modifying either the J2EE standard Web deployment descriptor or the OC4J specific descriptor within an updated WAR file causes the Web module to be restarted with the new configuration.
`WEB-INF/lib/`	Updating a library JAR file in this path forces the Web module to be restarted and modified classes to be reloaded.
`WEB-INF/classes/*`	Updating a file in this path forces the Web module to be restarted and modified classes to be reloaded.
`.tld` files	Updating a TLD file forces the Web module to be restarted.

Forcing a One-Time Redeployment Using admin.jar

The admin.jar command-line utility can be used to administer a standalone OC4J instance. This tool includes an -updateConfig option that enables OC4J polling on an as-needed basis, forcing OC4J to check its directories for updated files and reload any that have changed.

Usage Notes:

The admin.jar tool can only be used against a standalone OC4J instance. It cannot be used against an OPMN-managed instance.
checkForUpdates must be set to either all or adminClientOnly to use this feature.

The utility is installed in ORACLE_HOME/j2ee/instance by default. The OC4J server must be started before this utility can be used, except for converting a data-sources.xml file before deployment.

The syntax for this command follows:

java -jar admin.jar ormi://host:ormiPort adminId adminPassword
 -updateConfig

In the following example, the value supplied for oc4jOrmiPort is the default, 23791. The user name supplied for adminId is the user name for the default administrator account, oc4jadmin.

cd ORACLE_HOME\j2ee\instance
java -jar admin.jar ormi://localhost:23791 oc4jadmin password -updateConfig

See the Oracle Containers for J2EE Configuration and Administration Guide for additional instructions on using admin.jar.