Deploying WebLogic Server Applications

Deployment Tools Reference

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

weblogic.Deployer Utility

The weblogic.Deployer utility replaces the earlier weblogic.deploy utility, which has been deprecated. The weblogic.Deployer utility is a Java-based deployment tool that provides a command-line interface to the WebLogic Server Deployment Management API on page 5-11. This utility was developed for administrators and developers who need to initiate deployment from the command line, a shell script, or any automated environment other than Java.

Using weblogic.Deployer Utility

To use the weblogic.Deployer utility:

Set up your local environment so that WebLogic Server classes are in your system CLASSPATH and the JDK is available. You can use the setenv script located in your server's /bin directory to set the CLASSPATH.

Use the following command syntax:

% java weblogic.Deployer [options] [actions] [file(s)]

You can also list specific files in the archive that are to be deployed (or redeployed, or undeployed). The file list can include file names and directories relative to the root of the application. If you specify a directory, its entire subtree is deployed or redeployed.

weblogic.Deployer Actions and Options

The following table lists weblogic.Deployer options.

Note: The activate and deactivate actions have been deprecated. Use deploy or start instead of activate. Use undeploy or stop instead of deactivate.

Table 5-1 weblogic.Deployer Options

Option	Description
`-adminurl <protocol>://<server>:<port>`	The URL of the Administration Server. Default is `http://localhost:7001`.
`-username <user>`	The Administrator username. If you supply the `-username` option but you do not supply a corresponding `-password` option, `weblogic.Deployer` prompts you for the password.
`-password <password>`	The password of the Administrator user. To avoid having the plain text password appear in scripts or in process utilities such as `ps`, first store the username and encrypted password in a configuration file using the `STOREUSERCONFIG` command with `weblogic.Admin`. Omit both the `-username` and `-password` options to `weblogic.Deployer` to use the values stored in the default configuration file. See STOREUSERCONFIG in the weblogic.Admin Command-Line Reference for more information on storing and encrypting passwords. If you want to use a specific configuration file and key file, rather than the default files, use the `-userconfigfile` and `-userkeyfile` options to `weblogic.Deployer`.
`-name <deployment name>`	Specifies the deployment name for the application or standalone module. This can be the name of an existing, configured application or the name to use when creating a new configuration.
`-targets <target list>`	A comma-separated list of the target servers and/or cluster names (<server1>,<cluster1>,...). Each target may be qualified with a J2EE module name (<module1>`@`<server1>). This enables different modules of the archive to be deployed on different servers. For an application that is currently deployed, `-targets` defaults to all current targets. For an application that you are deploying for the first time, `-targets` defaults to the Administration Server.
`-delete_files <file list>`	Used after the `-redeploy` action, this option removes static files from a server's staging directory. `delete_files` is valid only for unarchived deployments, and only for applications deployed using stage mode. You must specify target servers when using this option, as shown in the following example: `java weblogic.Deployer -adminurl http://myserver:7001 -username weblogic -password weblogic -name myapp -targets myapp@myserver -redeploy -delete_files myapp/tempindex.html` `delete_files` only removes files that WebLogic Server copied to the staging area during deployment. If you use the `delete_files` option with an application that was deployed using either nostage or external_stage mode, the command does not delete the files. `delete_files` can only be used in combination with the `redeploy` action.
`-userconfigfile <path to file>`	Specifies the location of a user configuration file to use for the administrative username and password. Use this option, instead of the `-user` and `-password` options, in automated scripts or in situations where you do not want to have the password shown on-screen or in process-level utilities such as `ps`. Before specifying the `-userconfigfile` option, you must first generate the file using the `weblogic.Admin` `STOREUSERCONFIG` command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line Reference.
`-userkeyfile <path to file>`	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` option). Before specifying the `-userkeyfile` option, you must first generate the key file using the `weblogic.Admin` `STOREUSERCONFIG` command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line Reference.
`-verbose`	Displays additional progress messages, including details about the prepare and activate phases of the deployment.
`-output <raw>`	Specify either `raw` or `formatted` to control the appearance of `weblogic.Deployer` output messages. Both output types contain the same information, but `raw` output does not contain embedded tabs. By default, `weblogic.Deployer` displays `raw` output.
`-debug`	Display debug messages in the standard output.
`-help`	Prints command-line help text for the most commonly-used `weblogic.Deployer` actions and options.
`-advanced`	Prints full command-line help text for all `weblogic.Deployer` actions and options.
`-examples`	Display example command lines for common tasks.
`-upload`	Transfers the specified source file(s) to the Administration Server. Use this option when you are on a different machine from the Administration Server and you cannot copy the deployment files by other means. The application files are uploaded to the WebLogic Server Administration Server's upload directory prior to deployment.
`-remote`	Indicates that `weblogic.Deployer` is not running on the same machine as the Administration Server, and that source paths specified in the command are valid for the Administration Server machine itself. If you do not use the `-remote` option, `weblogic.Deployer` assumes that all source paths are valid paths on the local machine.
`-nostage`	Does not copy the deployment files to target servers; instead, deploys them from the fixed location specified using the `-source` option. `nostage` is the default when you deploy to the Administration Server (for example, in a single-server domain).
`-stage`	Copies deployment files to target servers' staging directories before deployment. stage is used as the default when deploying to Managed Server targets.
`-external_stage`	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 before deployment. You can manually copy the files or use a third-party tool or script.
`-nowait`	`weblogic.Deployer` prints the task ID and exits without waiting for the action to complete. This option is used to initiate multiple tasks and then monitor them later with the `-list` action.
`-timeout <seconds>`	Specifies the maximum time, in seconds, to wait for the deployment task to complete. After the time expires, `weblogic.Deployer` prints out the current status of the deployment and exits.
`-source <archive file or exploded archive directory>`	Specifies the location of the archive file or exploded archive directory to deploy.
`-altappdd`	Specifies the name of an alternate J2EE deployment descriptor (`application.xml`) to use for deployment.
`-altwlsappdd`	Specifies the name of an alternate WebLogic Server deployment descriptor (`weblogic-application.xml`) to use for deployment.
`-id <task identifier>`	Specifies the task identifier of a running deployment task. You can specify an identifier with the `-deploy`, `-redeploy,` or `-undeploy` actions, and use it later as an argument to the `-cancel` or `-list` actions. Make sure that the identifier is unique to all other running deployment tasks. The system automatically generates a unique identifier if you do not specify one.
`-version`	Prints version information.

Table 5-2 weblogic.Deployer Actions

Action	Description
`-deploy`	Deploys or redeploys an application.
`-undeploy`	Stops the deployment unit and removes staged files and deployment information from all target servers. (You may also use `-remove` as an alias.) Note: An application becomes unavailable to clients during an undeployment. WebLogic Server doesn't guarantee the operation of the application and deployment task if there is an access from the client at this time.
`-redeploy`	Replaces a running application or part of a running application. Note: An application becomes unavailable to clients during redeployment. WebLogic Server doesn't guarantee the operation of the application and deployment task if there is an access from the client at this time. For this reason, redeployment is not recommended for use in a production environment.
-stop	Makes an application inactive and unavailable to clients on target servers. The deployment information and staged files remain available on target servers for subsequent `-start`, `-deploy`, `-redeploy`, or `-undeploy` actions.
-start	Makes an inactive application available to clients on target servers. `-start` does not redistribute deployment files to target servers; the files must already be available via an earlier `-deploy` or `-distribute` action.
-distribute	Perform only the activate stage of a deployment by copying deployment files to target server staging directories (if necessary) and registering the deployment name. The application is ready for deployment, but is unavailable to clients on the target server. You can later use the `-start` action to make the application available to clients.
`-cancel`	Attempts to cancel the task identified by -id if it is not yet completed.
`-list`	Lists the status of the task identified by `-id`.
-listtask	Lists running deployment tasks in the domain.
-listapps	Lists all deployment names for applications and standalone modules deployed in the domain.

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 a WebLogic Server Domain in the WebLogic Server Command Reference for more information about wlserver and wlconfig. See Programming Topics in Developing WebLogic Server Applications 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 a WebLogic Server Domain in the WebLogic Server Command Reference 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 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 sample shows a wldeploy target that deploys an application to a single WebLogic Server instance:

<target name="deploy">
   <wldeploy action="deploy"
      source="${build}/ejb11_basic_statelessSession.ear" name="ejbapp"
      user="a" password="a" verbose="true" adminurl="t3://localhost:7001"
      debug="true" targets="myserver"/>
</target>

The following sample shows a more advanced wldeploy target that redeploys a single file in an exploded Web Application:

<target name="redeploy">
   <wldeploy action="redeploy"
      source="c:\myapps\myWebApp\" name="myWebApp"
      user="weblogic" password="weblogic" verbose="true" 
      adminurl="t3://localhost:7001"
      debug="true" targets="examplesServer">
     <files file="index.jsp"/>
   </wldeploy>
</target>

wldeploy Ant Task Reference

The following table describes the attributes of the wldeploy Ant task. For more information about the definition of various terms, see weblogic.Deployer Actions and Options

Table 5-3 Attributes of the wldeploy Ant Task

Attribute	Description	Data Type	Required?
action	The deployment action to perform. Valid values are `deploy`, `cancel`, `undeploy`, `redeploy`, `distribute`, `start`, and `stop`.	String	No
adminurl	The URL of the Administration Server.	String	No
altappdd	Specifies the name of an alternate J2EE deployment descriptor (`application.xml`) to use for deployment.	String	No
altwlsappdd	Specifies the name of an alternate WebLogic Server deployment descriptor (`weblogic-application.xml`) to use for deployment.	String	No
debug	Enable `wldeploy` debugging messages.	boolean	No
external_stage	Specifies whether the deployment uses external_stage deployment mode.	boolean	No
files	Specifies a file or list of files on which to perform a deployment action (for example, a list of JSPs to redeploy). See Sample build.xml Files for wldeploy.	FileSet	No
id	Identification used for obtaining status or cancelling the deployment.	String	No
name	The deployment name for the deployed application.	String	No
nostage	Specifies whether the deployment uses nostage deployment mode.	boolean	No
nowait	Specifies whether wldeploy returns immediately after making a deployment call (by deploying as a background task).	boolean	No
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	No
remote	Specifies whether the server is located on a different machine. This affects how filenames are transmitted.	boolean	No
source	The source file to deploy.	File	No
stage	Specifies whether the deployment uses stage deployment mode.	boolean	No
targets	The list of target servers to deploy to.	String	No
timeout	The maximum time to wait for a deployment to succeed.	int	No
upload	Specifies whether the source file(s) are copied to the Administration Server's upload directory prior to deployment.	boolean	No
user	The administrative username.	String	No
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	No
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	No
verbose	Specifies whether `wldeploy` displays verbose output messages.	boolean	No
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. This attribute is set to true by default.	Boolean	No

WebLogic Builder

WebLogic Builder is a WebLogic Server tool for generating and editing deployment descriptors for J2EE applications. It can also deploy applications to single servers.

See the WebLogic Builder Online Help.

Deployment Management API

A deployment task is initiated through a DeployerRuntimeMBean—a singleton (an object for which only one instance exists) that resides on an Administration Server. DeployerRuntimeMBean provides methods for activating, deactivating, and removing an application. These methods return a DeploymentTaskRuntimeMBean that encapsulates the request and provides the means for tracking its progress. DeploymentTaskRuntimeMBean provides ongoing status of the request through TargetStatus objects, one per target.

The WebLogic Server deployment management API is defined by the following WebLogic Server MBeans:

DeployerRuntimeMBean—programmatic interface to deployment requests. Deployment requests provided through the DeployerRuntimeMBean manifest the configuration state into the application and appropriate component configuration MBeans. These MBeans persist the deployment state of applications in the WebLogic Server domain.
DeploymentTaskRuntimeMBean—interface for encompassing deployment tasks.

The deployment management API is asynchronous. The client must poll the status or utilize ApplicationMBean notifications to determine when the task is complete.

For more information about WebLogic Server deployment management APIs, see the weblogic.management.deploy Javadoc.