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.

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.

Basic Steps for Using wldeploy

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

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

  2. 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"/>
    
  3. 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.
  4. 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.
  5. 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

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>

wldeploy Ant Task Attribute Reference

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

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

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.