| Oracle® Containers for J2EE Deployment Guide 10g (10.1.3.1.0) Part Number B28951-01 |
|
|
View PDF |
| Oracle® Containers for J2EE Deployment Guide 10g (10.1.3.1.0) Part Number B28951-01 |
|
|
View PDF |
OC4J provides a set of Ant tasks for performing deployment-related operations on a specific OC4J instance or simultaneously on all OC4J instances in a group. In Oracle Application Server 10g Release 3 (10.1.3.1.0), a group is a synchronized set of OC4J instances that belong to the same cluster topology, which is two or more loosely connected Oracle Application Server nodes.
This chapter describes the Ant tasks and provides guidelines for integrating them into your application build process. With OC4J Ant tasks, you can perform the following operations on an OC4J instance or group of instances within a cluster:
Deploy an application (EAR), a standalone Web module (WAR), a standalone EJB module (EJB JAR), or a standalone resource adapter (RAR)
Undeploy an application, Web module, EJB module, or resource adapter
Incrementally update a deployed EJB module with modified classes
Create, modify, or remove shared libraries for an application
Start, restart, or stop applications
Restart or stop an OC4J instance or group of instances
Add, test, and remove data sources and data source connection pools
Add and remove JMS connection pools and destinations
Add and remove JMS connection pools and destinations
Table 10-1 lists the OC4J ant tasks with references to their descriptions.
Table 10-1 OC4J Ant Tasks
You can perform similar deployment tasks through the Application Server Control Console or the admin_client.jar command-line utility. Chapter 9, "Using the Application Server Control Console for Deployment" describes how to use the Application Server Control Console for deployment. Chapter 11, "Using the admin_client.jar Utility for Deployment" explains how to use admin_client.jar for deployment tasks.
This chapter includes the following sections:
|
Note: The OC4J Ant tasks discussed in this chapter are intended to be used with Apache Ant version 1.6.5.See the following link to access the most recent Apache Ant product documentation: http://ant.apache.org/manual/ |
You can also use OC4J Ant tasks to deploy Web applications through Eclipse, as "Using Ant Tasks from the OC4J Administration Client with Eclipse" describes.
This section provides prerequisites and guidelines for using OC4J Ant tasks. It includes the following topics:
The following prerequisites are required to use the deployment-related OC4J Ant tasks that this document describes:
Ant version 1.6.5 or later
Ant 1.6.5 is installed with OC4J in the ORACLE_HOME/ant directory structure.
An ORACLE_HOME environment variable set to the OC4J installed directory
A JAVA_HOME environment variable set to the location of the Java2 Standard Edition SDK
For information about setting these environment variables, see the Oracle Containers for J2EE Configuration and Administration Guide.
The OC4j installation includes Ant 1.6.5 and the files for the OC4J Ant tasks. Before you can use the Ant tasks, you need to incorporate them into your environment.
The oracle-ant.jar file 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
A properties file, ant-oracle.properties, that you can edit to specify execution properties for the Ant tasks
ant-oracle.xml
An XML file that you can import into the Ant build file (build.xml) using the Ant <import> task. This is necessary only if oracle-ant.jar is not installed in the ORACLE_HOME/ant/lib directory.
Perform the following procedure to set up your build environment for using the Ant 1.6.5 implementation, which is installed with OC4J by default in ORACLE_HOME/ant:
Add ORACLE_HOME/ant/bin to the system PATH environment variable.
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. For example:
<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 or instances.
(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"/>
This section outlines the procedure for setting up your build environment to use the Ant 1.6.5 implementation outside OC4J.
Add ANT_HOME/ant/bin to the system PATH environment variable.
Set the ANT_HOME environment variable to point to your Ant installation and the JAVA_HOME environment variable to point to the location of the Java2 Standard Edition SDK.
The common ANT installation directory is ORACLE_HOME/ant
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 for ORACLE_HOME and JAVA_HOME. You can edit any of these properties as necessary to reflect the configuration of the target OC4J instance or instances.
Copy the ant-oracle.xml file from the ORACLE_HOME/j2ee/utilities directory to the directory containing your build file (build.xml).
At the top level of your build file, add this <import> element:
<import file="ant-oracle.xml"/>
The key property passed to an Ant task is deployerUri, which specifies the target OC4J instance or instances for the task. The syntax for the URI varies depending on the instance or instances being targeted.
See the following for the format of this URI:
Use the following URI to specify all OC4J instances in a group as the deployment target. A group is a synchronized set OC4J instances that belong to the same cluster topology. For example, you could specify default_group as the target to perform a deployment operation simultaneously on all OC4J instances that belong to the default group (named default_group) in a cluster.
The URI utilizes the OPMN-based clustering framework. You need to supply only the host name and, optionally, an 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 follows:
deployer:cluster:[rmis]:opmn://host[:opmnPort]/groupName
For example:
deployer:cluster:opmn://node1/default_group
Table 10-2 URI Parameters for Targeting a Group
| Parameter | Description |
|---|---|
|
|
Optional. Include if the target utilizes ORMI over SSL, or ORMIS. |
|
|
Required. The host name of an Oracle Application Server node within a cluster. Any node can be specified; the list of other nodes in the cluster will be retrieved from this node. |
|
|
Optional. The OPMN request port, as specified in |
|
|
Required. The name of the group to which the target OC4J instances belong. |
Use the following URI to target a specific OPMN-managed OC4J instance, including an instance within a cluster. In the prefix of the URI, oc4j replaces cluster.
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 follows:
deployer:oc4j:[rmis]:opmn://host[:opmnPort]/[iASInstanceName] /oc4jInstanceName
For example:
deployer:oc4j:opmn://server.company.com:6015/instance2/oc4j_2
Table 10-3 URI Parameters for Targeting a Specific Instance
| Parameter | Description |
|---|---|
|
|
Optional. Include if the target utilizes ORMI over SSL, or ORMIS. |
|
|
Required. The host name of the Oracle Application Server node to target within the cluster. |
|
|
Optional. The OPMN request port, as specified in |
|
|
Optional. The name of the Oracle Application Server instance to target, if it does not reside on the node specified for |
|
|
Required. The name of the target OC4J instance. |
Use one of the following URIs to target a standalone OC4J server instance.
If you are using RMI, the URI syntax is as follows:
deployer:oc4j:host:rmiPort
If you are using ORMI over SSL (ORMIS), the URI syntax is as follows:
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 |
|---|---|
|
|
Required if the target utilizes ORMI over SSL, or ORMIS. |
|
|
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. |
|
|
Required if RMI is used. The RMI port, as specified in the instance-specific |
|
|
Required if ORMIS is used. The SSL port, as specified in the instance-specific |
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_OPTS 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
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_OPTS environment variable.
You can set the value in the logging.properties file to one of the Java log-level values, which Table 10-5 describes.
Table 10-5 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
In OC4J (10.1.3.1.0), you can set the log levels for loggers through the Application Server Control Console, as follows:
On the OC4J Home page, click Administration.
From the administration tasks, select Logger Configuration to display the Logger Configuration page.
Click Expand All to view the entire list of loggers currently loaded for the OC4J instance.
Select a log level for any of the loggers shown on the page.
You invoke the deployment-related Ant tasks provided with OC4J through the build file (build.xml). Each task is specified in a <target> element in the build file , in a subelement formatted as <oracle:taskName. ... />. In the subelement, oracle is the namespace used to reference the OC4J Ant tasks.
The following sample build.xml file contains 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>
The following sections describe how to invoke the deploy task:
Use the deploy task to deploy a J2EE application packaged in an EAR file to an OC4J instance or to a group of instances within a cluster. 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}.ear"
deploymentName="${app.name}"
bindAllWebApps="default-web-site"
deploymentPlan="localPath/filename"
logfile="${log.dir}/deploy-ear.log"/>
Table 10-6 summarizes the properties that you can pass to the deploy task when you deploy an EAR file.
Table 10-6 deploy Properties for EAR Deployment
| Parameter | Description |
|---|---|
|
|
Required.The URI specifying the deployment target. |
|
|
Required.The administrator user name for the target OC4J instance or group of instances. |
|
|
Required.The administrator password for the target OC4J instance or group of instances. |
|
|
Required.The path and file name of the archive to deploy. |
|
|
Required.The user-defined application deployment name, used to identify the application within OC4J. |
|
|
Optional. Binds all Web modules to the specified Web site. Specify the |
|
|
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. |
|
|
Optional. The parent application of this application. The default is the global, or |
|
|
Optional. The directory to deploy the EAR to. If not specified, the EAR is deployed to the The deployed EAR file is also copied to this directory. Each successive deployment will cause this EAR file to be overwritten. |
|
|
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 |
|
|
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 The |
|
|
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 In addition, stubs for each individual EJB module are generated in an archive with the same name in the The |
|
|
Optional. The path and name for a log file generated for the deployment. |
Use the deploy task to deploy a standalone Web module packaged in a WAR file to an OC4J instance or to a group of instances within a cluster. For example:
<oracle:deploy
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
file="${lib.dir}/${app.name}.war"
deploymentName="${app.name}"
contextRoot="/myapp"
bindAllWebApps="default-web-site"
logfile="${log.dir}/deploy-war.log"/>
Table 10-7 summarizes the WAR-specific properties that you can pass to the deploy task when you deploy a WAR file.
Table 10-7 deploy Task Properties for Standalone WAR Deployment
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or group of instances. |
|
|
Required. The administrator password for the target OC4J instance or group of instances. |
|
|
Required. The path and file name of the archive to deploy. |
|
|
Required. The user-defined module deployment name, used to identify the module within OC4J. |
|
|
Required. Binds the Web module to the specified Web site. Specify the |
|
|
Required. 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
|
|
|
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. |
|
|
Optional. The parent application of this module. The default is the global, or |
|
|
Optional. The directory to deploy the archive to. If not specified, the archive is deployed to the The deployed archive file is also copied to this directory. Each successive deployment will cause this file to be overwritten. |
|
|
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 |
|
|
Optional. The path and name for a log file generated for the deployment. |
Use the deploy task to deploy a standalone resource adapter packaged in an archive to an OC4J instance or to a group of instances within a cluster. 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"/>
Table 10-8 summarizes the properties that you can pass to the deploy task when you deploy a RAR file.
Table 10-8 deploy Task Properties for Standalone RAR Deployment
| Parameter | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or group of instances. |
|
|
Required. The administrator password for the target OC4J instance or group of instances. |
|
|
Required. The path and file name of the archive to deploy. |
|
|
Required. The user-defined connector name, used to identify the connector within OC4J. |
|
|
Required if resource adapter needs runtime permissions. Include and set to |
|
|
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. |
|
|
Optional. The path to the directory containing native libraries (such as DLLs) within the RAR file. |
|
|
Optional. The path and name for a log file generated for the deployment. |
Every Web module deployed to OC4J must be bound to a Web site through which it will be accessed.
Typically, you will bind Web modules at the time an EAR file or WAR file is deployed using the bindAllWebApps property of the deploy task. However, if the bindAllWebApps property was not specified when the EAR or WAR was deployed, you can bind modules to a Web site after deployment, as the following topics describe:
Use the bindAllWebApps task to bind the Web modules within a previously deployed EAR to a specified Web site. For example:
<oracle:bindAllWebApps
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="${app.name}"
webSiteName="${oc4j.binding.module}"/>
Table 10-9 summarizes the properties that you can pass to the bindAllWebApps task.
Table 10-9 bindAllWebApps Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance. |
|
|
Required. The administrator password for the target OC4J instance. |
|
|
Required. The user-defined name of the application that the Web modules belong to, set when the application was deployed. |
|
|
Required. The name of the |
Use the bindWebApp task to bind a Web module to the specific Web site that will be used to access it. You can also specify the context URI for the module. For example:
<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}"/>
Table 10-10 summarizes the properties that you can pass to the bindWebApp task.
Table 10-10 bindWebApp Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance. |
|
|
Required. The administrator password for the target OC4J instance. |
|
|
Required. The user-defined name of the application the Web module belongs to, set when the application was deployed. |
|
|
Required. 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 |
|
|
Required. The name of the |
|
|
Required. The context URI for the Web module, such as |
Use the redeploy task to redeploy a previously deployed archive to an OC4J instance or to a group of instances within a cluster. The previous version of the archive will be undeployed as part of this process. For example:
<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-11 summarizes the properties that you can pass to the redeploy task.
Table 10-11 redeploy Task Properties
| Subswitch | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or group of instances. |
|
|
Required. The administrator password for the target OC4J instance or group of instances. |
|
|
Required. The path and file name of the archive to redeploy. |
|
|
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. |
|
|
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. |
|
|
Optional. Include to redeploy the archive to each OC4J instance in a group of instances within a cluster in sequence. The redeployment on each target must complete before it continues 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 OC4J instances in the group by default. This option is valid only in a clustered environment. It is not valid for standalone OC4J. |
|
|
Optional. The path and name for a log file generated for the deployment. |
Use the undeploy task to remove an application or module from an OC4J instance or from a group of instances within a cluster. The isConnector="true" property must be included if you are undeploying a standalone resource adapter (RAR). For example:
<oracle:undeploy
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="${app.name}"
logfile="${log.dir}/filename.log"/>
Table 10-12 summarizes the properties that you can pass to the undeploy task.
Table 10-12 undeploy Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or group of instances. |
|
|
Required. The administrator password for the target OC4J instance or group of instances. |
|
|
Required. The user-defined name of the application or module to undeploy. This is the name set when the archive was deployed. |
|
|
Required for a standalone RAR. Include and set to |
|
|
Optional. The path and name for a log file generated for the deployment. |
Use the updateEJBModule task to perform incremental or partial redeployment of EJB modules within an application running in an OC4J instance or in a group of instances within a cluster. This feature makes it possible to redeploy only those beans within an EJB JAR that have changed, without requiring redeployment of the entire module. For example:
<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"/>
|
Note: Incremental redeployment may be more efficient than redeploying the entire application for CMP or BMP entity beans but not for session beans, message-driven beans, or EJB 3.0 JPA entities. For details about whether to use this feature, see "Incremental Redeployment of Updated EJB Modules". |
Table 10-13 summarizes the properties that can be passed to the updateEJBModule task.
Table 10-13 updateEJBModuleTask Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or group of instances. |
|
|
Required. The administrator password for the target OC4J instance or group of instances. |
|
|
Required. The name of the application the EJB is part of. If you are updating a standalone EJB module, specify the |
|
|
Required. The name of the EJB JAR file to be updated as defined in |
|
|
Required. The path and file name of the updated EJB JAR. |
|
|
Optional. The path and name for a log file generated for the update. |
You can use Ant tasks to create and manage shared libraries in an OC4J instance or in a group of instances within a cluster, as the following topics describe:
Use the publishSharedLibrary task to install a shared library in an OC4J instance or in a group of instances within a cluster. Once installed, the shared library will be available for use by applications within each instance. For example:
<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>
The shared library binaries will be installed in the ORACLE_HOME/j2ee/instance/shared-lib directory within each OC4J instance. At the same time, a <shared-library> element declaring the shared library will be added to the server.xml file on each OC4J instance.
Include one element for each code source to upload or add. Do the same for each existing shared library to import.
To upload a new code source to each 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 file 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 each OC4J server. 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 or instances in an <oracle:sharedLibraryImport> element. You can specify the minimum or maximum version, or both, of the library to import.
The following example uploads two JAR files to each 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:publishSharedLibrary>
Table 10-14 summarizes the properties that can be passed to the publishSharedLibrary task.
Table 10-14 publishSharedLibraryTask Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or group of instances. |
|
|
Required. The administrator password for the target OC4J instance or group of instances. |
|
|
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, |
|
|
Required. The shared library version. This value should ideally reflect the code implementation version. |
|
|
Optional. The name of the parent shared library, if applicable. |
|
|
Optional. The parent shared library version, if applicable. |
|
|
Optional. The path and name for a log file generated for the update. |
Use the modifySharedLibrary task to make changes to an existing shared library installed in an OC4J instance or in a group of instances within a cluster. For example:
<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="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>
Include one element for each code source to upload, add, or remove. Do the same for each existing shared library to import or remove.
To upload a new code source to each 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 or servers, 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 or servers. 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 file name of the code source within the shared library to remove.
To import an existing shared library into the shared library, specify the shared library name as defined within the OC4J instance or instances in an <oracle:addImport> element. You can optionally specify the minimum or maximum version, or both, of the library to import.
To remove an imported shared library, use an <oracle:removeImport> element.
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="acme-apis.jar" />
<oracle:removeImport libraryName="foo" min-version="2.0"/>
</oracle:modifySharedLibrary>
Table 10-15 summarizes the properties that can be passed to the modifySharedLibrary task.
Table 10-15 modifySharedLibraryTask Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or group of instances. |
|
|
Required. The administrator password for the target OC4J instance or group of instances. |
|
|
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, |
|
|
Required. The shared library version. This value should ideally reflect the code implementation version. |
|
|
Optional. The path and name for a log file generated for the update. |
Use the removeSharedLibrary task to remove a shared library from an OC4J instance or from a group of instances within a cluster. For example:
<oracle:removeSharedLibrary
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
logfile="${log.dir}/filename.log"
libraryName="name"
version="version"/>
Table 10-16 summarizes the properties that can be passed to the removeSharedLibrary task.
Table 10-16 removeSharedLibrary Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or group. |
|
|
Required. The administrator password for the target OC4J instance. |
|
|
Required. The name of the shared library. |
|
|
Required. The version of the shared library. This value should ideally reflect the code implementation version. |
|
|
Optional. The path and name for a log file generated for the removal. |
Use the start or stop task to start, restart, or stop an application and its child applications as part of a deployment operation on a specific OC4J instance or group of OC4J instances across an entire cluster. For example:
<oracle:start|stop
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="${app.name}"/>
Table 10-17 summarizes the properties that can be passed to the start and stop tasks.
Table 10-17 start and stopTask Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or instances. |
|
|
Required. The administrator password for the target OC4J instance or instances. |
|
|
Required. The name of the application to start or stop. |
Use the restartServer or shutdownServer task to restart or stop a specific OC4J instance or a group of OC4J instances across an entire cluster. For example:
<oracle:restartServer|shutdownServer
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"/>
Table 10-18 summarizes the properties that can be passed to the restartServer and shutdownServer tasks.
Table 10-18 restartServer and shutdownServer Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The administrator user name for the target OC4J instance or instances. |
|
|
Required. The administrator password for the target OC4J instance or instances. |
You can use Ant tasks to manage data sources in an OC4J instance or in a group of instances within a cluster, as the following topics describe:
You can use Ant tasks to add, test, and remove data source connection pools in an OC4J instance or in a group of instances within a cluster, as the following topics describe:
Use the addDataSourceConnectionPool task to add a data source connection pool for an application in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:addDataSourceConnectionPool deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" name="ScottConnectionPool" factoryClass="oracle.jdbc.pool.OracleDataSource" dbUser="scott" dbPassword="tiger" url="jdbc:oracle:thin:@localhost:1521:xe"/>
Table 10-19 summarizes the properties that can be passed to the addDataSourceConnectionPool task.
Table 10-19 addDataSourceConnectionPool Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The location to use to bind the new data source connection pool into JNDI. |
|
|
Required. The fully qualified path of the connection factory implementation. |
|
|
Required. The default user name for the new data source connection pool. |
|
|
Required. The default password for the new data source connection pool. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application to deploy to. |
|
|
Optional. The login timeout for the new data source connection pool. |
|
|
Optional. The transaction level ( |
|
|
Optional. The database schema to use, |
|
|
Optional. Indicates whether or not OC4J should manage local transactions. The default value is |
Use the testDataSourceConnectionPool task to test an application's connection to a data source connection pool in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:testDataSourceConnectionPool deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" name="ScottConnectionPool" sqlStatement="select * from dual" />
Table 10-20 summarizes the properties that can be passed to the testDataSourceConnectionPool task.
Table 10-20 testDataSourceConnectionPool Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The name of the connection pool. |
|
|
Required. The SQL statement to use to test the connection |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application. |
|
|
Optional. The user name to use. |
|
|
Optional. The default password to use. |
Use the removeDataSourceConnectionPool task to remove a data source connection pool from an application in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:removeDataSourceConnectionPool deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" name="ScottConnectionPool"/>
Table 10-21 summarizes the properties that can be passed to the removeDataSourceConnectionPool task.
Table 10-21 removeDataSourceConnectionPool Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The name of the connection pool. |
|
|
Optional. The path and name for a log file generated for the removal. |
|
|
Optional. The name of the application from which to remove the data source connection pool. |
You can use Ant tasks to add, test, and remove data sources in an OC4J instance or in a group of instances within a cluster, as the following topics describe:
Use the addManagedDataSource task to add a managed data source for an application in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:addManagedDataSource deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" dataSourceName="ScottDataSource" jndiLocation="jdbc/ScottDataSource" connectionPoolName="ScottConnectionPool" />
Table 10-22 summarizes the properties that can be passed to the addManagedDataSource task.
Table 10-22 addManagedDataSource Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The name of the data source. |
|
|
Required. The location to use to bind the new data source into JNDI. |
|
|
Required. The name of the connection pool with which the data source interacts. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application for which to add the data source. |
|
|
Optional. The default user name for the new data source. |
|
|
Optional. The default password for the new data source. |
|
|
Optional. The login timeout for the new data source. |
|
|
Optional. The transaction level ( |
|
|
Optional. The database schema to use if the EJB CMP implementation being used is Orion CMP. (TopLink CMP is the default.) |
|
|
Optional. Indicates whether or not OC4J should manage local transactions. The default value is |
Use the removeManagedDataSource command to remove a managed data source from an application in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:removeManagedDataSource deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" dataSourceName="ScottDataSource"/>
Table 10-23 summarizes the properties that can be passed to the removeManagedDataSource task.
Table 10-23 removeManagedDataSource Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The name of the data source to remove. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application from which to remove the data source. |
Use the addNativeDataSource task to add a native data source for an application in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:addNativeDataSource deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" dataSourceName="ScottNativeDataSource" dbUser="scott" dbPassword="tiger" jndiLocation="jdbc/ScottNativeDataSource" loginTimeout="60" dataSourceClass="oracle.jdbc.pool.OracleDataSource" url="jdbc:oracle:thin:@localhost:1521:xe" > <oracle:nativeDataSourceProperty name="maxStatements" value="20"/> <oracle:nativeDataSourceProperty name="implicitCachingEnabled" value="30"/> </oracle:addNativeDataSource>
Table 10-24 summarizes the properties that can be passed to the addNativeDataSource task.
Table 10-24 addNativeDataSource Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The name of the new data source. |
|
|
Required. The location to use to bind the new data source into JNDI. |
|
|
Required. The default user for the new data source. |
|
|
Required. The default password for the new data source. |
|
|
Required. The fully qualified class of the new data source. |
|
|
Required. The url used by the new data source to connect to the database. |
|
<nativeDataSourceProperty> |
|
|
name |
Required. The name of a property for the new data source. |
|
value |
Required. The value of a property for the new data source. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application for which to add the data source. |
|
|
Optional. The login timeout for the new data source. |
Use the removeNativeDataSource task to remove a native data source from an application in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:removeNativeDataSource deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" dataSourceName="ScottNativeDataSource"/>
Table 10-25 summarizes the properties that can be passed to the removeNativeDataSource task.
Table 10-25 removeNativeDataSource Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The name of the data source to remove. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application from which to remove the data source. |
Use the testDatabaseConnection task to test an application's connection to a database in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:testDatabaseConnection deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" sqlStatement="select * from dual" factoryClass="oracle.jdbc.pool.OracleDataSource" dbUser="scott" dbPassword="tiger" url="jdbc:oracle:thin:@localhost:1521:xe"/>
Table 10-26 summarizes the properties that can be passed to the testDatabaseConnection task.
Table 10-26 testDatabaseConnection Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The SQL statement to use to test the connection. |
|
|
Required. The JDBC factory to test (instance of |
|
|
Required. The default user name for the database. |
|
|
Required. The default password for the database. |
|
|
Required. The URL to set on the JDBC factory. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application for which to test the database connection. |
Use the testDataSource task to test an application's connection to a data source in an OC4J instance or in each OC4J instance of a group within a cluster. For example:
<oracle:testDataSource deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" applicationName="default" dataSourceName="ScottDataSource" sqlStatement="select * from dual" />
Table 10-27 summarizes the properties that can be passed to the testDataSource task.
Table 10-27 testDataSource Task Properties
| Property | Task |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The data source to test. |
|
|
Required. The SQL statement to use to test the connection |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application for which to test the data source. |
|
|
Optional. The default user name for the data source. |
|
|
Optional. The default password for the data source. |
Use the getDataSourcesDescriptor task to retrieve an application's data sources descriptor. For example:
<oracle:getDataSourcesDescriptor deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" /> applicationName="default"
Table 10-28 summarizes the properties that can be passed to the getDataSourcesDescriptor task.
Table 10-28 getDataSourcesDescriptor Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The name of the application to which the descriptor belongs. |
You can use OC4J Ant tasks to manage data JMS resources in an OC4J instance or in a group of instances within a cluster, as the following topics describe:
You can use Ant tasks to manage the OC4J JMS connection factories, as the following topics describe:
Use the addJMSConnectionFactory task to add a JMS connection factory to an OC4J instance or to each instance of a group within a cluster. For example:
<oracle:addJMSConnectionFactory deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" domain="Queue" jndiLocation="jms/ExampleQueueCF" />
Table 10-29 summarizes the properties that can be passed to the addJMSConnectionFactory task.
Table 10-29 addJMSConnectionFactory Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The JMS domain of this connection factory ( |
|
|
Required. The JNDI location to which this connection factory will be bound. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The host name associated with this connection factory (defaults to the containing OC4J JMS server host). |
|
|
Optional. The port number associated with this connection factory (defaults to the containing OC4J JMS server port). |
|
|
Optional. The user name associated with this connection factory (defaults to |
|
|
Optional. The password associated with this connection factory (defaults to null). |
|
|
Optional. The JMS client ID associated with this connection factory (defaults to null). |
|
|
Optional. Whether or not this an XA connection factory (defaults to |
Use the removeJMSConnectionFactory task to remove a JMS connection factory from an OC4J instance or instances. For example:
<oracle:removeJMSConnectionFactory deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" jndiLocation="jms/ExampleQueueCF" />
Table 10-30 summarizes the properties that can be passed to the removeJMSConnectionFactory task.
Table 10-30 removeJMSConnectionFactory Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The JNDI location of the connection factory to remove. |
|
|
Optional. The path and name for a log file generated for the deployment. |
Use the getJMSConnectionFactories task to return the attributes for each of the JMS connection factories in an OC4J instance or in a group of OC4J instances within a cluster. For example:
<oracle:getJMSConnectionFactories deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" />
Table 10-31 summarizes the properties that can be passed to the getJMSConnectionFactories task.
Table 10-31 getJMSConnectionFactories Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Optional. The path and name for a log file generated for the deployment. |
You can use Ant tasks to manage the OC4J JMS destinations, as the following topics describe:
Use the addDestination task to add a JMS destination. For example:
<oracle:addDestination deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1"domain="Queue" name="ExampleQueue" jndiLocation="jms/ExampleQueue" />
Table 10-32 summarizes the properties that can be passed to the addDestination task.
Table 10-32 addDestination Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The JMS domain of this destination ( |
|
|
Required. The OC4J JMS provider-specific name of the destination. |
|
|
Required. The JNDI location to which this destination will be bound. |
|
|
Optional. The path and name for a log file generated for the deployment. |
|
|
Optional. The persistence file associated with this destination (defaults to null). |
|
description |
Optional. A textual description of this destination (defaults to null). |
Use the removeDestination task to remove a JMS destination from an OC4J instance or from each OC4J instance of a group within a cluster. For example:
<oracle:removeDestination deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" jndiLocation="jms/ExampleQueue" />
Table 10-33 summarizes the properties that can be passed to the removeDestination task.
Table 10-33 removeDestination Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Required. The OC4J JMS provider-specific name of the destination to remove. |
|
|
Optional. The path and name for a log file generated for the deployment. |
Use the getDestinations task to return the attributes for each of the OC4J JMS destinations in an OC4J instance or in a group of OC4J instances within a cluster. For example:
<oracle:getDestinations deployerUri="deployer:oc4j:localhost" userid="oc4jadmin" password="welcome1" />
Table 10-34 summarizes the properties that can be passed to the getDestinations task.
Table 10-34 getDestinations Task Properties
| Property | Description |
|---|---|
|
|
Required. The URI specifying the deployment target. |
|
|
Required. The default user name to use to get connections. |
|
|
Required. The default password to use to get connections. |
|
|
Optional. The path and name for a log file generated for the deployment. |
