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-10. 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. The most commonly-used options appear in boldface.
| -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. |
| -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, 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, 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, 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. |
|
Action |
Description |
|---|---|
| -deploy | Deploys or redeploys an application. (You may also use -activate as an alias.) |
| -undeploy | Stops the deployment unit and removes staged files and deployment information from all target servers. (You may also use -remove as an alias.) |
| -redeploy | Replaces a running application or part of a running application. |
| -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. (You may also use -deactivate as an alias.) |
| -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. (You may also use -activate as an alias.) |
| -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. |
| -delete_files | Removes files specified in the file list and leaves the application activated. This is valid only for unarchived applications. You must specify target servers. |
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 output 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>
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
|
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 |
| debug | Enable wldeploy debugging messages. | boolean | 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 |
| user | The administrative username. | String | 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 |
| targets | The list of target servers to deploy to. | String | No |
| timeout | The maximum time to wait for a deployment to succeed. | int | 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, first generate the file using the weblogic.Admin STOREUSERCONFIG command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line Reference. | File | 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, first generate the key file using the weblogic.Admin STOREUSERCONFIG command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line Reference. | File | 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.
|
|
|