wldeploy Ant Task Reference

wldeploy Ant Task Reference

Overview
Basic Steps for Using wldeploy
Sample build.xml Files for wldeploy
wldeploy Ant Task Attribute Reference

Overview

The wldeploy Ant task enables you to perform weblogic.Deployer functions using attributes specified in an Ant XML file. You can use wldeploy along with other WebLogic Server Ant tasks to create a single Ant build script that:

Builds your application from source, using wlcompile, appc, and the Web Services Ant tasks.
Creates, starts, and configures a new WebLogic Server domain, using the wlserver and wlconfig Ant tasks.
Deploys a compiled application to the newly-created domain, using the wldeploy Ant task.

See also:

Using Ant Tasks to Configure and Use a WebLogic Server Domain
Building Applications in a Split Development Directory

Basic Steps for Using wldeploy

To use the wldeploy Ant task:

Set your environment.
WL_HOME/server/bin/setWLSEnv.sh

In the staging directory, create the Ant build file ( build.xml).
To use an Ant installation that is different from the one installed with WebLogic Server, start by defining the wldeploy Ant task definition:
<taskdef name="wldeploy" classname="weblogic.ant.taskdefs.management.WLDeploy"/>

If necessary, add task definitions and calls to the wlserver and wlconfig tasks in the build script to create and start a new WebLogic Server domain.
Add a call to wldeploy to deploy your application to one or more WebLogic Server instances or clusters.
See:

Sample build.xml Files for wldeploy
wldeploy Ant Task Attribute Reference

Execute the Ant task or tasks specified in the build.xml file...
prompt> cd staging_directory
prompt> ant

Sample build.xml Files for wldeploy

Deploy an application to a single WebLogic Server instance:
  <target name="deploy">

    <wldeploy action="deploy" 
              verbose="true" 
              debug="true"
              name="DeployExample" 
              source="output/redeployEAR"
              user="weblogic" 
              password="weblogic"
              adminurl="t3://localhost:7001" 
              targets="myserver" />

  </target>
Undeploy the application. You do not specify the source archive file or exploded directory, but rather, just the deployed name...
  <target name="undeploy">

    <wldeploy action="undeploy" 
              verbose="true" 
              debug="true"
              name="DeployExample"
              user="weblogic" 
              password="weblogic"
              adminurl="t3://localhost:7001" 
              targets="myserver"
              failonerror="false" />

  </target>
Perform a partial redeploy of the application; in this case, just a single WAR file in the application is redeployed:
  <target name="redeploy_partial">

    <wldeploy action="redeploy" 
              verbose="true"
              name="DeployExample"
              user="weblogic" 
              password="weblogic"
              adminurl="t3://localhost:7001" 
              targets="myserver"
              deltaFiles="examples/general/redeploy/SimpleImpl.war" />

  </target>
Use the nested <files> child element of wldeploy to specify a particular file in the application that should be undeployed:
  <target name="undeploy_partial">

    <wldeploy action="undeploy" 
              verbose="true" 
              debug="true"
              name="DeployExample"
              user="weblogic" 
              password="weblogic"
              adminurl="t3://localhost:7001" 
              targets="myserver"
              failonerror="false">

      <files dir="${current-dir}/output/redeployEAR/examples/general/redeploy"
             includes="SimpleImpl.jsp" />

    </wldeploy>

  </target>
Deploy a Java EE library called myLibrary whose source files are located in the output/myLibrary directory:
  <target name="deploy">

    <wldeploy action="deploy" 
              name="myLibrary"
              source="output/myLibrary" 
              library="true"
              user="weblogic" 
              password="weblogic"
              verbose="true" 
              adminurl="t3://localhost:7001"
      targets="myserver" />

  </target>
Main attributes wldeploy Ant task

These attributes mirror some of the arguments of the weblogic.Deployer command.
Typically administrators use the weblogic.Deployer command, and not the wldeploy Ant task, to deploy applications in a production environment.

Attribute Description Data Type
action The deployment action to perform.
Valid values are deploy, cancel, undeploy, redeploy, distribute, start, and stop.
String
adminmode The deployment action puts the application into Administration mode.
Administration mode restricts access to an application to a configured Administration channel.
Valid values for this attribute are true and false. Default value is false, which means that by default the application is deployed in production mode so that all clients can access it immediately.
Boolean
adminurl The URL of the Administration Server.
The format of the value of this attribute is protocol://host:port, where protocol is either http or t3, host is the host on which the Administration Server is running, and port is the port which the Administration Server is listening.

In order to use the HTTP protocol, enable the http tunnelling option in the Administration Console.
String
allversions The action (redeploy, stop, and so on) applies to all versions of the application.
Valid values for this attribute are true and false. The default value is false.
Boolean
altappdd Name of an alternate Java EE deployment descriptor (application.xml) to use for deployment.
If you do not specify this attribute, and you are deploying an Enterprise application, the default deployment descriptor is called application.xml and is located in the META-INF subdirectory of the main application directory or archive (specified by the source attribute.)
String
altwlsappdd Name of an alternate WebLogic Server deployment descriptor (weblogic-application.xml) to use for deployment.
If you do not specify this attribute, and you are deploying an Enterprise application, the default deployment descriptor is called weblogic-application.xml and is located in the META-INF subdirectory of the main application directory or archive (specified by the source attribute.)
String
appversion The version identifier of the deployed application. String
debug Enable wldeploy debugging messages. Boolean
deleteFiles Whether to remove static files from a server's staging directory.
This attribute is valid only for unarchived deployments, and only for applications deployed using stage mode. You must specify target servers when using this attribute.
Specifying the deleteFiles attributes indicates that WebLogic Server should remove only thos files that it copied to the staging area during deployment.
This attribute can be used only in combination with action="redeploy".
Because the deleteFiles attribute deletes all specified files, Oracle recommends that you use caution when using the deleteFiles attribute and that you do not use it in production environments.
Valid values for this attribute are true and false. Default value is false.
Boolean
deltaFiles Comma- or space-separated list of files, relative to the root directory of the application, which are to be redeployed.
Use this attribute only in conjunction with action="redeploy" to perform a partial redeploy of an application.
String
enableSecurityValidation Whether or not to enable validation of security data.
Valid values for this attribute are true and false. Default value is false.
Boolean
externalStage Whether the deployment uses external_stage deployment mode.
In this mode, the Ant task does not copy the deployment files to target servers; instead, ensure that deployment files have been copied to the correct subdirectory in the target servers' staging directories.
You can specify only one of the following attributes:

stage
nostage
external_stage

If none is specified, the default deployment mode to Managed Servers is stage
The default mode to the Administration Server and in single-server cases is nostage.
Boolean
failonerror This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build.
Valid values for this attribute are true and false. Default value is true.
Boolean
graceful Stops the application after existing HTTP clients have completed their work.
You can use this attribute only when stopping or undeploying an application, or in other words, also specify either the action="stop" or action="undeploy" attributes.
Valid values for this attribute are true and false. Default value is false.
Boolean
id Identification used for obtaining status or cancelling the deployment.
You assign a unique ID to an application when you deploy it, and then subsequently use the ID when redeploying, undeploying, stopping, and so on.
If you do not specify this attribute, the Ant task assigns a unique ID to the application.
String
ignoresessions This option immediately places the application into Administration mode without waiting for current HTTP sessions to complete.
You can use this attribute only when stopping or undeploying an application, or in other words, also specify either...
action="stop"
action="undeploy"

Valid values for this attribute are true and false. Default value is false.
Boolean
libImplVer Implementation version of a Java EE library or optional package.
This attribute can be used only if the library or package does not include a implementation version in its manifest file. You can specify this attribute only in combination with the library attribute.
String
library Identifies the deployment as a shared Java EE library or optional package. You must specify the library attribute when deploying or distributing any Java EE library or optional package.
Valid values for this attribute are true and false. Default value is false.
Boolean
libSpecVer Provides the specification version of a Java EE library or optional package.
This attribute can be used only if the library or package does not include a specification version in its manifest file. You can specify this attribute only in combination with the library attribute.
String
name The deployment name for the deployed application.
If you do not specify this attribute, WebLogic Server assigns a deployment name to the application, based on its archive file or exploded directory.
String
nostage Whether the deployment uses nostage deployment mode.
In this mode, the Ant task does not copy the deployment files to target servers, but leaves them in a fixed location, specified by the source attribute. Target servers access the same copy of the deployment files.
You can specify only one of the following attributes: stage, nostage, or external_stage. If none is specified, the default deployment mode to Managed Servers is stage; the default mode to the Administration Server and in single-server cases is nostage.
Boolean
noversion Indicates that the wldeploy Ant task should ignore all version related code paths on the Administration Server. This behavior is useful when deployment source files are located on Managed Servers (not the Administration Server) and you want to use the external_stage staging mode.
If you use this option, you cannot use versioned applications.
Valid values for this attribute are true and false. Default value is false.
Boolean
nowait Whether wldeploy returns immediately after making a deployment call (by deploying as a background task). Boolean
password The administrative password.
To avoid having the plain text password appear in the build file or in process utilities such as ps, first store a valid username and encrypted password in a configuration file using the WLST storeUserConfig command. Then omit both the username and password attributes in your Ant build file. When the attributes are omitted, wldeploy attempts to login using values obtained from the default configuration file.
If you want to obtain a username and password from a non-default configuration file and key file, use the userconfigfile and userkeyfile attributes with wldeploy.
String
plan Deployment plan to use when deploying the application or module.
By default, wldeploy does not use an available deployment plan, even if you are deploying from an application root directory that contains a plan.
String
planversion The version identifier of the deployment plan. String
remote Whether the server is located on a different machine. This affects how filenames are transmitted.
Valid values for this attribute are true and false. Default value is false, which means that the Ant task assumes that all source paths are valid paths on the local machine.
Boolean
retiretimeout Number of seconds before WebLogic Server undeploys the currently-running version of this application or module so that clients can start using the new version.
It is assumed, when you specify this attribute, that you are starting, deploying, or redeploying a new version of an already-running application.
int
securityModel Security model to use for this deployment. Possible security models are:

Deployment descriptors only
Customize roles
Customize roles and policies
Security realm configuration (advanced model)

Valid actual values for this attribute are DDOnly, CustomRoles, CustomRolesAndPolicy, or Advanced.
String
source The archive file or exploded directory to deploy. File
stage Whether the deployment uses stage deployment mode.
In this mode, the Ant task copies deployment files to target servers' staging directories.
You can specify only one of the following attributes: stage, nostage, or external_stage. If none is specified, the default deployment mode to Managed Servers is stage; the default mode to the Administration Server and in single-server cases is nostage.
Boolean
submoduletargets JMS server targets for resources defined within a JMS application module.
The value of this attribute is a comma-separated list of JMS server names.
String
targets The list of target servers to which the application is deployed.
The value of this attribute is a comma-separated list of the target servers, clusters, or virtual hosts.
If you do not specify a target list when deploying an application, the target defaults to the Administration Server instance.
String
timeout The maximum number of seconds to wait for a deployment to succeed. int
upload Whether the source file(s) are copied to the Administration Server's upload directory prior to deployment.
Use this attribute when you are on a remote machine and you cannot copy the deployment files to the Administration Server by other means.
Valid values for this attribute are true and false. Default value is false.
Boolean
usenonexclusivelock The deployment action (deploy, redeploy, stop, and so on) uses the existing lock on the domain that has already been acquired by the same user performing the action.
This attribute is particularly useful when the user is using multiple deployment tools (Ant task, command line, Administration console, and so on) simultaneously and one of the tools has already acquired a lock on the domain.
Valid values for this attribute are true and false. Default value is false.
Boolean
user The administrative username. String
userconfigfile Location of a user configuration file to use for obtaining the administrative username and password. Use this option, instead of the user and password attributes, in your build file when you do not want to have the plain text password shown in-line or in process-level utilities such as ps.
Before specifying the userconfigfile attribute, first generate the file using using the WLST storeUserConfig command
String
userkeyfile Location of a user key file to use for encrypting and decrypting the username and password information stored in a user configuration file (the userconfigfile attribute).
Before specifying the userkeyfile attribute, first generate the key file using the WLST storeUserConfig command
String
verbose Whether wldeploy displays verbose output messages. Boolean

Nested <files> Child Element

The wldeploy Ant task also includes the <files> child element that can be nested to specify a list of files on which to perform a deployment action (for example, a list of JSPs to undeploy.)
Use of <files> to redeploy a list of files in an application has been deprecated as of release 9.0 of WebLogic Server. Instead, use the deltaFiles attribute of wldeploy.
The <files> element works the same as the standard <fileset> Ant task (except for the difference in actual task name). Therefore, see the Apache Ant Web site for detailed reference information about the attributes you can specify for the <files> element.

Attribute	Description	Data Type
action	The deployment action to perform. Valid values are deploy, cancel, undeploy, redeploy, distribute, start, and stop.	String
adminmode	The deployment action puts the application into Administration mode. Administration mode restricts access to an application to a configured Administration channel. Valid values for this attribute are true and false. Default value is false, which means that by default the application is deployed in production mode so that all clients can access it immediately.	Boolean
adminurl	The URL of the Administration Server. The format of the value of this attribute is protocol://host:port, where protocol is either http or t3, host is the host on which the Administration Server is running, and port is the port which the Administration Server is listening. In order to use the HTTP protocol, enable the http tunnelling option in the Administration Console.	String
allversions	The action (redeploy, stop, and so on) applies to all versions of the application. Valid values for this attribute are true and false. The default value is false.	Boolean
altappdd	Name of an alternate Java EE deployment descriptor (application.xml) to use for deployment. If you do not specify this attribute, and you are deploying an Enterprise application, the default deployment descriptor is called application.xml and is located in the META-INF subdirectory of the main application directory or archive (specified by the source attribute.)	String
altwlsappdd	Name of an alternate WebLogic Server deployment descriptor (weblogic-application.xml) to use for deployment. If you do not specify this attribute, and you are deploying an Enterprise application, the default deployment descriptor is called weblogic-application.xml and is located in the META-INF subdirectory of the main application directory or archive (specified by the source attribute.)	String
appversion	The version identifier of the deployed application.	String
debug	Enable wldeploy debugging messages.	Boolean
deleteFiles	Whether to remove static files from a server's staging directory. This attribute is valid only for unarchived deployments, and only for applications deployed using stage mode. You must specify target servers when using this attribute. Specifying the deleteFiles attributes indicates that WebLogic Server should remove only thos files that it copied to the staging area during deployment. This attribute can be used only in combination with action="redeploy". Because the deleteFiles attribute deletes all specified files, Oracle recommends that you use caution when using the deleteFiles attribute and that you do not use it in production environments. Valid values for this attribute are true and false. Default value is false.	Boolean
deltaFiles	Comma- or space-separated list of files, relative to the root directory of the application, which are to be redeployed. Use this attribute only in conjunction with action="redeploy" to perform a partial redeploy of an application.	String
enableSecurityValidation	Whether or not to enable validation of security data. Valid values for this attribute are true and false. Default value is false.	Boolean
externalStage	Whether the deployment uses external_stage deployment mode. In this mode, the Ant task does not copy the deployment files to target servers; instead, ensure that deployment files have been copied to the correct subdirectory in the target servers' staging directories. You can specify only one of the following attributes: stage nostage external_stage If none is specified, the default deployment mode to Managed Servers is stage The default mode to the Administration Server and in single-server cases is nostage.	Boolean
failonerror	This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. Valid values for this attribute are true and false. Default value is true.	Boolean
graceful	Stops the application after existing HTTP clients have completed their work. You can use this attribute only when stopping or undeploying an application, or in other words, also specify either the action="stop" or action="undeploy" attributes. Valid values for this attribute are true and false. Default value is false.	Boolean
id	Identification used for obtaining status or cancelling the deployment. You assign a unique ID to an application when you deploy it, and then subsequently use the ID when redeploying, undeploying, stopping, and so on. If you do not specify this attribute, the Ant task assigns a unique ID to the application.	String
ignoresessions	This option immediately places the application into Administration mode without waiting for current HTTP sessions to complete. You can use this attribute only when stopping or undeploying an application, or in other words, also specify either... action="stop" action="undeploy" Valid values for this attribute are true and false. Default value is false.	Boolean
libImplVer	Implementation version of a Java EE library or optional package. This attribute can be used only if the library or package does not include a implementation version in its manifest file. You can specify this attribute only in combination with the library attribute.	String
library	Identifies the deployment as a shared Java EE library or optional package. You must specify the library attribute when deploying or distributing any Java EE library or optional package. Valid values for this attribute are true and false. Default value is false.	Boolean
libSpecVer	Provides the specification version of a Java EE library or optional package. This attribute can be used only if the library or package does not include a specification version in its manifest file. You can specify this attribute only in combination with the library attribute.	String
name	The deployment name for the deployed application. If you do not specify this attribute, WebLogic Server assigns a deployment name to the application, based on its archive file or exploded directory.	String
nostage	Whether the deployment uses nostage deployment mode. In this mode, the Ant task does not copy the deployment files to target servers, but leaves them in a fixed location, specified by the source attribute. Target servers access the same copy of the deployment files. You can specify only one of the following attributes: stage, nostage, or external_stage. If none is specified, the default deployment mode to Managed Servers is stage; the default mode to the Administration Server and in single-server cases is nostage.	Boolean
noversion	Indicates that the wldeploy Ant task should ignore all version related code paths on the Administration Server. This behavior is useful when deployment source files are located on Managed Servers (not the Administration Server) and you want to use the external_stage staging mode. If you use this option, you cannot use versioned applications. Valid values for this attribute are true and false. Default value is false.	Boolean
nowait	Whether wldeploy returns immediately after making a deployment call (by deploying as a background task).	Boolean
password	The administrative password. To avoid having the plain text password appear in the build file or in process utilities such as ps, first store a valid username and encrypted password in a configuration file using the WLST storeUserConfig command. Then omit both the username and password attributes in your Ant build file. When the attributes are omitted, wldeploy attempts to login using values obtained from the default configuration file. If you want to obtain a username and password from a non-default configuration file and key file, use the userconfigfile and userkeyfile attributes with wldeploy.	String
plan	Deployment plan to use when deploying the application or module. By default, wldeploy does not use an available deployment plan, even if you are deploying from an application root directory that contains a plan.	String
planversion	The version identifier of the deployment plan.	String
remote	Whether the server is located on a different machine. This affects how filenames are transmitted. Valid values for this attribute are true and false. Default value is false, which means that the Ant task assumes that all source paths are valid paths on the local machine.	Boolean
retiretimeout	Number of seconds before WebLogic Server undeploys the currently-running version of this application or module so that clients can start using the new version. It is assumed, when you specify this attribute, that you are starting, deploying, or redeploying a new version of an already-running application.	int
securityModel	Security model to use for this deployment. Possible security models are: Deployment descriptors only Customize roles Customize roles and policies Security realm configuration (advanced model) Valid actual values for this attribute are DDOnly, CustomRoles, CustomRolesAndPolicy, or Advanced.	String
source	The archive file or exploded directory to deploy.	File
stage	Whether the deployment uses stage deployment mode. In this mode, the Ant task copies deployment files to target servers' staging directories. You can specify only one of the following attributes: stage, nostage, or external_stage. If none is specified, the default deployment mode to Managed Servers is stage; the default mode to the Administration Server and in single-server cases is nostage.	Boolean
submoduletargets	JMS server targets for resources defined within a JMS application module. The value of this attribute is a comma-separated list of JMS server names.	String
targets	The list of target servers to which the application is deployed. The value of this attribute is a comma-separated list of the target servers, clusters, or virtual hosts. If you do not specify a target list when deploying an application, the target defaults to the Administration Server instance.	String
timeout	The maximum number of seconds to wait for a deployment to succeed.	int
upload	Whether the source file(s) are copied to the Administration Server's upload directory prior to deployment. Use this attribute when you are on a remote machine and you cannot copy the deployment files to the Administration Server by other means. Valid values for this attribute are true and false. Default value is false.	Boolean
usenonexclusivelock	The deployment action (deploy, redeploy, stop, and so on) uses the existing lock on the domain that has already been acquired by the same user performing the action. This attribute is particularly useful when the user is using multiple deployment tools (Ant task, command line, Administration console, and so on) simultaneously and one of the tools has already acquired a lock on the domain. Valid values for this attribute are true and false. Default value is false.	Boolean
user	The administrative username.	String
userconfigfile	Location of a user configuration file to use for obtaining the administrative username and password. Use this option, instead of the user and password attributes, in your build file when you do not want to have the plain text password shown in-line or in process-level utilities such as ps. Before specifying the userconfigfile attribute, first generate the file using using the WLST storeUserConfig command	String
userkeyfile	Location of a user key file to use for encrypting and decrypting the username and password information stored in a user configuration file (the userconfigfile attribute). Before specifying the userkeyfile attribute, first generate the key file using the WLST storeUserConfig command	String
verbose	Whether wldeploy displays verbose output messages.	Boolean