WebLogic Server Deployment

e-docs > WebLogic Server > Developing WebLogic Server Applications > WebLogic Server Deployment

Developing WebLogic Server Applications

WebLogic Server Deployment

This release of WebLogic Server introduces a new deployment protocol, two-phase deployment, which helps prevent inconsistent deployment states across servers, especially clustered servers. See Two-Phase Deployment.

You can deploy an application using the WebLogic Server Administration Console, weblogic.Deployer utility, WebLogic Builder, or auto-deployment. These deployment tools are discussed in Deployment Tools and Procedures.

The following sections discuss WebLogic Server deployment:

Two-Phase Deployment

The new two-phase deployment protocol helps to maintain domain consistency. In previous versions of WebLogic Server, when you deployed an application, the administration server sent a copy of the application file(s) to all the targeted servers, which then loaded the application. If deployment to any of those servers failed or partially failed, the entire deployment's state across its target servers became inconsistent.

In the current release of WebLogic Server, deployment first prepares the application across all target servers and then activates the application in a separate phase. If a deployment of an application fails in either the preparation or activation phase, then the cluster deployment is failed.

For information about using the earlier WebLogic Server deployment protocol, see Using WebLogic Server 6.x Deployment Protocol.

The new deployment protocol supports the following new features for deployed applications:

Consistent deployment states for clusters. If an application targeted to a cluster fails on any of the cluster members in the prepare phase and then in the activate phase, the application is not activated on any of the cluster members. This helps to ensure that the cluster is kept homogeneous.
Application ordering. At server startup, you set the order of application activations. See Deployment Order for Resources and Applications.
Application-scoped configuration. Certain resources can be configured and scoped for an application. These include connection pools, security realms and XML related resources. See Overview of Application Scoping.
Improved redeployment. You do not need to undeploy before redeploying. See Updating Applications with the Administration Console, Undeploying and Redeploying Archived Applications, and Redeploying Applications in Exploded Format
Note: An application becomes unavailable to clients during redeployment. For this reason, redeployment is not recommended for use in a production environment.
Improved API. A simple API separates configuration from the actual deployment operations. When a deployment is requested, this API creates the necessary configuration (MBeans) for you. Also, the deployment operations are not on the MBeans themselves, so you can change the configuration (such as the target lists) without affecting the deployed application, until a deployment request is initiated. See Deployment Management API, and see also the API documentation at weblogic.management.deploy.
Deployment status. It is now easier to track the progress of a deployment especially when it has multiple targets. See Example Uses of the weblogic.Deployer Utility, and WebLogic Administration Console help on Tasks.

Restarting Admin Server

Stopping and restarting your Admin Server cancels pending deployment requests. If your are deploying to a cluster and one of the targeted servers in the cluster is down, an Admin Server restart will prevent the targeted server from receiving the deployment request when the targeted server comes back up.

Prepare Phase and Activate Phase

The two-phase model makes inconsistent deployment states in clusters less likely by confirming the success of the prepare phase before deploying the application on any targeted servers. A deployment that fails during the prepare phase will not enter the activation phase.

Prepare Phase

The prepare phase of deployment, the first phase, distributes or copies files and prepares the application and its components for activation, validating them and performing error checks on them. The purpose of the prepare phase is to ensure that the application and its components are in a state in which they can be reliably deployed.

Activate Phase

The second phase, the activate phase, is the actual deployment, or activation, of the application and its component with the relevant server subsystem. After the activate phase, the application is made available to clients.

Deployment Order for Resources and Applications

By default, WebLogic Server deploys server-level resources (JDBC followed by JMS) before deploying applications and standalone modules, followed by startup classes. The order of startup class execution is configurable, as described in Ordering Startup Class Execution and Deployment.

Setting the Order of Applications

Applications are deployed in this order: connectors, then EJBs, then Web Applications. WebLogic Server 7.0 allows you to select the load order for applications. See the ApplicationMBean LoadOrder attribute in Application.

Ordering Components Within an Application

If the application is an EAR, the individual components are loaded in the order in which they are declared in the application.xml deployment descriptor. See Editing Enterprise Application Deployment Descriptors.

Ordering Startup Class Execution and Deployment

By default WebLogic Server startup classes are run after the server initializes JMS and JDBC services, and after applications and standalone modules have been deployed.

If you want to perform startup tasks after JMS and JDBC services are available, but before applications and modules have been activated, you can select the Run Before Application Deployments option in the Administration Console (or set the StartupClassMBean's LoadBeforeAppActivation attribute to "true").

If you want to perform startup tasks before JMS and JDBC services are available, you can select the Run Before Application Activations option in the Administration Console (or set the StartupClassMBean's LoadBeforeAppDeployments attribute to "true").

The following figure summarizes the time at which WebLogic Server executes startup classes.

Figure 5-1 Startup Class Execution

BEA provides the examples.jms.startup API code example which demonstrates how to establish a JMS message consumer from a WebLogic startup class. See the full Javadocs for StartupClassMBean for more information.

Note: WebLogic Server 7.0 optionally installs API code examples in WL_HOME\samples\server\src\examples, where WL_HOME is the top-level directory of your WebLogic Server installation. You can start the examples server, and obtain information about the samples and how to run them.

Application Staging

In this release of WebLogic Server, the staging mode controls whether or not, where, and by whom application files are copied for deployment. Staging means the copying of application files to the locations from which they will be deployed. Each server has a staging mode. Once an application is deployed, its staging mode cannot be changed. See Best Practices for Application Deployment for help on when to use staging modes.

Staging Modes

Available staging modes are:

nostage: does not copy application files to another location.
A server in nostage mode will run applications deployed to it directly from their source directories. In this mode, the web application container detects changes to JSPs and servlets.
stage: copies application files to server targeted in deployment
The stage mode means that the Administration Server copies source files to the staging directory on target servers when you perform a deployment operation. The target servers then initialize and run the application from this directory.
external_stage: the user, and not WebLogic Server, ensures that application files are copied to the server's staging directory before deployment.
The deployment should be copied to a directory with the same name as the application name under each target server's staging directory.

The external stage mode means that the application will be run from a staging directory, to which an external entity is expected to distribute the files. This mode is useful in environments that are managed by third-party tools.

Note: In order to use either nostage or external_stage modes, the files to deploy must be accessible to the Administration Server machine. You can either copy the files to the Administration Server machine or place them on a shared directory that is available from the Administration Server machine.

Staging mode defaults are:

for managed servers, staging mode is stage by default, meaning that the default staging behavior is to copy the application files to their targeted managed servers
for administration servers, staging mode is nostage by default, meaning that the default staging behavior is to deploy from the source location provided

The following table describes how staging attribute and path settings affect an application's deployment:

Table 5-1 Deployment Staging Modes

Staging Mode	Staging Directory	Administration Server Deployment Behavior	Managed Server Deployment Behavior
stage	Absolute, Relative	Application files are copied to a directory named after the application deployment in the server staging directory, and activated from there (e.g., server/stage/myapp/app.ear). If the staging path is relative, the path is evaluated relative to the server's root directory.	Same as for Administration Server.
nostage	Absolute, Relative	Staging path is ignored, and no files are copied. Files are deployed from their location on the Administration Server, or from a shared directly accessible by the Administration Server.	Same as for Administration Server. (Source files must be accessible from the Managed Server machine in order to deploy.)
external_stage	Absolute, Relative	No files are copied, but deployment files are assumed to reside in a subdirectory named after the deployment in the server staging directory. and are loaded from there. For example, if you deploy an application using the deployment name "myextapp" and the server staging directory is .\myserver\stage, you must ensure that the deployment files are available in .\myserver\stage\myextapp before deploying. If the staging path is relative, the path is evaluated relative to the server's root directory.	Same as for Administration Server. (You must ensure deployment files are copied to the correct subdirectory of the Managed Server's staging directory.)

Staging Mode

Staging Directory

Administration Server Deployment Behavior

Managed Server Deployment Behavior

stage

Absolute, Relative

Application files are copied to a directory named after the application deployment in the server staging directory, and activated from there (e.g., server/stage/myapp/app.ear).

If the staging path is relative, the path is evaluated relative to the server's root directory.

Same as for Administration Server.

nostage

Absolute, Relative

Staging path is ignored, and no files are copied. Files are deployed from their location on the Administration Server, or from a shared directly accessible by the Administration Server.

Same as for Administration Server. (Source files must be accessible from the Managed Server machine in order to deploy.)

external_stage

Absolute, Relative

No files are copied, but deployment files are assumed to reside in a subdirectory named after the deployment in the server staging directory. and are loaded from there. For example, if you deploy an application using the deployment name "myextapp" and the server staging directory is .\myserver\stage, you must ensure that the deployment files are available in .\myserver\stage\myextapp before deploying.

If the staging path is relative, the path is evaluated relative to the server's root directory.

Same as for Administration Server. (You must ensure deployment files are copied to the correct subdirectory of the Managed Server's staging directory.)

Configuring Staging Modes and Directories

By default, when you deploy an application to a managed server, it is staged to the target server staging area (ServerMBean.StagingDirectoryName) and deployed from there. You can disable staging using the ServerMBean.StagingMode attribute or the ApplicationMBean.StagingMode attribute. The ServerMBean.StagingMode attribute applies to all applications deployed to that server. It can be overridden by ApplicationMBean.StagingMode.

See Best Practices for Application Deployment for help on when to use staging modes.

For Javadoc on the attributes mentioned here, see Javadocs for WebLogic Classes.

Staging Scenarios

You can configure the system to perform some common tasks described in the sections that follow.

Deploy Application from its Source Location

Configure the StagingMethod attribute on the application or on a specific server to be set to nostage. If you configure this on the application, you must do so when the application is configured in the server using the weblogic.Deployer tool.

This mode is useful for incremental development on a single server, and is also handy in a shared disk environment where multiple servers are using the same copy of the application.

Deploy Application from a Known Staging Area

Configure the StagingDirName attribute on each server to point to a well-known directory. You must place the actual EAR/JAR/WAR/RAR file in a directory having the name of the application within that directory.

Distribute Application Files to Managed Servers

If you set the StagingMode attribute to stage, WebLogic Server will copy the files from the source to the staging directory. To deploy using stage mode:

Configure the Managed Servers to use stage mode, and specify the staging directory each server uses.
Ensure that the files to deploy are available to the Administration Server for the domain—either copy the files to the Administration Server machine or place them on a shared filessytem available to the Administration Server machine.
Deploy the files to the Managed Servers using the Administration Console.

Deploy an Application Using external_stage Mode

external_stage mode requires that you either manually copy deployment files to Managed Servers or have an application or script copy the file for you. To deploy an application to Managed Servers using external_stage mode:

Configure the Managed Servers to use stage mode, and specify the staging directory each server uses.
In the staging area for the Managed Server, create a subdirectory with the deployment name you will use (for example, "mywar"), and copy the deployment files to that subdirectory.
Ensure that the files to deploy are available to the Administration Server for the domain—either copy the files to the Administration Server machine or place them on a shared filessytem available to the Administration Server machine.
Deploy the files to the Managed Servers using the Administration Console, using the same deployment name ("mywar"). The Managed Servers deploy using the deployment files you copied in Step 2 above.

Deployment Tools and Procedures

WebLogic Server deployment tools provide interfaces to the deployment API described in Deployment Management API.

The deployment instructions provided in this document presume that you have created a functional J2EE application that uses the correct directory structure and contains the appropriate deployment descriptors. Deployment descriptors, which are text files formatted with XML tags, describe the contents of the application directory or archive. The J2EE specifications define standard, portable deployment descriptors for J2EE applications and their components. BEA defines additional WebLogic-specific deployment descriptors for deploying an application and its components in the WebLogic Server environment. For more information, see XML Deployment Descriptors.

The following is a list of WebLogic Server deployment tools:

weblogic.Deployer Utility
wldeploy Ant Task
WebLogic Server Administration Console
WebLogic Builder
Auto-Deployment (for Development Mode only)

weblogic.Deployer Utility

The weblogic.Deployer utility is new in WebLogic Server 7.0 and 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 API. 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.

This section describes how to use the weblogic.Deployer utility to perform the following tasks:

Deploying Using weblogic.Deployer Utility

To deploy an application or its components using 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] [-activate|-deactivate|-remove|-cancel|-list] [files]

You can also list the specific -files in the archive that are to be deployed (or redeployed, or undeployed, or unprepared, or deactivated, or removed). 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

Table 5-2 weblogic.Deployer Actions

Action	Description
activate	Deploys or redeploys the application specified by -name to the servers specified by -targets.
cancel	Attempts to cancel the task identified by -id if it is not yet completed.
deactivate	Deactivates the application on the target servers. Deactivation suspends the deployed components, leaving staged data in place in anticipation of subsequent reactivation. This command only works in the two-phase deployment protocol.
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.
deploy	A convenient alias for -activate.
examples	Displays example usages of the tool.
help	Prints a help message.
list	Lists the status of the task identified by -id.
remove	Physically removes the application and any staged data from the target servers. The components are deactivated and the targets are removed from the applications configuration. If you remove the application entirely, the associated MBeans are also deleted from the system configuration. This command only works with the two-phase deployment model.
undeploy	A convenient alias for -unprepare.
unprepare	Deactivates and unloads classes for the application identified by -name on the target servers, leaving the staged application files in a state where they may be edited or quickly reloaded.
upload	Transfers the specified source file(s) to the administration server. Use this option when you are on a remote system and want to deploy an application that resides on the remote system. The application files are uploaded to the WebLogic Server administration server prior to distribution to named target servers.
version	Prints version information.

weblogic.Deployer options include:

Table 5-3 weblogic.Deployer Options

Option	Description
adminurl	https://<server>:<port> is the URL of the administration server. Default is http://localhost:7001.
debug	Turns on debug messages in the output log.
enforceClusterConstraints	Specifies whether a deployment to a cluster succeeds or fails when one or more members of the cluster are unavailable. Set this option to "true" to ensure that deployments succeed only when all members of the cluster are available.
external_stage	Indicates that user wants to copy the application to the servers' staging area externally on their own, or using a third-party tool. When specified, WLS looks for the application under StagingDirectoryName (of target server)/applicationName.
id	The task identifier -id is a unique identifier for the deployment task. You can specify an -id with the -activate, -deactivate, or -remove commands, and use it later as an argument to -cancel or -list. Make sure the -id is unique from all other existing deployment tasks. The system generates an -id if you do not specify one.
name	The application -name specifies the name of the application being deployed. This can be the name of an existing, configured application or the name to use when creating a new configuration.
nostage	Does not stage the application; instead, deploys it from its current location which you specify using the -source option. Defaults: nostage for admin server and stage for managed server targets.
nowait	Once the action is initiated, the tool prints the task id and exits. This is used to initiate multiple tasks and then monitor them later using the -list action.
output	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.
password	Specifies the password on the command line. If you do not provide a password, you will be prompted for one.
remote	Signals that weblogic.Deployer is not running on the same machine as the administration server and that the source path should be passed through unchanged because it represents the path on the remote server.
source	Specifies the location of the archive, file or directory to be deployed. Use this option to set the application Path. The source option should reference the root directory or archive being deployed. If you are using it with the upload command, the source path is relative to the current directory. Otherwise, it is relative to the administration server root directory—the directory where the config.xml file resides.
stage	Indicates that application needs to be copied into the target servers staging area before deployment. Defaults: nostage for admin server, and stage for managed server targets. Sets the stagingMethod attribute on the application when it is created so that the application will always be staged. This value overrides the stagingMethod attribute on any targeted servers.
targets	Displays a comma-separated list of the targeted server and/or cluster names (<server 1>,...<component>@<server N>). Each target may be qualified with a J2EE component name. This enables different components of the archive to deployed on different servers. Default: For an application which is currently deployed, the default is all current targets. For a new application, it is deployed to the administration server, by default.
timeout	Seconds. Specifies the maximum time in seconds to wait for the completion of the deployment task. When the time expires, weblogic.Deployer prints out the current status of the deployment and exits.
user	User name.
userconfigfile	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 -userconfig option, you must first generate the file using the weblogic.Admin STOREUSERCONFIG command.
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 -userconfigfilefile option). Before specifying the -userkeyfile option, you must first generate the key file using the weblogic.Admin STOREUSERCONFIG command.
verbose	Displays additional progress messages.

Example Uses of the weblogic.Deployer Utility

Below are example usages of the weblogic.Deployer utility.

Deploying a New Application

java weblogic.Deployer -adminurl http://admin:7001 -name app -source /myapp/app.ear -targets server1,server2 -activate

Deploying a New Application to a Cluster

java weblogic.Deployer -adminurl http://admin:7001 -name app -source /myapp/app.ear -targets cluster1 -activate -enforceClusterConstraints

Redeploying an Entire Application

java weblogic.Deployer -source /myapp/app.ear -adminurl http://admin:7001 -name app -activate

Notes: Ensure that you specify the -source option or provide the list of updated files. Without this, the operation will have no effect as the system will assume that nothing has been changed in the application.

When redeploying a Web Application, the system defaults to deploying the application on the Administration Server. To change the settings, use the -source and -targets options.

Deploying a Module Newly Added to an EAR

If you have added the module newmodule.war to the deployed application myapp.ear and updated the module in the application.xml file, you can deploy newmodule.war in myapp.ear using the following:

java weblogic.Deployer -username myname -password mypassword -name myapp.ear -activate -targets newmodule.war@myserver -source /myapp/myapp.ear

Note that this command will deploy the new module without redeploying the other modules in the application.

Redeploying Part of an Exploded Application, or Refreshing

java weblogic.Deployer -adminurl http://admin:7001 -name app  -activate jsps/login.jsp

where jsps is a directory in the top level of the exploded web application. Note that partial redeployment is only supported on exploded WAR files. The path is relative to the root of the application as originally deployed. For example, if you modified the login.jsp file in a working directory, you would need to first copy the updated file into the appropriate source directory of the exploded application before entering the weblogic.Deployer command.

Deactivating an Application on All Active Targets, Making It Unavailable

java weblogic.Deployer -adminurl http://admin:7001 -name app  -deactivate

Reactivating a Deactivated Application

 java weblogic.Deployer -adminurl http://7001 -name app -activate

Removing an Application from All Targeted Servers

java weblogic.Deployer -adminurl http://admin:7001 -name app -targets server -remove

Cancelling a Deployment Task

java weblogic.Deployer -adminurl http://admin:7001 -cancel -id tag

Listing All Deployment Tasks

java weblogic.Deployer -adminurl http://admin:7001 -list

Deploying or Redeploying an Application to a Single Server

java weblogic.Deployer -activate -name ArchivedEarJar -source C:/MyApps/JarEar.ear -target server1

Deploying an Application to an Additional Server

java weblogic.Deployer -activate -name ArchivedEarJar -target server2

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:

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 Administration Guide for more information about wlserver and wlconfig.

Note: The WebLogic Server Ant tasks are incompatible with Ant versions prior to 1.5. Also, if you use a version of Ant that is not included with WebLogic Server, you must specify the wldeploy task definition in your build.xml file, as described in Basic Steps for Using wldeploy.

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 Platform 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="activate"
      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

Table 5-4 Attributes of the wldeploy Ant Task

Attribute	Description	Data Type	Required?
action	The deployment action to perform. Valid values are activate, deactivate, remove, cancel, list and unprepare.	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.	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, you must first generate the file using the weblogic.Admin STOREUSERCONFIG command as described in STOREUSERCONFIG in the WebLogic Server 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, you must first generate the key file using the weblogic.Admin STOREUSERCONFIG command.	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 Server Administration Console

This section discusses deployment tasks performed through the Administration Console. The Console supports the same functionality as the weblogic.Deployer utility. It allows deployers to submit new or updated applications and to query the status and remove pending deployments.

Configuring J2EE Applications for Deployment Using the Administration Console

To configure a J2EE Application using the WebLogic Server Administration Console:

Start the WebLogic Server Administration Console.
Select the Domain in which you will be working.
In the left pane of the Console, click Deployments.
In the left pane of the Console, click Applications. A table is displayed in the right pane of the Console showing all the deployed J2EE Applications.
Select the Configure a new Application option.
Locate the archive file (WAR, EAR, RAR, JAR) to configure.
Note: You can also configure an exploded application or component directory. Note that WebLogic Server deploys all components it finds in and below the specified directory.
Click [select] to the left of a directory or file to choose it and proceed to the next step.
Select a Target Server from among Available Servers.
Enter a name for the Application in the provided field.
Click Configure and Deploy. The Console will display the Deploy panel, which lists deployment status and deployment activities for the J2EE Application.
Using the available tabs, enter the following information:
- Configuration—Edit the staging mode and enter the deployment order.
- Targets—Indicate the Targets-Server for this configured J2EE Application by moving the server from the Available list to the Chosen list.
Note: If you do not select any targets, the application will just be configured and not deployed. You can modify and deploy this later by accessing it in the mydomain/applications directory.
- Deploy/Undeploy—Deploy the J2EE Application to all or selected targets or undeploy it from all or selected targets; undeploy the J2EE Application. Deploy/Undeploy are toggle options.
- Monitoring—Enable session monitoring for the J2EE Application.
- Notes—Enter notes related to the J2EE Application.

Deploying J2EE Applications with the Administration Console

To deploy a J2EE application using the WebLogic Server Administration Console:

Expand the Deployments node in the left pane.
Right-click on the Applications node.
Select Configure a New Application.
Locate the archive (WAR, EAR, RAR, JAR) or the directory containing the exploded application to configure.
Click [select] to the left of a directory or file to choose it and proceed to the next step. If you specify a directory, WebLogic Server will deploy all components it finds in and below the specified directory.
Select a Target Server from among Available Servers.
Enter a name for the J2EE Application in the provided field.
Click Configure and Deploy. The Console will display the Deploy panel, which lists deployment status and deployment activities for the J2EE Application.
Use the Deploy button to deploy the J2EE Application to all or selected targets or undeploy it from all or selected targets.
Test your J2EE Application by accessing a resource through a Web browser. Access resources with a URL constructed as follows:

http://myServer:myPort/myApp/resource

Where:
- myServer is the name of the machine hosting WebLogic Server.
- myPort is the port number where WebLogic Server is listening for requests.
- myApp is the name of the J2EE Application archive file (myApp.ear, for instance) or the name of a directory containing the J2EE Application.
- resource is the name of a resource such as a JSP, HTTP servlet, or HTML page.

Viewing Deployed Components with the Administration Console

To view a deployed component in the Administration Console:

In the Administration Console under Deployments, select the <component> in the left panel.
View a list of deployed components in the Deployments table in the right pane.

Undeploying Components with the Administration Console

To undeploy a deployed component from the WebLogic Server Administration Console:

In the Administration Console under Deployments, select the component in the left panel.
In the component Deployments table, select the component to undeploy.
Click Apply.

Undeploying a component does not remove the <component> name from WebLogic Server. The component remains undeployed for the duration of the Server session, as long as you do not change it once it has been undeployed. You cannot re-use the deployment name with the deploy argument until you reboot the server. You can re-use the deployment name to update the deployment, as described in the following section.

Updating Applications with the Administration Console

To update a deployed J2EE application:

In the Console, click Deployments.
Click the Applications option.
In the displayed table, click the name of the application you wish to update.
Update the Application Name and Deployed status as needed.
Note: An application becomes unavailable to clients during redeployment. For this reason, redeployment is not recommended for use in a production environment.
Click Apply.

To add a module to a deployed application and deploy the added module:

Add the module by redeploying the application, using steps 1-5 above.
Click the module name in the table in the Deployments >Applications tab.
Select the Targets tab.
Move the desired server from the Available area to the Chosen area, and click Apply.

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 WebLogic Builder.

Auto-Deployment

Auto-deployment is a method for quickly deploying an application on the administration server. It is recommended that this method be used only in a single-server development environment for testing an application. Use of auto-deployment in a production environment or for deployment of components on managed servers is not recommended.

If auto-deployment is enabled, when an application is copied into the \applications directory of the administration server, the administration server detects the presence of the new application and deploys it automatically (if the administration server is running). If WebLogic Server is not running when you copy the application to the \applications directory, the application is deployed the next time the WebLogic Server is started. Auto-deployment deploys only to the administration server

Note: Due to the strict file locking limitations of Windows NT, if your applications are exploded, all the components within your applications must also be exploded. In other words, WebLogic Server cannot support a JAR file within an exploded application or component.

Enabling and Disabling Auto-Deployment

You can run WebLogic Server in two different modes: development and production. You use development mode to test your applications. Once they are ready for a production environment, you deploy your applications on a server that is started in production mode.

Development mode enables a WebLogic Server to automatically deploy and update applications that are in the domain_name/applications directory (where domain_name is the name of a WebLogic Server domain). In other words, development mode lets you use auto-deploy.

Production mode disables the auto-deployment feature. Instead, you must use the WebLogic Server Administration Console or the weblogic.Deployer tool.

By default, a WebLogic Server runs in development mode. To specify the mode for a server, do one of the following:

If you use the startWebLogic startup script, edit the script and set the STARTMODE variable as follows:

STARTMODE = false enables deployment mode

STARTMODE = true enables production mode

If you start a server entering the weblogic.Server command directly on the command line, use the -Dweblogic.ProductionModeEnabled option as follows:

-Dweblogic.ProductionModeEnabled=false enables deployment mode

-Dweblogic.ProductionModeEnabled=true enables production mode

For more information on starting WebLogic Server in development and production modes, refer to "Starting and Stopping WebLogic Servers."

Auto-Deploying Applications

This is a convenience feature for deploying applications during development. It allows deploying of applications or individual J2EE modules to the administration server just by copying the deployment into a predefined auto-deployment directory. This directory is located under the domain directory, e.g., mydomain/applications.

Undeploying and Redeploying Archived Applications

An application or its component that was auto-deployed can be dynamically redeployed while the server is running. To dynamically redeploy a JAR, WAR or EAR file, simply copy the new version of the file over the existing file in the \applications directory.

This feature is useful for developers who can simply add the copy to the \applications directory as the last step in their makefile, and the server will then be updated.

If you delete the application from the \applications directory, the application will be undeployed and removed from the configuration.

Redeploying Applications in Exploded Format

You can also dynamically redeploy applications or components that have been auto-deployed in exploded format. When an application has been deployed in exploded format, the administration server periodically looks for a file named REDEPLOY in the exploded application directory. If the timestamp on this file changes, the administration server redeploys the exploded directory.

If you want to update files in an exploded application directory, do the following:

When you first deploy the exploded application, create an empty file named REDEPLOY, and place it in the WEB-INF or META-INF directory, depending on the application type you are deploying:

An exploded application contains a META-INF top-level directory; this contains the application.xml file.

An exploded Web application contains a WEB-INF top-level directory; this contains the web.xml file.

An exploded EJB application contains a META-INF F top-level directory; this contains the ejb-jar.xml file.

An exploded connector contains a META-INF top-level directory; this contains the ra.xml file.

Note: The REDEPLOY file works only for an entire deployed application or a deployed standalone module. If you have deployed an exploded Enterprise Application, the REDEPLOY file controls redeployment for the entire application—not for individual modules (for example, a Web Application) within the Enterprise Application. If you deploy a Web Application by itself as an exploded archive directory, the REDEPLOY file controls redeployment for the entire Web Application.
To update the exploded application, copy the updated files over the existing files in that directory.
After copying the new files, modify the REDEPLOY file in the exploded directory to alter its timestamp.

When the administration server detects the changed timestamp, it redeploys the contents of the exploded directory.

Deployment Management API

A deployment task is initiated through a DeployerRuntimeMBean—a singleton (an object for which only one instance exists) that resides on a WebLogic 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.

Best Practices for Application Deployment

The following are some best practices for deploying applications.

Single Server Development

In an iterative development environment, it is most efficient to maintain all files in an exploded form and deploy the application directly from its source location.

If you are working in a single server environment (deploying only to the administration server), you can use directory-based auto deployment. In other words, you can simply place the exploded application in the mydomain/applications directory to deploy it. For more information, see Auto-Deployment in this document.

Testing Changes to Web Applications or Web Services

You can change JSPs or any static data files in the application under the mydomain/applications directory, and view your changes in the application.
You can also directly compile updated servlet classes into a web application under the mydomain/applications directory (for instance, mydomain/applications/exploded_web_app_dir/WEB-INF/classes). The new classes are incorporated in the Web application; no additional steps are required.
To incorporate changes made to the Web application deployment descriptors, modify the WEB-INF/REDEPLOY file in the mydomain/applications directory, so that the auto deployer detects the change. This redeploys the Web application.

Testing Changes to EJBs and Resource Adapters

To incorporate changes made to the EJB or Resource Adapter deployment descriptors, modify the META-INF/REDEPLOY file in the mydomain/applications directory, so that the auto deployer detects the change. This redeploys the EJB or Resource Adapter.

Note: If the EJB is part of an enterprise application, the entire application is redeployed.

Multiple Server Development

If you are working in a multiple server environment, it is recommended that you use the weblogic.Deployer tool to deploy applications.

Testing Changes in a Multiple Server Environment

If you have made any changes to application files, you must communicate these changes to the server using the weblogic.Deployer tool. This allows the changes to be incorporated into the deployed application.

The following steps illustrate how you communicate changes made to a Web application to the server. The steps are identical for any type of application. However, you should note that if an EJB is part of an enterprise application, the entire application and application components are redeployed.

Deploy the Web application using the Administration Console or as follows:

java weblogic.Deployer -adminurl http://adminAddr:7001 -name webapp -activate -source /myapp/webapp -targets managedserver1,managedserver2

Make needed changes to the JSP: /myapp/webapp/jsps/login.jsp

Apply the changes as follows:

java weblogic.Deployer -adminurl http://adminAddr:7001 -name webapp -activate jsps/login.jsp

In the above example, login.jsp is distributed and incorporated to all servers where the Web application is deployed.

File Structures for Exploded Applications

For more information about packaging deployable units, see WebLogic Server Application Packaging and Classloading.

If a directory contains multiple modules but no overall application descriptor file, each module should be contained in its own directory and have its own descriptor files. In other words, in non-archived applications each module must be independent of the other modules, just as in an archive.

sourceDirectory\

               \Module1
                     WEB-INF\
                             web.xml
                             Module1FilesDir

               \Module2
                     META-INF\
                             ejb-jar.xml 
                             Module2FilesDir

For exploded non-EAR deployments, the source directory should always be either A or B:

A.

 \Module1
         WEB-INF\
                web.xml
                Module1FilesDir

 \Module1
         WEB-INF\
                web.xml
                Module1FilesDir

 \Module2
         META-INF\
                ejb-jar.xml 
                Module2FilesDir 
 \Module3
         META-INF\
                ra.xml 
                Module3FilesDir

The following directory structures are not supported and do not make sense:

sourceDirectory/

       META-INF/ejb-jar.xml

       WEB-INF/web.xml

       webfiles/

       ejbfiles/

moduledir/

       WEB-INF/web.xml

       webfiles

       ejb.jar

moduledir/

       WEB-INF/web.xml

       web1files

       web2/WEB-INF/web.xml

       web2/webfiles

Staging Mode

Use the system defaults of -nostage for administration server and -stage for managed servers, unless:

You want to use third-party solutions to manage file copying and distribution from the administration server to the managed server machines.
You want to use a shared file system for sharing the source of an application between different servers in a domain.

Auto-Deployment

You should only use auto-deployment in development setups for single server deployments.

Exploded Enterprise Applications

Exploded deployments with multiple modules should always have an application descriptor defined in META-INF/application.xml.

Partial Redeployment

If you redeploy a module or file to which other modules in the application have references, you must also redeploy the referencing modules.

Sharing Classes between Components That Are Part of an Enterprise Application

To share classes between components that are part of an Enterprise Application, use the MANIFEST classpath. A JAR utility containing the shared classes is packed in the EAR next to the other component archives. Each component needing to use these classes creates a Class-Path entry in a file named META-INF/MANIFEST.MF within the component's archive. This scheme is part of the J2EE standard and should be used if you require portability between application servers.

For more information, refer to Manifest Class-Path.

Using WebLogic Server 6.x Deployment Protocol

By default, the two-phase deployment protocol is used for deploying new applications by all available deployment tools. The current administration server still supports the WebLogic Server 6.x deployment protocol, and this protocol is used when:

Configured applications do not specify the two-phase deployment protocol by setting ApplicationMBean.TwoPhase=false.
The application contains multiple modules and is not an EAR.

See Deploying Applications in the WebLogic Server 6.1 Administration Guide.

Note: When using the WebLogic Server 6.x deployment protocol, a server instance creates a .wlnotdelete directory to manage the deployment process. You should not delete this directory or its contents.

Updating to Two Phase Deployment

To configure an application that uses 6.x protocol to start using the two-phase protocol, remove the application from the domain—removing its configuration—and then re-activate the application, as follows:

Remove the application using weblogic.Deployer. Enter a command in the following form:

java weblogic.Deployer -adminurl http://admin:7001 -name app -targets server -remove

Reactivate the application using weblogic.Deployer. Enter a command in the following form:

java weblogic.Deployer -activate -name ArchivedEarJar -source C:/MyApps/JarEar.ear -target server1

The application will redeploy using the new protocol.

Additional Deployment Documentation

For more information on WebLogic Server deployment, see the following documentation:

Document	Deployment Topics
WebLogic Builder	How to use WebLogic Builder to edit and generate XML deployment descriptor files for J2EE applications and their components.
Administration Console Online Help	How to use the Administration Console for deployment tasks.
Understanding Cluster Configuration and Application Deployment	How to deploy to clustered servers.
Programming WebLogic EJBs	How to deploy WebLogic Server EJBs.
Programming WebLogic J2EE Connectors	How to deploy WebLogic Server J2EE Connectors.
Assembling and Configuring Web Applications	How to deploy Weblogic Server Web Applications.
Programming WebLogic JSP	How to deploy applets from JSP.
WebLogic Server Application Packaging and Classloading	How to package WebLogic Server application components.