> Developing Applications with WebLogic Server > wldeploy Ant Task Reference

Developing Applications with WebLogic Server

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

wldeploy Ant Task Reference

The following sections describe tools for deploying applications and standalone modules to WebLogic Server:

 

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:

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:

  1. Set your environment.

    2. On Windows NT, 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.

  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:
    3. <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:
    6. prompt> ant

 

Sample build.xml Files for wldeploy

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 J2EE 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. BEA 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 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 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 J2EE 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 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, BEA 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 J2EE 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 J2EE Libraries and Optional Packages.
String
library
Identifies the deployment as a shared J2EE library or optional package. You must specify the library attribute when deploying or distributing any J2EE library or optional package.
Valid values for this attribute are true and false. Default value is false.
See Creating Shared J2EE Libraries and Optional Packages.
Boolean
libSpecVer
Provides the specification version of a J2EE 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 J2EE 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
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 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 username 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 and Variable Reference 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
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 Updating 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 the 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, 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
Specifies the 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, you must first generate the file using using the WebLogic Scripting Tool (WLST) storeUserConfig command as described in the WLST Command and Variable Reference.
String
userkeyfile
Specifies the 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, you must first generate the key file using the WebLogic Scripting Tool (WLST) storeUserConfig command as described in the WLST Command and Variable Reference.
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.)

WARNING: 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.


  Back to Top       Previous  Next