Developing Applications with WebLogic Server

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:

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:

Set your environment.

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.

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

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
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
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
external_stage	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
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.Admin 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 STOREUSERCONFIG in the weblogic.Admin Command-Line 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 EJB and Web Application 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 time 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 the `weblogic.Admin` `STOREUSERCONFIG` command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line 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.Admin` `STOREUSERCONFIG` command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line 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 in this release. 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.