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 Exploded-Directory Deployment for Application Development and Testing
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.

Exploded-Directory Deployment

If you are developing J2EE applications with OC4J, you can use exploded-directory deployment for rapid development and test cycles. Exploded-directory deployment enables you to deploy an application to a set of distributed, expanded directories without packaging the application in an enterprise application archive (EAR) or Web application archive (WAR) file.

One exploded directory represents the application-level directory, and the rest are the modules to be deployed. You can place module directories under the application-level directory, or you can place them elsewhere and specify an alternate path to each module directory.

Redeployment of 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 Exploded-Directory Deployment for Application Development and Testing

Exploded-directory deployment, equivalent to deployment of a J2EE application packaged in an EAR file, facilitates application testing by supporting partial redeployment. When you deploy an EAR file, OC4J makes a copy of the EAR and then executes the application by accessing the files that are in that copy. In exploded-directory deployment, OC4J copies only the deployment plan and then executes the application by accessing the original application files in your file system.

You can deploy an application from its standard, fully expanded directory structure instead of a packaged application archive. With exploded-directory deployment, OC4J reads all Web content, class files, libraries, deployment descriptors, and so on directly from the file system. You can deploy all types of standard J2EE modules and applications in this manner, including Web modules, EJB modules, and full J2EE applications. An exploded directory must conform to the standard J2EE directory structure for applications and components.

You can specify the path to an application directory in the OC4J configuration file, server.xml. The modules of an application, however, do not need to be in subdirectories of the application-level directory. You can place the module directories elsewhere in the file system and specify an alternate path to each module in the application.xml deployment descriptor for the application. You can also specify the alternate paths in the OC4J application deployment descriptor, orion-application.xml.

Building and Deploying a J2EE Application from a Master Directory

While developing an application, you can modify, compile, and execute your classes quickly with exploded-directory deployment. OC4J automatically deploys your application as you develop it within an exploded-directory format.

This automatic deployment occurs whenever a timestamp changes in the application-level directory, which is a master directory, like appname in Figure 14-1. The subdirectories of the master directory, located within it or elsewhere in the file system, are application modules for OC4J to deploy.

To perform an exploded-directory deployment, you need to modify OC4J configuration files for the initial deployment of the application. The location of the master directory is the value of the path attribute in the server.xml configuration file for OC4J. An alternate path for each J2EE module in application.xml and, optionally, in orion-application.xml enables OC4J to locate the module directories. The format of a path name is platform dependent. In a Linux or UNIX environment, the path name can contain forward slashes. In a Windows environment, the path name can contain back slashes. Some examples of path names follow:

D:\sharedfolder\My resource

/scratch/sharedfolder/my resource

For exploded-directory deployment, the application's master directory and module directories must have the same hierarchical format as required for an EAR, WAR, or JAR file. A set of directory paths represents the application, one path for the master directory and one or more alternate paths, each pointing to the location of an application module. Figure 14-1 shows the directory structure for a J2EE application that has the master directory appname. The directory structure under appname is similar to the structure within an EAR file.

Figure 14-1 Application Directory Structure

Description of "Figure 14-1 Application Directory Structure "

To build and deploy a J2EE application from a master directory:

Place the files in any directory or set of directories, as follows:
1. Replace each EJB JAR, WAR, client JAR, and RAR file name with a directory name of your choice to represent a separate module.
  
  Figure 14-1 represents these directory names with ejb_module/, web_module/, client_module/, and connector_module/.
2. Place the classes for each module within the appropriate directory structure that maps to their package structure.
Edit the server.xml file and add a new <application> element that specifies the path to the exploded directory that is to be deployed.

For example:
```
<application name="dwp" path="file://d:/eclipse/workspace/dwp/test-app"/>
```
List the absolute or relative paths of J2EE modules in application.xml and, optionally, in orion-application.xml.

In the j2ee/home/applications/appname/META-INF/application.xml file, modify the <web-uri>, <ejb>, and <client> elements within <module> elements to designate the directory path name for each module (not the JAR or WAR file name). To designate the directories where these modules exist, the path name in each of these elements should be relative to the master directory and should be the parent of the WEB-INF or META-INF directories in each of these application types.

If application.xml and orion-application.xml refer to the same Java EE module, the key is the path specification (absolute or relative, directory URL or archive file URL). The key must be identical in both files, if they are included.

For example, the following <web-uri> element designates myapp-web/ as the Web module directory within the <web> and <module> elements:
```
<module>
  <web>
    <web-uri>myapp-web</web-uri>
  </web>
</module>
```
Note:
In OC4J 10g (10.1.3.5.0), the system application, represented by the j2ee/home/config/system-application.xml file, is the ultimate parent of all applications. Oracle recommends, however, that you deploy Web modules to the default application, represented by j2ee/home/config/application.xml.
In the j2ee/home/config/default-web-site.xml file, add a new <web-app> element for each Web application that is in the exploded directory.

For example:
```
<web-app application="dwp" module="web" context-root="/dwp"/>
```
The <web-app> element binds the application to a Web site. The value of the application attribute of <web-app> should be the same as the application name in the server.xml file. The value of the name attribute should be the directory path to the Web application, like the path in the <web-uri> element in the application.xml file.
If the application being deployed is a standalone Web application in exploded WAR format, you can deploy the application as a standalone Web module to the default application:
1. Edit the application.xml file and add a new <web-module> element that specifies the path to the exploded directory that is to be deployed, as follows:
```
<web-module id="dwp" path="file://d:/eclipse/workspace/dwp/web"/>
```
2. Edit the default-web-site.xml file and add a new <web-app> element for the Web module, as follows:
```
<web-app application="default" module="dwp" root="/dwp"/>
```

When OC4J starts, the application and Web modules will be deployed from the specified exploded-directory paths.

Cloning an Application Module to an Exploded Directory

It is possible to create an entire exploded application from an application module by cloning the application.xml file to an exploded-application.xml file, removing the unneeded entries, and then adding the application to server.xml. This keeps your J2EE module outside of the default application and within its own application that can be started, stopped, and managed.

To clone an application to an exploded directory:

Copy the application.xml file to exploded-application.xml in the ORACLE_HOME/j2ee/instance/config directory:
```
>cd j2ee/home/config
>cp application.xml exploded-application.xml
```

Edit server.xml and add the following element:

<application name="exploded" path="exploded-application.xml" parent="default" 
 start="true" />

Edit exploded-application.xml, remove the unneeded application modules (that is, most of them), and then add an entry for your Web module, like this:
```
<web-module id="exp" path="d:/temp/exp/how-to-cluster-web" />
```
Bind the exploded Web module to the exploded Web site:
```
<web-app application="exploded" name="exp" load-on-startup="true" context-root="/exp" />
```
Instead of the default Web site, you use exploded because that is the name of the new containing application.

Reloading Modified Classes from an Exploded Directory

If you are using exploded-directory deployment and change a JavaServer Pages (JSP) module in the exploded-directory structure, the default OC4J settings cause it to notice the change and recompile the page. The implicit default setting, with main_mode, should cause OC4J to pick up any changes to JSP modules.

If a changed JSP does not get recompiled, try forcing the browser to not load the page from its cache by using SHIFT plus RELOAD.

If you change any compiled Java class that the JSP module uses, such as a Web bean, DTO, or DAO, OC4J does not pick up the changed class with the JSP module.

To reload modified classes from an exploded directory:

Set the check-for-updates attribute to all in the <application-server> element of server.xml:
```
<application-server   
    application-directory="../applications"
    check-for-updates="all"
    deployment-directory="../application-deployments" 
    connector-directory="../connectors" 
    schema-major-version="10" schema-minor-version="0" > 
```
Any class changes you make in the exploded directory should then be picked up.

For more information about the check-for-updates attribute, see "Using the Check-for-Updates Feature".

Note:

You can achieve better performance by deploying a JAR file. During execution, the entire JAR file is loaded into memory and indexed. This is faster than reading in each class from the development directory when necessary.

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.

The EAR or WAR file is also deployed when its timestamp is newer than the timestamp of the directory that contains the file.

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 either 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-related 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 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 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 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.