wldeploy Ant Task Reference

B wldeploy Ant Task Reference

Learn about the different tools to deploy applications and standalone modules to WebLogic Server.

This chapter includes the following sections:

Overview of the wldeploy Ant Task
The wldeploy Ant task enables you to perform weblogic.Deployer functions using attributes specified in an Ant XML file.
Basic Steps for Using wldeploy
To use the wldeploy Ant task you must perform several required and some optional steps.
Sample build.xml Files for wldeploy
Examine these sample build.xml files which show how to deploy an application on a single WebLogic Server instance, undeploy the application, perform a partial redeploy of the application, undeploy a particular file in the application, and deploy a Java EE library.
wldeploy Ant Task Attribute Reference

Overview of the wldeploy Ant Task

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 Using Ant Tasks to Configure and Use a WebLogic Server Domain, for more information about wlserver and wlconfig. See Building Applications in a Split Development Directory, for information about wlcompile.

Parent topic: wldeploy Ant Task Reference

Basic Steps for Using wldeploy

To use the wldeploy Ant task you must perform several required and some optional steps.

Set your environment.

On Windows platforms, execute the setWLSEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Server installation.

On UNIX, execute the setWLSEnv.sh command, located in the directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Server installation.

Note:

On UNIX operating systems, the setWLSEnv.sh command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.
In the staging directory, create the Ant build file (build.xml by default). If you want 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. See Using Ant Tasks to Configure and Use a WebLogic Server Domain, for information about wlserver and wlconfig.
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 and wldeploy Ant Task Attribute Reference.
Execute the Ant task or tasks specified in the build.xml file by typing ant in the staging directory, optionally passing the command a target argument:
```
prompt> ant
```

Parent topic: wldeploy Ant Task Reference

Sample build.xml Files for wldeploy

Examine these sample build.xml files which show how to deploy an application on a single WebLogic Server instance, undeploy the application, perform a partial redeploy of the application, undeploy a particular file in the application, and deploy a Java EE library.

The following example shows a wldeploy target that deploys 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>

The following example shows a corresponding task to undeploy the application; the example shows that when you undeploy or redeploy an application, you do not specify the source archive file or exploded directory, but rather, just its 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>

The following example shows how to 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>

The following example uses 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>

The following example shows how to 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>

Parent topic: wldeploy Ant Task Reference

wldeploy Ant Task Attribute Reference

The following sections describe the attributes and child element <files> of the wldeploy Ant task.

Parent topic: wldeploy Ant Task Reference

Main Attributes

The following table describes the main attributes of the wldeploy Ant task.

These attributes mirror some of the arguments of the weblogic.Deployer command. Oracle provides an Ant task version of the weblogic.Deployer command so that developers can easily deploy and test their applications as part of the iterative development process. Typically, however, administrators use the weblogic.Deployer command, and not the wldeploy Ant task, to deploy applications in a production environment. For that reason, see the weblogic.Deployer Command-Line Reference in Deploying Applications to Oracle WebLogic Server for the full and complete definition of the attributes of the wldeploy Ant task. The table below is provided just as a quick summary.

Table B-1 Attributes of the wldeploy Ant Task

Attribute	Description	Data Type
`action`	The deployment action to perform. Valid values are `deploy`, `cancel`, `undeploy`, `redeploy`, `distribute`, `start`, and `stop`.	`String`
`adminmode`	Specifies that 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. Note: In order to use the HTTP protocol, you must enable the http tunnelling option in the WebLogic Server Administration Console.	`String`
`allversions`	Specifies that 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`	Specifies the 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`	Specifies the 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`	Specifies 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 those 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`	Specifies a 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`	Specifies whether or not to enable validation of security data. Valid values for this attribute are true and false. Default value is false.	`Boolean`
`externalStage`	Specifies whether the deployment uses `external_stage` deployment mode. In this mode, the Ant task does not copy the deployment files to target servers; instead, you must 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`, 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`. See Controlling Deployment File Copying with Staging Modes.	`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, you must 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, you must also specify either the `action="stop"` or `action="undeploy"` attributes. Valid values for this attribute are `true` and `false`. Default value is `false`.	`Boolean`
`libImplVer`	Specifies the 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. See Creating Shared Java EE Libraries and Optional Packages.	`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`. See Creating Shared Java EE Libraries and Optional Packages.	`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. See Creating Shared Java EE Libraries and Optional Packages.	`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`	Specifies 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`. See Controlling Deployment File Copying with Staging Modes.	`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`	Specifies whether `wldeploy` returns immediately after making a deployment call (by deploying as a background task).	`Boolean`
`partition`	Specifies the name of the partition associated with the resource group on which you want to perform deployment actions for an application or library. You can specify the partition attribute for the following deployment actions: deploy, undeploy, redeploy, distribute, start, and stop. The partition attribute is optional for partition administrators. For more information about deploying applications to partition resource groups, see Deploying Applications in Using WebLogic Server MT.	`String`
`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 user name and encrypted password in a configuration file using the WebLogic Scripting Tool (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 user name and password from a non-default configuration file and key file, use the `userconfigfile` and `userkeyfile` attributes with `wldeploy`. See the command reference for `storeUserConfig` in the WLST Command Reference for WebLogic Server for more information on storing and encrypting passwords.	`String`
`plan`	Specifies a 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`	Specifies 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`
`removePlanOverride`	Removes an overridden deployment plan during a redeploy or update deployment action. For applications or libraries deployed to a resource group, you can override the default application configuration defined in the resource group template that the resource group references. To remove an application override, specify the removePlanOverride attribute. You can specify the removePlanOverride attribute for the redeploy deployment actions. For more information about overriding application configuration, see Overriding Application Configuration in Using WebLogic Server MT.	`String`
`resourceGroup`	Specifies the name of the resource group at the partition or domain level on which you want to perform deployment actions for an application or library. For deploy, and distribute actions, you must specify the name of the resource group to which you want to deploy or distribute applications or libraries by setting the resourceGroup attribute. For partitions, if only one resource group exists in the specified partition, then the resourceGroup attribute is optional. For other supported deployment actions, you do not specify the resourceGroup attribute, as WebLogic Server derives the resource group from the unique application name. For more information about deploying applications to resource groups at the domain or partition level, see Deploying Applications to Partition Resource Groups in Deploying Applications to Oracle WebLogic Server.	`String`
`resourceGroupTemplate`	Specifies the name of the resource group template to which you want to perform a deployment action for an application or library. You can specify the resourceGroupTemplate attribute with the following deployment actions: deploy, undeploy, redeploy, and distribute. For more information about deploying applications to resource group templates, see Application Deployment with Resource Group Templates in Deploying Applications to Oracle WebLogic Server.	`String`
`retiretimeout`	Specifies the 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. See Redeploying Applications in a Production Environment.	`int`
`securityModel`	Specifies the 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`. See Options for Securing Web application and EJB Resources for more information on these security models.	`String`
`source`	The archive file or exploded directory to deploy.	`File`
`stage`	Specifies 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`. See Controlling Deployment File Copying with Staging Modes.	`Boolean`
`submoduletargets`	Specifies 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. See Using Sub-Module Targeting with JMS Application Modules.	`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`	Specifies 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`	Specifies that 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, WebLogic Server 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 user name.	`String`
`userconfigfile`	Specifies the location of a user configuration file to use for obtaining the administrative user name 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, you must first generate the file using the WebLogic Scripting Tool (WLST) `storeUserConfig` command as described in the WLST Command Reference for WebLogic Server.	`String`
`userkeyfile`	Specifies the location of a user key file to use for encrypting and decrypting the user name and password information stored in a user configuration file (the `userconfigfile` attribute). Before specifying the `userkeyfile` attribute, you must first generate the key file using the WebLogic Scripting Tool (WLST) `storeUserConfig` command as described in the WLST Command Reference for WebLogic Server.	`String`
`verbose`	Specifies whether `wldeploy` displays verbose output messages.	`Boolean`

Parent topic: wldeploy Ant Task Attribute Reference

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.)

Note:

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 at http://ant.apache.org/manual/Types/fileset.html for detailed reference information about the attributes you can specify for the <files> element.

Parent topic: wldeploy Ant Task Attribute Reference