10 Deploying with the OC4J Ant Tasks

OC4J provides a set of Ant tasks for performing deployment-related operations on a specific OC4J instance or on a "group" of instances within a cluster. This chapter describes the Ant tasks and provides guidelines for integrating the tasks into your application build process.

This chapter includes the following sections:

Preparing to Use the Ant Tasks
Invoking the OC4J Ant Tasks

Note:

The OC4J Ant tasks discussed in this chapter are intended to be used with Apache Ant version 1.6.2.

See the following link to access the most recent Apache Ant product documentation:

http://ant.apache.org/manual/

Preparing to Use the Ant Tasks

This section provides prerequisites and guidelines for using the OC4J Ant tasks. It includes the following topics:

Overview of the Ant Tasks
Prerequisites for Using the Ant Tasks
Incorporating the OC4J Ant Tasks into Your Environment
Enabling Logging
Sample build.xml File

Overview of the Ant Tasks

Ant 1.6.2 is installed with OC4J in the ORACLE_HOME/ant/ directory structure. The oracle-ant.jar is installed by default within the ORACLE_HOME/ant/lib directory.

The following Ant-related files are installed with OC4J in the ORACLE_HOME/j2ee/utilities directory:

ant-oracle-classes.jar

A JAR file containing the compiled Ant task classes.
ant-oracle.properties

An editable properties file used to specify the execution properties for the Ant tasks. You may want to edit this file to reflect your environment.
ant-oracle.xml

An XML file that can be optionally imported into the Ant build file (build.xml) using the Ant <import> task. This is only necessary if oracle-ant.jar is not installed in the ORACLE_HOME/ant/lib directory.

Prerequisites for Using the Ant Tasks

The following prerequisites are required to use the deployment-related OC4J Ant tasks as outlined in this documentation.

Ant version 1.6.2 or later must be used.
An ORACLE_HOME environment variable set to the OC4J installed directory must be defined.
A JAVA_HOME environment variable set to the location of the Java2 Standard Edition SDK must be defined.

Incorporating the OC4J Ant Tasks into Your Environment

This section outlines the procedure for setting up your build environment to use the Ant 1.6.2 implementation installed with OC4J by default in ORACLE_HOME/ant.

Add ORACLE_HOME/ant/bin to the system PATH.
Declare the oracle namespace in the <project> element in the Ant build file (build.xml). The OC4J Ant tasks will be referenced in build.xml using this namespace.
```
<project name="test" default="all" basedir="."
  xmlns:oracle="antlib:oracle">
```
(OPTIONAL) Copy the ant-oracle.properties file from the ORACLE_HOME/j2ee/utilities directory to the directory containing your build file (build.xml).

Although you can modify the file in ORACLE_HOME/j2ee/utilities and reference it from your build scripts, it is better to maintain the original file as a template.
(OPTIONAL) Set the values for arguments to pass to the Ant tasks in the ant-oracle.properties file.

The properties within the file are set to the OC4J default values. The file also reads in environment variable settings, such as ORACLE_HOME and JAVA_HOME. You can edit any of these properties as necessary to reflect the configuration of the target OC4J instance.
(OPTIONAL) If you copied the ant-oracle.properties file to your build directory, you must reference it in the build script (build.xml). For example:
```
<property file="ant-oracle.properties"/>
```

Incorporating the Ant Tasks Using Ant 1.6.2 Outside OC4J

This section outlines the procedure for setting up your build environment to use the Ant 1.6.2 implementation outside OC4J.

Add ORACLE_HOME/ant/bin to the system PATH.
Set the ANT_HOME environment variable to point to your Ant installation.
Declare the oracle namespace in the <project> element in the Ant build file (build.xml). The OC4J Ant tasks will be referenced in build.xml using this namespace.
```
<project name="test" default="all" basedir="."
  xmlns:oracle="antlib:oracle">
```
Copy the ant-oracle.properties file from the ORACLE_HOME/j2ee/utilities directory to the directory containing your build file (build.xml).

Although you can modify the file in ORACLE_HOME/j2ee/utilities and reference it from your build scripts, it is better to maintain the original file as a template.
Set the values for arguments to pass to the Ant tasks in the ant-oracle.properties file.

The properties within the file are set to the OC4J default values. The file also reads in environment variable settings, such as ORACLE_HOME and JAVA_HOME. You can edit any of these properties as necessary to reflect the configuration of the target OC4J instance.
Copy the ant-oracle.xml from the ORACLE_HOME/j2ee/utilities directory to the directory containing your build file (build.xml).
Import ant-oracle.xml into your build script (build.xml). For example:
```
<property file="ant-oracle.xml"/>
```

Enabling Logging

You can enable Java logging to help troubleshoot errors that occur when running the Ant tasks. Log messages will be output to the console.

To enable logging:

Create an ANT_OPS environment variable and set the value to -Djava.util.logging.config.file=logging.properties before running the Ant tasks.
Create a logging.properties file containing a single line:
```
oracle.oc4j.admin.jmx.client.CoreRemoteMBeanServer.level=INFO
```
Note that if you create this file in a location other than ORACLE_HOME/ant/bin, you must include the path to the file in the ANT_OPS variable.

You can set the value in the logging.properties file to one of the following Java log level values:

Table 10-1 Java Log Levels

Java Log Level	Description
SEVERE	Log system errors requiring attention from the system administrator.
WARNING	Log actions or a conditions discovered that should be reviewed and may require action before an error occurs.
INFO	Log normal actions or events. This could be a user operation, such as "login completed" or an automatic operation such as a log file rotation.
CONFIG	Log configuration-related messages or problems.
FINE	Log trace or debug messages used for debugging or performance monitoring. Typically contains detailed event data.
FINER	Log fairly detailed trace or debug messages.
FINEST	Log highly detailed trace or debug messages.

For example:

oracle.oc4j.admin.jmx.client.CoreRemoteMBeanServer.level=FINE

Sample build.xml File

The following is an example build.xml file containing a single deploy task. This task will deploy the specified EAR to a standalone OC4J server.

<project name="test" default="deploy" basedir="." xmlns:oracle="antlib:oracle">
    <property name="lib.dir" value="/scratch//temp"/>
    <property name="app.name" value="hello-planet"/>
    <property name="deployer.uri" value="deployer:oc4j:localhost:23791"/>
    <property name="oc4j.admin.user" value="oc4jadmin"/>
    <property name="oc4j.admin.password" value="password"/>
    ...
  <target name="deploy-ear" depends="setup,check-oc4j-available>
   <echo message="-----> Deploying the application module deployment (ear) file"/>
   <oracle:deploy deployerUri="${deployer.uri}"
                  userId="${oc4j.admin.user}" 
                  password="${oc4j.admin.password}"
                  file="${lib.dir}/${app.name}.ear" 
                  deploymentName="${app.name}"
                  bindAllWebApps="default-web-site"
                  logFile="${log.dir}/deploy-ear.log"/>  </target>
  ...
</project>

Invoking the OC4J Ant Tasks

This section provides guidelines on using the deployment-related Ant tasks provided with OC4J.

Each task is specified within a <target> element in the build file (build.xml), in a subelement formatted as <oracle:taskName. ... /> Note that oracle is the namespace used to reference the OC4J Ant tasks. See "Sample build.xml File" for a sample build file.

See the following sections for guidelines on invoking each task:

Setting the Deployer URI
Deploying an EAR File
Deploying a Standalone WAR File
Deploying a Standalone RAR File
Binding All Web Modules to a Single Web Site
Binding a Specific Web Module to a Specific Web Site and Setting the Context URI
Undeploying an Archive
Updating Modified Classes Only in a Deployed EJB Module
Installing a Shared Library
Starting or Stopping an Application

Setting the Deployer URI

The key property passed to an Ant task deployerUri, which specifies the target OC4J instance(s) for the task. The syntax for the URI varies depending on the instance(s) being targeted.

See the following for the format of this URI:

Invoking a Task on a Group of OC4J Instances Within a Cluster
Invoking a Task on a Specific OC4J Instance Within a Cluster
Invoking a Task on a Standalone OC4J Server

Invoking a Task on a Group of OC4J Instances Within a Cluster

Use the following URI to specify all OC4J instances within a group as the target. A group is defined as a loosely syncronized set of like-named OC4J instances within the same cluster topology. For example, all instances named home within a cluster would collectively form a group across which configuration operations can be executed simultaneously.

The URI utilizes the OPMN-based clustering framework. You only need to supply the host name and optionally OPMN request port for any Oracle Application Server node within the cluster; the application is then able to retrieve the host names and OPMN ports for all other nodes within the cluster.

The URI syntax is as follows:

deployer:cluster:[rmis]:opmn://host[:opmnPort]/oc4jInstanceName

For example:

deployer:cluster:opmn://node1/home

Table 10-2 URI Parameters for Targeting a Group

Parameter	Description
`rmis`	Optional. Include if the target utilizes ORMI over SSL, or ORMIS.
`host`	Required. The host name of an Oracle Application Server node within the cluster. Any node can be specified; the list of other nodes in the cluster will be retrieved from this node.
`opmnPort`	Optional. The OPMN request port, as specified in `opmn.xml`. If not specified, the default port `6003` will be used.
`oc4jInstanceName`	Required. The common instance name shared by OC4J instances within the group.

Invoking a Task on a Specific OC4J Instance Within a Cluster

Use the following URI to target a specific OC4J instance within a cluster. Note that cluster: is replaced by oc4j: in the prefix.

Specify the host name for the Oracle Application Server node hosting the instance. If you are not sure of the host name or port for the node, you can specify the host name for another node within the cluster, as well as the name of the Oracle Application Server instance. The application will then use the OPMN clustering framework to locate the node hosting the Oracle Application Server instance.

The URI syntax is as follows:

deployer:oc4j:[rmis]:opmn://host[:opmnPort]/[iASInstanceName]
/oc4jInstanceName

For example:

deployer:oc4j:opmn://server.company.com:6015/instance2/home

Table 10-3 URI Parameters for Targeting a Specific Instance

Parameter	Description
`rmis`	Optional. Include if the target utilizes ORMI over SSL, or ORMIS.
`host`	Required. The host name of the Oracle Application Server node to target within the cluster.
`opmnPort`	Optional. The OPMN request port, as specified in `opmn.xml`. If not specified, the default port `6003` will be used.
`iASInstanceName`	Optional. The name of the Oracle Application Server instance to target, if it does not reside on the node specified for `host`.
`oc4jInstanceName`	Required. The name of the target OC4J instance.

Invoking a Task on a Standalone OC4J Server

Use the following URIs to target a standalone OC4J server instance.

If using RMI, the URI syntax is as follows:

deployer:oc4j:host:rmiPort

If using ORMI over SSL (ORMIS), specify the following:

deployer:oc4j:rmis:host:ormisPort

For example:

deployer:oc4j:myserver:23791
deployer:oc4j:rmis:myserver:23943

Table 10-4 URI Parameters for Targeting Standalone OC4J

Parameter	Description
`rmis`	Required if the target utilizes ORMI over SSL, or ORMIS.
`host`	Required. The host name of an Oracle Application Server node within the cluster. Any node can be specified; the list of other nodes in the cluster will be retrieved from this node.
`rmiPort`	Required if RMI used. The RMI port, as specified in the instance-specific `rmi.xml` file.
`ormisPort`	Required if ORMIS used. The SSL port, as specified in the instance-specific `rmi.xml` file.

Deploying an EAR File

Use the deploy task to deploy a J2EE application packaged in an EAR file. The following example shows the properties typically supplied to deploy an EAR file.

<oracle:deploy 
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
file="${lib.dir}/${app.name}.archiveType"
deploymentName="${app.name}"
bindAllWebApps="default-web-site"
deploymentPlan="localPath/filename"
logFile="${log.dir}/deploy-ear.log"/>

The following table summarizes the properties that can be passed to the task.

Table 10-5 deploy Properties for EAR Deployment

Parameter	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`file`	The path and file name of the archive to deploy.
`deploymentName`	The user-defined application deployment name, used to identify the application within OC4J.
`bindAllWebApps`	Binds all Web modules to the specified Web site. Specify the `name` portion of the `name_web-site.xml` file that configures the Web site.
`deploymentPlan`	Optional. The path and file name for a deployment plan to apply to the application. The plan would have been saved during a previous deployment as an XML file. The file must exist on the local host.
`parent`	The parent application of this application. The default is the global or `default` application.
`targetPath`	Optional. The directory to deploy the EAR to. If not specified, the EAR is deployed to the `ORACLE_HOME/j2ee/home/applications/` directory by default. The deployed EAR file is also copied to this directory. Each successive deployment will cause this EAR file to be overwritten.
`deploymentDirectory`	Optional. The directory containing the OC4J-specific deployment descriptors and generated files, such as compiled JSP classes and EJB wrapper classes. The default directory is `ORACLE_HOME/j2ee/home/application-deployments/`.
`enableIIOP`	Optional. Include to generate IIOP client stubs on the OC4J server. The application-level stubs generated for all EJB modules are output to an archive named `_iiopClient.jar` in the`/j2ee/home/application-deployments/appName` directory. In addition, stubs for each individual EJB module are generated in an archive with the same name in the `/j2ee/home/application-deployments/appName/ejbModuleName/` directory. Note that the `GenerateIIOP` system property must be enabled at OC4J startup to use this feature. This property is set as `-DGenerateIIOP=true` on the OC4J command line for OC4J standalone or as an `oc4j-options` value in `opmn.xml`.
`iiopClientJarPath`	Optional. The path and filename of the JAR to output IIOP client stubs to. The application-level stubs generated for all EJB modules are output to an archive named `_iiopClient.jar` in the`/j2ee/home/application-deployments/appName` directory. If a path is supplied, the archive is also set on this path. In addition, stubs for each individual EJB module are generated in an archive with the same name in the `/j2ee/home/application-deployments/appName/ejbModuleName/` directory. Note that the `GenerateIIOP` system property must be enabled at OC4J startup to use this feature. This property is set as `-DGenerateIIOP=true` on the OC4J command line for OC4J standalone or as an `oc4j-options` value in `opmn.xml`.
`logFile`	The path and name for a log file generated for the deployment.

Deploying a Standalone WAR File

Use the deploy task to deploy a standalone Web module packaged in a WAR file.

<oracle:deploy
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
file="${lib.dir}/${app.name}.war"
deploymentName="${app.name}"
bindAllWebApps="default-web-site"
logFile="${log.dir}/deploy-war.log"/>

The following table summarizes the WAR-specific properties that can be passed to the task.

Table 10-6 deploy Properties for Standalone WAR Deployment

Property	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`file`	The path and file name of the archive to deploy.
`deploymentName`	The user-defined module deployment name, used to identify the module within OC4J.
`bindAllWebApps`	Binds the Web module to the specified Web site. Specify the `name` portion of the `name_web-site.xml` file that configures the Web site.
`deploymentPlan`	Optional. The path and file name for a deployment plan to apply to the application. The plan would have been saved during a previous deployment as an XML file. The file must exist on the local host.
`parent`	Optional. The parent application of this module. The default is the global or `default` application.
`targetPath`	Optional. The directory to deploy the archive to. If not specified, the archive is deployed to the `ORACLE_HOME/j2ee/home/applications/` directory by default. The deployed archive file is also copied to this directory. Each successive deployment will cause this file to be overwritten.
`deploymentDirectory`	Optional. The directory containing the OC4J-specific deployment descriptors and generated files, such as compiled JSP classes and EJB wrapper classes. The default directory is `ORACLE_HOME/j2ee/home/application-deployments/`.
`contextRoot`	The Web module context, which will be appended to the URL used to access the application through a Web browser. For example, if you supply `/petstore` as the context root, the module could be accessed with the following URL: `http://node1.company.com:7777/petstore`
`logFile`	The path and name for a log file generated for the deployment.

Deploying a Standalone RAR File

The deploy task deploys a J2EE application or a standalone module packaged in an archive. The following example shows the properties typically supplied to deploy a standalone RAR file.

<oracle:deploy 
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
file="${lib.dir}/${app.name}.rar"
deploymentName="${app.name}"
grantAllPermissions="true"
logFile="${log.dir}/deploy-rar.log"/>

The following table summarizes the properties that can be passed to the task.

Table 10-7 deploy Task Properties for Standalone RAR Deployment

Parameter	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`file`	The path and file name of the archive to deploy.
`deploymentName`	The user-defined connector name, used to identify the connector within OC4J.
`deploymentPlan`	Optional. The path and file name for a deployment plan to apply to the application. The plan would have been saved during a previous deployment as an XML file. The file must exist on the local host.
`nativeLibPath`	Optional. The path to the directory containing native libraries (such as DLLs) within the RAR file.
`grantAllPermissions`	Include and set to `true` to grant all runtime permissions requested by the resource adapter, if required.
`logFile`	The path and name for a log file generated for the deployment.

Redeploying an Archive

The redeploy task can be used to redeploy a previously-deployed archive. Note that the previous version of the archive will be undeployed as part of this process.

The syntax is as follows:

<oracle:redeploy 
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
file="${lib.dir}/${app.name}.archiveType"
deploymentName="${app.name}"
keepsettings="true"
sequential="true"
logFile="${log.dir}/deploy-ear.log"/>

Table 10-8 redeploy Task Properties

Subswitch	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`file`	Required. The path and file name of the archive to redeploy.
`deploymentName`	Required. The user-defined application deployment name, used to identify the application within OC4J. This value must exactly match the name of the existing application on the server.
`keepsettings`	Optional. If included, the redeployed application will fetch and use the deployment plan from the previous deployment. Values set in deployment descriptors packaged within the archive will be ignored. If not specified, values will be set to those in the deployment descriptors packaged with the archive.
`sequential`	Optional. Include to deploy the archive to each OC4J instance within the cluster in sequence. The redeployment on each target must complete before continuing on to the next target. Requests will not be routed to an instance while the EAR is being deployed to it. If not included, the archive is simultaneously deployed to all instances by default. This option is valid in a clustered environment only; it is not valid for standalone OC4J.

Binding All Web Modules to a Single Web Site

The bindAllWebApps task binds the Web modules within a previously deployed EAR to a specified Web site

<oracle:bindAllWebApps
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="${app.name}"
webSiteName="${oc4j.binding.module}"

The following table summarizes the properties that can be passed to the task.

Table 10-9 bindAllWebApps Task Properties

Property	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`deploymentName`	The user-defined name of the application that the Web modules belong to, set when the application was deployed.
`webSiteName`	The name of the `name_web-site.xml` file that denotes the Web site that this Web application should be bound to.

Binding a Specific Web Module to a Specific Web Site and Setting the Context URI

The bindWebApp task binds a specific Web module to the Web site that will be used to access it. You can also specify the context URI for the module.

<oracle:bindWebApp
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="${app.name}"
webModule="${web.name}"
webSiteName="${oc4j.binding.module}"
contextRoot="/${context.root}"/>

The following table summarizes the properties that can be passed to the task.

Table 10-10 bindWebApp Task Properties

Property	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`deploymentName`	The user-defined name of the application the Web module belongs to, set when the application was deployed.
`webModule`	The name of the Web module to be bound to the Web site. This should be the name of the WAR file contained within the EAR file, without the`.WAR` extension.
`webSiteName`	The name of the `name_web-site.xml` file that denotes the Web site that this Web application should be bound to.
`contextRoot`	The context URI for the Web module, such as `/utility`. This will be appended to the URL used to access the application through a Web browser; for example `http://localhost:8888/utility`.

Undeploying an Archive

Use the undeploy task to remove an application or module from the OC4J instance(s). Note that the isConnector="true" property must be included if you are undeploying a standalone resource adapter (RAR).

<oracle:undeploy
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="${app.name}"
logFile="${log.dir}/filename.log"/>

The following table summarizes the properties that can be passed to the task.

Table 10-11 undeploy Task Properties

Property	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`deploymentName`	The user-defined name of the application or module to undeploy. This is the name set when the archive was deployed.
`isConnector`	Include and set to `true` if undeploying a standalone RAR.
`logFile`	The path and name for a log file generated for the deployment.

Updating Modified Classes Only in a Deployed EJB Module

The updateEJBModule task allows incremental or partial redeployment of EJB modules within an application running in an OC4J instance. This feature makes it possible to redeploy only those beans within an EJB JAR that have changed, without requiring the entire module to be redeployed.

<oracle:updateEJBModule
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="${app.name}"
ejbModuleName="${ejb.jar}"
file="${new.ejb.jar}"
logFile="${log.dir}/filename.log"/>

The following table summarizes the properties that can be passed to the task.

Table 10-12 updateEJBModuleTask Properties

Property	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`deploymentName`	Required. The name of the application the EJB is part of. If you are updating a standalone EJB module, specify the `default` application.
`ejbModuleName`	Required. The name of the EJB JAR file to be updated as defined in `application.xml`.
`file`	Required. The path and file name of the updated EJB JAR.
`logFile`	The path and name for a log file generated for the update.

Installing a Shared Library

Use the publishSharedLibrary task to install a shared library within a single OC4J instance. Once installed, the shared library will be available for use by applications within the instance.

Note:

In the current release, this task can only be run against a single standalone or OPMN-managed OC4J instance. It will not create a shared library across multiple instances with a cluster.

The shared library binaries will be installed in the ORACLE_HOME/j2ee/instance/shared-lib directory within the OC4J instance. At the same time, a <shared-library> element declaring the shared library will be added to the server.xml file on the OC4J instance.

<oracle:publishSharedLibrary
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
libraryName="name"
libraryVersion="version"
logFile="${log.dir}/filename.log">
  <oracle:uploadCodeSource path="path/file" />
  <oracle:addCodeSource path="path/file" />
  <oracle:sharedLibraryImport libraryname="name" min-version="version" 
      max-version="version" />
</oracle:publishSharedLibrary>

To upload a new code source to the OC4J server, specify the path and file name of the JAR or ZIP archive file to upload in a nested <oracle:uploadCodeSource> element. The path can be absolute or relative to the current working directory.
To add a JAR or ZIP that already exists on the server, specify the path and file name in an <oracle:addCodeSource> element. Specify an absolute or relative path pointing to the location of the existing file on the OC4J server. Note if a relative path is used, it will be interpreted as relative to ORACLE_HOME.
To import an existing shared library into the new shared library, specify the shared library name as defined within the OC4J instance in an <oracle:sharedLibraryImport> element. Note that you can optionally specify the minimum and/or maximum version of the library to import.

Include one element for each code source to upload or add. Do the same for each existing shared library to import.

The following example uploads two JAR files to the target OC4J server:

<oracle:publishSharedLibrary
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
libraryName="acme.common"
libraryVersion="2.5"
logFile="${log.dir}/filename.log">
  <oracle:uploadCodeSource path="/acme/acme-apis.jar" />
  <oracle:uploadCodeSource path="/acme/acmeImpl.jar" />
</oracle:installSharedLibrary>

The following table summarizes the properties that can be passed to the task.

Table 10-13 publishSharedLibraryTask Properties

Property	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`libraryName`	Required. The name of the shared library. In cases where common APIs are implemented by multiple vendors, the name should include both the vendor name and the name of the technology; for example, `oracle.jdbc` or `xerces.xml`.
`libraryVersion`	Required. The shared library version. This value should ideally reflect the code implementation version.
`parentName`	Optional. The name of the parent shared library, if applicable.
`parentVersion`	Optional. The parent shared library version, if applicable.
`logFile`	The path and name for a log file generated for the update.

Modifying an Existing Shared Library

Use the modifySharedLibrary task to make changes to an existing shared library installed within a single OC4J instance.

Note:

In the current release, this task can only be run against a single standalone or OPMN-managed OC4J instance. It will not create a shared library across multiple instances with a cluster.

<oracle:modifySharedLibrary
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
libraryName="name"
libraryVersion="version"
logFile="${log.dir}/filename.log">
  <oracle:uploadCodeSource path="path/file" />
  <oracle:removeCodeSource path="path/file" />
  <oracle:addCodeSource path="path/file" />
  <oracle:addImport libraryName="name" min-version="version 
      max-version="version" />
  <oracle:removeImport libraryname="name" min-version="version 
      max-version="version" />
</oracle:modifySharedLibrary>

To upload a new code source to the OC4J server, specify the path and file name of the JAR or ZIP archive file to upload in a nested <oracle:uploadCodeSource> element. The path can be absolute or relative to the current working directory.
To add a JAR or ZIP that already exists on the server, specify the path and file name in an <oracle:addCodeSource> element. Specify an absolute or relative path pointing to the location of the existing file on the OC4J server. Note if a relative path is used, it will be interpreted as relative to ORACLE_HOME.
Use <oracle:removeCodeSource> to remove an existing code source from the shared library. Specify the location of the code source in the ORACLE_HOME/j2ee/instance/shared-lib directory within the OC4J instance.
To import an existing shared library into the shared library, specify the shared library name as defined within the OC4J instance in an <oracle:addImport> element. Note that you can optionally specify the minimum and/or maximum version of the library to import.
To remove an imported shared library, use an <oracle:removeImport> element.

Include one element for each code source to upload, add or remove. Do the same for each existing shared library to import or remove.

The following example removes a code source and an imported library from the target shared library:

<oracle:modifySharedLibrary
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
libraryName="acme.common"
libraryVersion="2.5"
logFile="${log.dir}/filename.log">
  <oracle:removeCodeSource path="c:/oracle/j2ee/home/shared-lib/acme-apis.jar" />
  <oracle:removeImport libraryName="foo" min-version="2.0"/>
</oracle:installSharedLibrary>

The following table summarizes the properties that can be passed to the task.

Table 10-14 modifySharedLibraryTask Properties

Property	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`libraryName`	Required. The name of the shared library to affect. In cases where common APIs are implemented by multiple vendors, the name should include both the vendor name and the name of the technology; for example, `oracle.jdbc` or `xerces.xml`.
`libraryVersion`	Required. The shared library version. This value should ideally reflect the code implementation version.
`logFile`	The path and name for a log file generated for the update.

Starting or Stopping an Application

You can use the start or stop task to start, stop or restart an application and its child applications as part of a deployment operation on a specific OC4J instance or across an entire cluster.

<oracle:start | stop
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="${app.name}"

The following table summarizes the properties that can be passed to the task.

Table 10-15 start/stopTask Properties

Property	Description
`deployerUri`	The URI specifying the deployment target.
`userId`	The administrator user name for the target OC4J instance.
`password`	The administrator password for the target OC4J instance.
`deploymentName`	Required. The name of the application to start or stop.