14 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:

What Is Automatic Deployment in OC4J?
Using an "Auto-Deployment" Directory
Using the Check For Updates Feature
Forcing a One-Time Redeployment Using admin.jar

What Is 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.

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 Should Automatic Deployment Be Used?

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 in a designated "auto-deployment" directory within the OC4J instance. Note this feature should only be used 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/home/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/home/config/server.xml.

The server.xml entry below sets ORACLE_HOME/j2ee/home/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 allows you to redeploy files to an OC4J instance, as the following topics describe:

Enabling/Disabling Check For Updates
What Types of Files Are Automatically Redeployed?
What Happens During Redeployment?

Note:

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

Enabling/Disabling Check For Updates

The check for updates feature can be enabled or disabled through the following methods:

The check-for-updates attribute of the root <application-server> element in ORACLE_HOME/j2ee/home/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 minute. 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 minute.

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.

What Types of Files Are Automatically Redeployed?

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

Modified OC4J-specific XML configuration files in the ORACLE_HOME/j2ee/home/config/ directory, including server.xml.
Modified deployment descriptors packaged in an updated EAR file copied to the ORACLE_HOME/j2ee/home/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/home/applications/ directory, or copied directly to the Web module's ORACLE_HOME/j2ee/home/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 that 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.

What Happens During Redeployment?

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/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/home/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.

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.

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/home/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/home by default. Note that the OC4J server must be started before this utility can be used.

The syntax for this command is as follows:

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

In the example below, 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\home
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.