| Oracle® Containers for J2EE Deployment Guide 10g (10.1.3.5.0) Part Number E13980-01 |
|
|
View PDF |
| Oracle® Containers for J2EE Deployment Guide 10g (10.1.3.5.0) Part Number E13980-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. 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 OC4J instances:
Adding Web sites
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
Bind and Unbind Web modules to a Web site and List details about Web bindings
Create, modify, or remove shared libraries for an application
Start, restart, or stop applications and list status and details for applications
Restart or stop an OC4J instance or group of instances
Add, test, list, and remove data sources and data source connection pools
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
| Ant Task Name | Description |
|---|---|
|
addDataSourceConnectionPool |
|
|
addDestination |
|
|
addWebSite |
|
|
addImportSharedLibrary |
|
|
addJMSConnectionFactory |
|
|
addManagedDataSource |
|
|
addNativeDataSource |
|
|
addRemoveInheritedSharedLibrary |
|
|
bindWebApp |
"Binding a Specific Web Module to a Web Site and Setting the Context Root" |
|
bindAllWebApps |
|
|
compileJsp |
"Using an Ant Task to Precompile a JSP" in the Oracle Containers for J2EE Support for JavaServer Pages Developer's Guide |
|
deleteImportSharedLibrary |
|
|
deleteRemoveInheritedSharedLibrary |
|
|
deploy |
"Deploying a J2EE Application (EAR)" |
|
getDataSourcesDescriptor |
|
|
getDestinations |
|
|
getJMSConnectionFactories |
|
|
listApplications |
|
|
listDataSourceConnectionPools |
|
|
listDataSources |
|
|
listWebBindings |
|
|
modifySharedLibrary |
|
|
publishSharedLibrary |
|
|
redeploy |
|
|
removeDataSourceConnectionPool |
|
|
removeDestination |
|
|
removeJMSConnectionFactory |
|
|
removeManagedDataSource |
|
|
removeNativeDataSource |
|
|
removeSharedLibrary |
|
|
restartApp |
|
|
restartServer |
|
|
shutdownServer |
|
|
start |
|
|
stop |
|
|
testDatabaseConnection |
|
|
testDataSource |
|
|
testDataSourceConnectionPool |
|
|
unbindAllWebApps |
|
|
unbindWebApp |
|
|
undeploy |
|
|
updateEJBModule |
You can perform similar deployment tasks with Application Server Control or the admin_client.jar command-line utility. Chapter 9, "Using Application Server Control for Deployment" describes how to use the Application Server Control 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 ant-oracle.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 ant-oracle.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 Administrative Client Utility enables you to use OC4J Ant tasks for configuration and deployment.
To incorporate OC4J Ant tasks using Ant 1.6.5 with the Administrative Client Utility:
Download the oc4j_admin_client_101350.zip file from the Oracle Technology Network at
http://www.oracle.com/technology/software/products/ias/htdocs/utilsoft.html
For information about the Administrative Client Utility and how to use it, see "Downloading and Extracting the Remote Administration Client".
Extract the contents of oc4j_admin_client_101350.zip into a local directory of your choice, such as oc4j_admin_client.
Copy the ORACLE_HOME/ant/lib/ant-oracle.jar file from an Oracle Application Server 10g (10.1.3.5.0) home directory to OC4J_ADMIN_CLIENT_DIR\ant\lib, in the local directory to which you extracted the contents of oc4j_admin_client_101350.zip.
Set the ORACLE_HOME environment variable to the OC4J_ADMIN_CLIENT_DIR directory.
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 Java 2 Standard Edition SDK.
The common ANT installation directory is ORACLE_HOME/ant.
Declare the oracle namespace in the <project> element of the Ant build file (build.xml)., as follows:
<project name="test" default="all" basedir="." xmlns:oracle="antlib:oracle">
References to the OC4J Ant tasks in build.xml will use this namespace.
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 this 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 attribute passed to an Ant task is deployerUri, which specifies the OC4J target for the task. The syntax for the URI varies depending on the target.
For the format of this URI, see the following topics:
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 for the standalone OC4J server. |
|
|
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 might 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 10g (10.1.3.5.0), you can set the log levels for loggers with Application Server Control, 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>
You can use the addWebSite task to add a Web site on a standalone OC4J instance or on an OC4J instance within a cluster. The new Web site will include the default Web application from the default Web site. See Chapter 13, "Managing Web Sites in OC4J," in the Oracle Containers for J2EE Configuration and Administration Guide for detailed information about OC4J Web sites and how to manually add Web sites.
Note:
TheaddWebSite task cannot be used to create a Web site on multiple OC4J instances within a group.The following example adds a secure HTTP Web site to the OC4J home instance in a clustered environment:
<oracle:addWebSite
deployerUri="deployer:oc4j:opmn://localhost:6003/home"
userId="oc4jadmin"
password="welcome"
webSiteName="test-web-site"
protocol="https" port="9443"
keystorePath="/tmp/testkeystore.jks"
keystorePassword="welcome"
logfile="${log.dir}/my.log" />
Table 10-6 addWebSite Task Attributes
| Parameter | 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 name for the Web site. The name must use the form |
|
|
Required. The protocol to be used by the Web site. The protocol can be |
|
|
Required. The port number to be used by the Web site. Two Web sites can share the same port number only if they both use the |
|
|
Optional. The filename, including the path, of the keystore file. This parameter is required when using |
|
|
Optional. The password of the keystore file. This parameter is required when using |
|
|
Optional. The third-party |
|
|
Optional. The log file to use for output. |
The following sections describe how to invoke the deploy task:
Use the deploy task to deploy a J2EE application that is packaged as an EAR file, or a J2EE application that is in the standard enterprise application directory structure, to an OC4J instance or to a group of OC4J instances. A J2EE application's modules can be packaged or left in their directory structure as well. The following example shows the attributes 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-7 summarizes the attributes that you can set for the deploy task when you deploy an EAR file.
Table 10-7 deploy task Attributes for EAR Deployment
| Attribute | 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 file path of the archive or application directory to be deployed. The application directory must be assembled in a standard J2EE application directory structure when using directory-based deployment. |
|
|
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. Specify 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 file name 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. Specify to deploy the archive to each OC4J instance in a group in sequence. The deployment to each target OC4J instance must complete before deployment begins on the next target instance. Requests will not be routed to an OC4J instance while the EAR is being deployed to it. You can use the If this attribute is not specified, the archive will be simultaneously deployed to all OC4J instances in the target group by default. This attribute is valid only in an Oracle Application Server environment. It is not valid for standalone OC4J. |
|
|
Optional. Specifies a number of seconds between sequential deployments to different OC4J instances that are running an application cluster. |
|
|
Optional. The path and file name for a log to be 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 OC4J instances.
Note:
Thedeploy task does not support directory-based deployment for standalone Web modules. The Web module must be packaged as a WAR file. However, directory-based deployment of a Web module is supported if the Web module directory is included within a J2EE application directory structure with a respective META-INF/application.xml file. In this case, deploy the application instead of the Web module.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-8 summarizes the WAR-specific attributes that you can set for the deploy task when you deploy a WAR file.
Table 10-8 deploy Task Attributes for Standalone WAR Deployment
| Attribute | 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's context root, which will be appended to the URL used to access the application through a Web browser. For example, if you supply
|
|
|
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 EJB module packaged as a JAR file. For example:
<oracle:deploy
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
file="${lib.dir}/${app.name}.jar"
deploymentName="${app.name}"
logfile="${log.dir}/deploy-jar.log"/>
Table 10-9 summarizes the attributes that you can set for the deploy task when you deploy an EJB JAR file.
Table 10-9 deployTask Attributes for Standalone EJB JAR Deployment
| Attribute | Description |
|---|---|
|
|
Required. The path and file name of the archive to deploy. |
|
|
Required. The user-defined name for the EJB module, used to identify it within OC4J. |
|
|
Optional. The directory to deploy the EJB JAR to. If a directory is not specified, the EJB JAR is deployed to the The deployed EJB JAR file is also copied to this directory. Each successive deployment will cause this EJB JAR file to be overwritten. |
|
|
Optional. The parent application the EJB module will be deployed to. The default is the |
|
|
Optional. The directory containing the OC4J-specific deployment descriptors. The default directory is |
|
|
Optional. Delete the JAR file from the server's file system after deployment. |
Use the deploy task to deploy a standalone resource adapter packaged in an archive to an OC4J instance or to a group of OC4J instances. The following example shows the attributes 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-10 summarizes the attributes that you can set for the deploy task when you deploy a RAR file.
Table 10-10 deploy Task Attributes for Standalone RAR Deployment
| Attribute | 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. |
You can use Ant tasks to: bind Web modules to a Web site; unbind Web modules from a Web site; and list the current Web module bindings for a Web site. The tasks can be run for a specific OC4J instance or for a group of OC4J instances in a cluster.
This section covers the following topics:
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 attribute of the deploy task. However, if the bindAllWebApps attribute 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}"
shared="false"
loadOnStartup="true"
accessLog="true" />
Table 10-11 summarizes the attributes that you can set for the bindAllWebApps task.
Table 10-11 bindAllWebApps Task Attributes
| Attribute | 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. |
|
|
Optional. The Web site name to which the Web module tries to bind. The name is the same as the Web site XML configuration file name. For example, Web modules are bound to the default Web site ( |
|
|
Optional. The application is allowed to be shared between HTTP/HTTPS. The default value is |
|
|
Optional. The application is allowed to be loaded on startup. The default value is |
|
|
Optional. The application is allowed to enable access logging. The default value is |
Use the bindWebApp task to bind a specific Web module within a J2EE application to a Web site you specify or to the default Web site. You can also specify the context root that will be used to access the Web 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}"
shared="false"
loadOnStartup="true"
accessLog="true" />
Table 10-12 summarizes the attributes that you can set for the bindWebApp task.
Table 10-12 bindWebApp Task Attributes
| Attribute | 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 |
|
|
Optional. The Web site name to which the Web module tries to bind. The name is the same as the Web site XML configuration file name. For example, Web modules are bound to the default Web site ( |
|
|
Required. The context root for the Web module, such as |
|
|
Optional. The application is allowed to be shared between HTTP/HTTPS. The default value is |
|
|
Optional. The application is allowed to be loaded on startup. The default value is |
|
|
Optional. The application is allowed to enable access logging. The default value is |
Web Modules can be unbound from a Web site after deployment. You can unbind all Web Modules from a Web site or you can unbind a specific Web module from a Web site.
Use the unbindAllWebApps task to remove all Web module bindings from a specific Web site in an OC4J instance or in a group of OC4J instances that are part of a cluster. For example:
<oracle:unbindAllWebApps
deployerUri="${connection_url}"
userId="{username}"
password="${password}"
deploymentName="${appname}"
webSiteName="default-web-site"
logFile="${log.dir}/my.log"
/>
Table 10-15 summarizes the attributes that you can set for the unbindAllWebApps task.
Table 10-13 unbindAllWebApps Task Attributes
| Parameter | 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 modules belong to, set when the application was deployed. |
|
|
Optional. The Web site name from which the Web modules try to unbind. The name is the same as the Web site XML configuration file name. For example, Web modules are unbound from the default Web site ( |
|
|
Optional. The log file to use for output. |
Use the unbindWebApp task to remove a specific Web module binding from a Web site in an OC4J instance or in a group of OC4J instances that are part of a cluster For example:
<oracle:unbindWebApp
deployerUri="${connection_url}"
userId="{username}"
password="${password}"
deploymentName="hello"
webModuleName="hello-web"
webSiteName="default-web-site"
logFile="${log.dir}/my.log"
/>
Table 10-14 summarizes the attributes that you can set for the unbindWebApp task.
Table 10-14 unbindWebApp Task Attributes
| Parameter | 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 modules belong to, set when the application was deployed. |
|
|
Required. The name of the Web module to be unbound. This should be the name of the WAR file contained within the EAR file, without the |
|
|
Optional. The Web site name from which the Web modules try to unbind. The name is the same as the Web site XML configuration file name. For example, The Web module is unbound from the default Web site ( |
|
|
Optional. The log file to use for output. |
Use the listWebBindings task to display the Web site bindings for each Web module in an OC4J instance or in a group of OC4J instances that are part of a cluster. The following information is listed by default: application name, module name, context root, and Web site name. For more detailed information, use the verbose attribute, which is described below. For example:
<oracle:listWebBindings
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
webSiteName="${oc4j.binding.module}"
verbose="true"
logfile="${log.dir}/my.log"
/>
Table 10-15 summarizes the attributes that you can set for the listWebBindings task.
Table 10-15 listWebBindings Task Attributes
| Parameter | 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. |
|
|
Optional. The Web site name for which to view all Web bindings. The name is the same as the Web site XML configuration file name. For example, All Web bindings for all Web sites are displayed if no Web site is specified. |
|
|
Optional. Displays more details. The additional details include: pre-load, shared, access log, and maximum inactivity time. |
|
|
Optional. The log file to use for output. |
Use the redeploy task to redeploy a previously deployed archive to an OC4J instance or to a group of OC4J instances. The isConnector="true" attribute must be included if you are redeploying a standalone resource adapter (RAR). 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-16 summarizes the attributes that you can set for the redeploy task.
Table 10-16 redeploy Task Attributes
| Attribute | 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 match the name of the existing application on the server. |
|
|
Required for a standalone RAR. Include and set to |
|
|
Optional. If this attribute is specified, 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 this attribute is not specified, values will be set to those in the deployment descriptors packaged with the archive. |
|
|
Optional. Specify to redeploy the archive to each OC4J instance in a group of OC4J instances in sequence. The redeployment to each target OC4J instance must complete before redeployment begins on to the next target instance. Requests will not be routed to an OC4J instance while the archive is being redeployed to it. You can use the If this attribute is not included, the archive will be 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. Specifies a number of seconds between sequential redeployments to different OC4J instances that are running an application cluster. |
|
|
Optional. Enable recovery from a failed redeployment. The previous archive is redeployed if possible. |
|
|
Optional. The path and name for a log file generated for the deployment. |
When an application is redeployed to a group with the sequential attribute of the redeploy Ant task, the redeployment operation is serialized, with redeployment done to one OC4J instance at a time so that the application being deployed is never entirely in a stopped state. In a sequential redeployment, the deployment manager immediately commences redeployment on the next OC4J instance that is running a member of an application cluster as soon as the redeployment operation completes on the current instance. The result is that the system might not be able to stabilize itself so that the new application instance is fully active before the next redeployment commences, which introduces these possible side effects:
The application can become inaccessible while it is stopped on one OC4J instance and before mod_oc4j is notified that the application is available on another instance.
Session replication activities might not have had an opportunity to execute.
In some circumstances, the session state of an application might be lost when you redeploy an application to a cluster with the redeploy task, even if you specify the sequential and keepsettings attributes.
In OC4J 10g (10.1.3.5.0), you can use the sequentialDelay attribute of the redeploy task to specify a number of seconds between redeployments to different OC4J instances that are running an application cluster. This delay can provide enough time for replication of session state.
If you specify the optional sequentialDelay attribute, the deployment manager waits the specified number of seconds between redeployment operations on OC4J instances within a group. This delay enables the system to stabilize as redeployment operations occur across the group, reducing the opportunities for applications to be inaccessible or session state to be lost.
An example of the redeploy Ant task with the sequentialDelay attribute 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"
sequentialDelay="15"
logfile="${log.dir}/deploy-ear.log"/>
The sequentialDelay option also applies to the deploy Ant task.
If you redeploy an application that has scheduled jobs, the jobs will not run as scheduled unless you remove all the jobs before the redeployment and resubmit them after it.
To redeploy an application with scheduled jobs:
Remove all scheduled jobs.
Redeploy the application.
Resubmit all the jobs.
Use the undeploy task to remove an application or module from an OC4J instance or from a group of OC4J instances. The isConnector="true" attribute 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-17 summarizes the attributes that you can set for the undeploy task.
Table 10-17 undeploy Task Attributes
| Attribute | 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 OC4J instances. 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-18 summarizes the attributes that you can set for the updateEJBModule task.
Table 10-18 updateEJBModule Task Attributes
| Attribute | 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 that the EJB module 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 OC4J instances, as the following topics describe:
Use the publishSharedLibrary task to install a shared library in an OC4J instance or in a group of OC4J instances. 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-19 summarizes the attributes that you can set for the publishSharedLibrary task.
Table 10-19 publishSharedLibrary Task Attributes
| Attribute | 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 OC4J instances. 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 file 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-20 summarizes the attributes that you can set for the modifySharedLibrary task.
Table 10-20 modifySharedLibrary Task Attributes
| Attribute | 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 modify. |
|
|
Required. The version of the shared library. |
|
|
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 OC4J instances. For example:
<oracle:removeSharedLibrary
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
logfile="${log.dir}/filename.log"
libraryName="name"
libraryVersion="version"/>
Table 10-21 summarizes the attributes that you can set for the removeSharedLibrary task.
Table 10-21 removeSharedLibrary Task Attributes
| Attribute | 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. |
|
|
Optional. The path and name for a log file generated for the removal. |
Use the addImportSharedLibrary task to import an existing shared library to an application's classloader. The task is equivalent to adding an <import-shared-library> element to an application's orion-application.xml descriptor. This task requires an application restart for the change to take effect. Refer to "Installing a Shared Library" for instructions on installing a shared library. For example:
<oracle:addImportSharedLibrary
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
logfile="${log.dir}/filename.log"
appName="Myapp"
name="oracle.jdbc"
MinVersion="1.0"/>
Table 10-22 summarizes the attributes that you can set for the addImportSharedLibrary task.
Table 10-22 addImportSharedLibrary Task Attributes
| Parameter | 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, as defined at deployment time, to which the shared library is imported. |
|
|
Required. The name of an existing shared library to add to the given application. |
|
|
Optional. The minimum version number of the library required by an application. |
|
|
Optional. The maximum version number of the library required by an application. |
|
|
Optional. The log file to use for output. |
Use the deleteImportSharedLibrary task to delete a shared library from an application's classloader. The task is equivalent to deleting an <import-shared-library> element from an application's orion-application.xml descriptor. This task requires an application restart for the change to take effect. The syntax follows:
<oracle:deleteImportSharedLibrary
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
logfile="${log.dir}/filename.log"
appName="Myapp"
name="oracle.jdbc"/>
Table 10-23 summarizes the attributes that you can set for the addImportSharedLibrary task.
Table 10-23 deleteImportSharedLibrary Task Attributes
| Parameter | 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, as defined at deployment time, from which the shared library is deleted. |
|
|
Required. The name of the shared library to remove from the given application. |
|
|
Optional. The log file to use for output. |
Use the addRemoveInheritedSharedLibrary task to stop a shared library from being inherited by an application's classloader. The task is equivalent to adding a <remove-inherited> element to an application's orion-application.xml descriptor. This task requires an application restart for the change to take effect. The syntax follows:
<oracle:addRemoveInheritedSharedLibrary
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
logfile="${log.dir}/filename.log"
appName="Myapp"
name="oracle.jdbc"/>
Table 10-24 summarizes the attributes that you can set for the addRemoveInheritedSharedLibrary task.
Table 10-24 addRemoveInheritedSharedLibrary Task Attributes
| Parameter | 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, as defined at deployment time, that will not inherit the shared library. |
|
|
Required. The name of the shared library to stop from being inherited. |
|
|
Optional. The log file to use for output. |
Use the deleteRemoveInheritedSharedLibrary task to allow a shared library to be inherited by an application's classloader. The task is equivalent to deleting a <remove-inherited> element from an application's orion-application.xml descriptor. This task requires an application restart for the change to take effect. The syntax follows:
<oracle:deleteRemoveInheritedSharedLibrary
deployerUri="${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
logfile="${log.dir}/filename.log"
appName="Myapp"
name="oracle.jdbc"/>
Table 10-25 summarizes the attributes that you can set for the deleteRemoveInheritedSharedLibrary task.
Table 10-25 deleteRemoveInheritedSharedLibrary Task Attributes
| Parameter | 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, as defined at deployment time, that will inherit the shared library. |
|
|
Required. The name of the shared library to be inherited. |
|
|
Optional. The log file to use for output. |
You can use Ant tasks to start, restart, or stop an application and its child applications in a specific OC4J instance or in a group of OC4J instances. You can also list the status of deployed applications in a specific OC4J instance or in a group of OC4J instances. The following topics are included in this section:
Use the start task to start an application and its child applications on target OC4J instances. Applications are automatically redeployed at startup if a file within the application has been modified.
The following example starts the ascontrol application on node2 within a cluster:
<oracle:start
deployerUri="deployer:oc4j:opmn://node2.company.com:6004/home"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="ascontrol"/>
Table 10-26 summarizes the attributes that you can set for the start task.
Table 10-26 -start Task Attributes
| Parameter | 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. |
Use the stop task to stop an application and its child applications on target OC4J instances. By default, applications are stopped immediately. Any requests that are currently being processed are lost. For planned shutdown scenarios, an application can have a specified amount of time to complete request processing before the application is stopped.
The following example stops the ascontrol application on node2 within a cluster. The application is allowed 5 seconds to complete requests before the application is forcefully stopped.
<oracle:stop
deployerUri="deployer:oc4j:opmn://node2.company.com:6004/home"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="ascontrol"
timeout="5"/>
Table 10-27 summarizes the attributes that you can set for the stop task.
Table 10-27 -stop Task Attributes
| Parameter | 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 stop. |
|
|
Optional. The amount of time to wait for the application to stop gracefully. The application is stopped forcefully after the timeout is reached. The default timeout is |
|
|
Optional. The graceful attribute specifies the method used to stop the application. The value The |
Use the restartApp task to stop and then start an application and its child applications on target OC4J instances. Applications are automatically redeployed at startup if a file within the application has been modified. By default, applications are stopped immediately. Any requests that are currently being processed are lost. For planned shutdown scenarios, an application can have a specified amount of time to complete request processing before the application is stopped.
The following example restarts the ascontrol application on node2 within a cluster. The application is allowed 5 seconds to complete requests before the application is forcefully stopped and then started.
<oracle:restartApp
deployerUri="deployer:oc4j:opmn://node2.company.com:6004/home"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
deploymentName="ascontrol"
timeout="5"/>
Table 10-28 summarizes the attributes that you can set for the restartApp task.
Table 10-28 -restartApp Task Attributes
| Parameter | 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 restart. |
|
|
Optional. The amount of time to wait for the application to stop gracefully. The application is stopped forcefully after the timeout is reached. The default timeout is |
|
|
Optional. The graceful attribute specifies the method used to stop the application. The value The |
Use the listApplications task to display the status of applications that are currently deployed in an OC4J instance or in a group of OC4J instances that are part of a cluster. The following status information is listed by default: application name, contained modules, application type, application state, and parent application. For more detailed information, use the verbose argument, which is described below. For example:
<oracle:listApplications
deployerUri="${deployer.uri}"
userId="${oc4j.admin.user}"
password="${oc4j.admin.password}"
verbose="true"
logfile="${log.dir}/my.log" />
Table 10-29 summarizes the attributes that you can set for the listApplications task.
Table 10-29 listApplications Task Attributes
| Parameter | 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. |
|
|
Optional. Displays more details. The additional details include: application context root binding, routing enabled, group name, and state replication. |
|
|
Optional. The log file to use for output. |
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-30 summarizes the attributes that you can set for the restartServer and shutdownServer tasks.
Table 10-30 restartServer and shutdownServer Task Attributes
| Attribute | 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 OC4J instances, as the following topics describe:
You can use Ant tasks to add, test, list, and remove data source connection pools in an OC4J instance or in a group of OC4J instances, 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-31 summarizes the attributes that you can set for the addDataSourceConnectionPool task.
Table 10-31 addDataSourceConnectionPool Task Attributes
| Attribute | 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" connectionPoolName="ScottConnectionPool" sqlStatement="select * from dual" />
Table 10-32 summarizes the attributes that you can set for the testDataSourceConnectionPool task.
Table 10-32 testDataSourceConnectionPool Task Attributes
| Attribute | 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 listDataSourceConnectionPools task to view a list of data source connection pools that are configured for an application. The list includes each connection pool's configured properties. For example:
<oracle:listDataSourceConnectionPool
deployerUri=${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
applicationName="default"
logfile="${log.dir}/my.log" />
Table 10-33 summarizes the attributes that you can set for the listDataSourceConnectionPool task.
Table 10-33 listDataSourceConnectionPools Task Attributes
| Parameters | 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 name of the application for which to list configured data source connection pools. The |
|
|
Optional. The log file to use for output. |
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-34 summarizes the attributes that you can set for the removeDataSourceConnectionPool task.
Table 10-34 removeDataSourceConnectionPool Task Attributes
| Attribute | 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, list, and remove data sources in an OC4J instance or in a group of OC4J instances, 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-35 summarizes the attributes that you can set for the addManagedDataSource task.
Table 10-35 addManagedDataSource Task Attributes
| Attribute | 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 task 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-36 summarizes the attributes that you can set for the removeManagedDataSource task.
Table 10-36 removeManagedDataSource Task Attributes
| Attribute | 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-37 summarizes the attributes that you can set for the addNativeDataSource task.
Table 10-37 addNativeDataSource Task Attributes
| Attribute | 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-38 summarizes the attributes that you can set for the removeNativeDataSource task.
Table 10-38 removeNativeDataSource Task Attributes
| Attribute | 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-39 summarizes the attributes that you can set for the testDatabaseConnection task.
Table 10-39 testDatabaseConnection Task Attributes
| Attribute | 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-40 summarizes the attributes that you can set for the testDataSource task.
Table 10-40 testDataSource Task Attributes
| Attribute | 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 listDataSources task to view a list of data sources that are configured for an application. The list includes each data source's configured properties. For example:
<oracle:listDataSources
deployerUri=${deployer.uri}"
userid="${oc4j.admin.user}"
password="${oc4j.admin.password}"
applicationName="default"
logfile="${log.dir}/my.log" />
Table 10-41 summarizes the attributes that you can set for the listDataSource task.
Table 10-41 listDataSources Task Attributes
| Parameter | 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 name of the application for which to list configured data sources. The |
|
|
Optional. The log file to use for output. |
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-42 summarizes the attributes that you can set for the getDataSourcesDescriptor task.
Table 10-42 getDataSourcesDescriptor Task Attributes
| Attribute | 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 OC4J instances, 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-43 summarizes the attributes that you can set for the addJMSConnectionFactory task.
Table 10-43 addJMSConnectionFactory Task Attributes
| Attribute | 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-44 summarizes the attributes that you can set for the removeJMSConnectionFactory task.
Table 10-44 removeJMSConnectionFactory Task Attributes
| Attribute | 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-45 summarizes the attributes that you can set for the getJMSConnectionFactories task.
Table 10-45 getJMSConnectionFactories Task Attributes
| Attribute | 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-46 summarizes the attributes that you can set for the addDestination task.
Table 10-46 addDestination Task Attributes
| Attribute | 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-47 summarizes the attributes that you can set for the removeDestination task.
Table 10-47 removeDestination Task Attributes
| Attribute | 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-48 summarizes the attributes that you can set for the getDestinations task.
Table 10-48 getDestinations Task Attributes
| Attribute | 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. |
|
 Copyright © 2006, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|