Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Deployment

# Performing Deployment Operations

The following sections describe how to implement deployment operations for a WebLogic deployment API constructed deployment tool.

- Application Deployment
- Deployment Factories
- DeploymentManager Behaviors
- Server Connectivity
- Deployment Processing
- Production Redeployment
- Progress Reporting
- Module Types
- Target Objects
- Examples

# Application Deployment

Up to this point, we have described how to create elaborate configurations but have not touched only actually putting those configurations to a practical use. Application Deployment, the fifth phase of deployment, uses any information setup by configuration operations to handle the distribution of the application and plan to the administration server for server-side processing and application startup. This chapter describes all of the necessary components to deploy and control an application to the WebLogic Server environment.

# Deployment Factories

A deployer tool must allocate a DeploymentManager from a DeploymentFactory, which is registered with the DeploymentFactoryManager class, in order to perform deployment operations. In addition to configuration (described in Overview of the Configuration Process), the DeploymentManager is responsible for establishing a connection to a J2EE server. The DeploymentManager implementation is accessed via a DeploymentFactory.

A deployer tool is responsible for instantiating and registering any DeploymentFactory objects it uses. The WebLogic factory is advertised via the manifest file in the wldeploy.jar archive. The manifest contains entries defining the fully-qualified class names of the factories, separated by whitespace. For example:

>     MANIFEST.MF:

>         Manifest-version: 1.0

>         Implementation-Vendor: BEA Systems

>          Implementation-Title: WebLogic Server 9.0 Mon Nov 11 08:16:47 PST 2002 221755

>         Implementation-Version: 9.0.0.0

>         J2EE-DeploymentFactory-Implementation-Class:

>         weblogic.deploy.spi.factories.DeploymentFactoryImpl

A deployer tool can define any mechanism for managing the SPI plug-ins it recognizes. For simplicity's sake, assume the tool requires that all SPI plug-ins reside in some fixed location, and that they are also in its classpath. Upon startup, the tool would register the plug-ins as shown in the example.

The standard `DeploymentFactory` interface is extended by weblogic.deploy.api.WebLogicDeploymentFactory. The additional methods provided in the extension are:

- String[] getUris(): returns an array of URI's that are recognized by `getDeploymentManager`. The first URI in the array is guaranteed to be the default `DeploymentManager` URI, `deployer:WebLogic`. Only published URI's are returned in this array.
- String createUri(String protocol, String host, String port): returns a usable URI based on the arguments.

# DeploymentManager Behaviors

Only one DeploymentManager implementation is provided. Depending on the URI specified when allocating the `DeploymentManager`, it will take on the following characteristics:

- deployer:WebLogic: The `DeploymentManager` assumes it is running locally on an administration server. Thus any files referenced during the deployment session are assumed to be local to the administration server.
- deployer:WebLogic.remote: The `DeploymentManager` will assume it is running remotely to the WebLogic administration server, thus any files referenced during the deployment session are not assumed to be local to the administration server. i.e. a distribute operation will include uploading the application files to the administration server.
- deployer:WebLogic.authenticated: This is an internal, unpublished URI, usable by applications such as a console servlet that is already authenticated and has access to the domain management information. The `DeploymentManager` will assume it is running locally on a WebLogic administration server. Thus any files referenced during the deployment session are assumed to be local to the administration server.

# Server Connectivity

A deployment tool allocates a `DeploymentManager` from a registered `DeplomentFactory` (see above). `DeploymentManagers` can be either connected or disconnected. Connected `DeploymentManagers` imply a connection to a WebLogic administration server. This connection is maintained until it is explicitly disconnected or the connection is lost. If the connection is lost, the `DeploymentManager` will revert to a disconnected state.

Explicitly disconnecting a `DeploymentManager` is accomplished via the `DeploymentManager.release` method. There is no corresponding method for reconnecting the `DeploymentManager`. Instead the deployer tool must allocate a new `DeploymentManager`. This should not affect any configuration information being maintained within the tool through a `DeploymentConfiguration` object.

`DeploymentManagers` are identified by an opaque URI. All `DeploymentManagers` for WebLogic Server have the URI scheme, `deployer:WebLogic``<.type>`. The `DeploymentFactory.getDeploymentManager` method takes a URI, userid and password as arguments. In this case the URI must also include the host and port for the admin server, e.g. `deployer:WebLogic:``localhost:7001`. When obtaining a disconnected `DeploymentManager`, only the URI is necessary because no actual connection to a server is made. In this case, the URI can simply be `deployer:WebLogic`, although extending the URI with the host and port is allowed.

The userid and password arguments are ignored if the deployer tool uses a pre-authenticated `DeploymentManager`; The factory presumes that the user has already been authenticated.

The URI of any `DeploymentManager` implementation should be accessed using the `DeploymentFactory.getUris()` method. `getUris` is an extension of `DeploymenFactory`.

The behavior of the `DeploymentManager` operations is guided by the URI specified when it is allocated from the factory. These behaviors apply to relevant operations supported by the `DeploymentManager`. They include:

- File Upload: determines whether files are uploaded to the admin server. This functionality is automatically enabled for the remote `DeploymentManagers`
- Authentication Required:

These behaviors also can be explicitly enabled using the WebLogicDeploymentManager method `enableFileUploads()`.

# Deployment Processing

Most of the functional components of a DeploymentManager are defined in the J2EE Deployment API specification. The specification does not describe a `DeploymentManager` that is sufficient to support the needs of WebLogic Server customers, hence a number of extensions were introduced. These are documented in the Javadocs for weblogic.deploy.api.spi.WebLogicDeploymentManager. The relationship between the SPI operations and WebLogic Server is provided here.

The intent is not to change the programming model defined by the J2EE deployment API specification, but rather to extend the DeploymentManager interface (`DeploymentManager`) with the capabilities required and expected by existing WebLogic Server-based deployment tools.

The JSR-88 programming model revolves around employing `TargetModuleID` objects (`TargetModuleIDs`) and `ProgressObject` objects. In general, the target modules are specified by a list of `TargetModuleIDs` which are roughly equivalent to deployable (root modules) and (sub)module level mbeans. The `DeploymentManager` applies the `TargetModuleIDs` to its deployment operations (start, stop, and so on) and tracks their progress. The deployer tool queries progress via a `ProgressObject` returned for each operation. When the `ProgressObject` indicates the operation is completed or failed, the operation is done.

The following sections describe the different `DeploymentManager` operations and their extensions. Full descriptions are provided in the Javadocs. This section serves as a general overview. The extensions cover the following features:

- General usability/convenience
- Side-by-side version support
- module level targeting
- partial redeployment
- administration (test) mode applications

## DeploymentOptions

The WebLogic Server allows for a `DeploymentOptions` argument (`weblogic.deploy.api.spi.DeploymentOptions`), which supports the overriding of certain deployment behaviors. The argument may be null, which provides for standard behaviors. Some of the options supported in this release are:

- administration (test) mode
- Retirement Policy
- Staging

See the DeploymentOptions Javadoc for a full list of options.

## Distribution

The distribution of new applications results in the application archive and plan being staged on all targets, and the application being configured into the domain. Redistribution will honor the staging mode already configured for the application.

The standard distribute operations do not allow for version naming, leaving this to be generated by the system. `WebLogicDeploymentManager` extends the standard with a distribute operation that allows the user to specify a version name to associate with the new application.

The `ProgressObject` returned from a distribute provides a list of `TargetModuleIDs` representing the application as it exists on the target servers. The targets used in the distribute are any of the supported targets. The `TargetModuleID` will represent the application's module availability on each target.

For new applications, the resulting `TargetModuleIDs` represent the top level `AppDeploymentMBean` objects. The `TargetModuleIDs` will not have child `TargetModuleIDs` based on the modules and submodules in the application, since the underlying `MBeans` would only represent the root module. For pre-existing applications, the `TargetModuleIDs` are based on the `DeployableMBeans` and any `AppDeploymentMBean` and `SubAppDeploymentMBean` in the configuration.

When using the `distribute(Target[],InputStream,InputStream)` method to distribute, the archive and plan represented by the input streams will be copied from the streams into a temp area prior to deployment. It is not recommended to use this distribute method for performance reasons.

## Application Start

The standard start operation only supports root modules; implying only entire applications can be started. Consider the following configuration.

>     <AppDeployment Name="myapp">

>      <SubDeployment Name="webapp1", Targets="serverx"/>

>      <SubDeployment Name="webapp2", Targets="serverx"/>

>     </AppDeployment>

The `TargetModuleID` returned from `getAvailableModules(``ModuleType.EAR``)` would look like this:

>     myapp on serverx (implied)

>      webapp1 on serverx

>      webapp2 on serverx

So `start(``tmid``)` would start `webapp1` and `webapp2` on `serverx`.

To just start `webapp1`, module level control is required. This is achievable as follows by manually creating a `TargetModuleID` hierarchy.

>     WebLogicTargetModuleID root = dm.createTargetModuleID("myapp",ModuleType.EAR,getTarget(serverx));

>     WebLogicTargetModuleID web = dm.createTargetModuleID(root,"webapp1",ModuleType.WAR);

>     dm.start(new TargetModuleID[]{web});

This approach uses the `TargetModuleID` creation extension to manually create an explicit `TargetModuleID` hierarchy. In this case the created `TargetModuleID` would look like

>     myapp on serverx (implied)

>      webapp1 on serverx

The `start` operation does not modify the application configuration. Version support is built into the `TargetModuleIDs`, allowing the user to start a specific version of an application. Applications may be started in normal or administration (test) mode.

## Application Deploy

The `deploy` operation combines a `distribute` and `start` operation, and is provided as a convenience. Web Applications may be deployed in normal or administration (test) mode. Application staging can also be specified via the `DeploymentOptions` argument on deploy. The deploy operations use `TargetModuleIDs` instead of `Targets` for targeting, thus allowing for module level configuration.

The deploy operation may change the application configuration based on the `TargetModuleIDs` provided.

## Application Stop

The standard `stop` operation only supports root modules; implying only entire applications can be stopped. See the Application Start discussion for more details on module level control.

The `stop` operation does not modify the application configuration.

Version support is built into the `TargetModuleIDs`, allowing the user to stop a specific version of an application.

## Undeployment

The standard undeploy operation removes an application from the configuration, as specified by the `TargetModuleIDs`. Individual modules can be undeployed. The result is that the application remains on the target, but certain modules are not actually configured to run on it. See the Application Start section for more detail on module level control.

The `WebLogicDeploymentManager` extends undeploy in support of removing files from a distribution. This is a form of in-place redeployment that is only supported in web applications, and is intended to allow for removal of static pages and the like.

Version support is built into the `TargetModuleIDs`, allowing the user to undeploy a specific version of an application.

# Production Redeployment

Standard redeployment support only applies to entire applications and employs side-by-side versioning to ensure uninterrupted session management. The `WebLogicDeploymentManager` extends the `redeploy()` method as follows:

- redeploying individual modules in an application. This implies an in-place redeploy (no new version). The version information in the new application must be the same as the old application, but with a different value (for example 1.0, 1.1, and so on.). Module targeting must be specified.
- Specifying a retirement policy for an old application.
- Partial redeployment - this involves adding or replacing specific files in an existing deployment. This is an in-place redeployment.
- Redeploying applications in administration (test) mode.
- updating configuration - the redeployment of a deployment plan.

Version support is provided via arguments in the above operations. The version, if relevant, is specified in the `TargetModuleID`.

## Retirement Policy

When a new version of an application is redeployed, the old version should eventually be retired and undeployed. There are 2 policies for retiring old versions of applications:

1. (Default) old version is retired when new version is active and old version finishes its in-flight operations.

2. The old version is retired when new version is active, retiring the old after some specified time limit of the new version being active.

Note that the old version will not be retired if the new version is in administration (test) mode.

## Module Targeting

`DeploymentManager'`s will honor the JSR-88 specification and restrict operations to root modules. Module level control is provided by manually constructing a module specific `TargetModuleID` hierarchy via `WebLogicDeploymentManager.createTargetModuleID`

## Version Support

Side-by-side versioning is used to provide retirement extensions, as suggested in the JSR-88 redeployment specification. This ensures that an application can be redeployed with no interruption in service to its current clients. Details on deploying side-by-side versions can be found in the Redeployment Strategies documentation. Briefly, an archive manifest can specify the WebLogic Server application version. The deployment plan also supports a version identifier. The combination of these 2 version identifiers is used internally to distinguish between versions of applications, and may also be used by developers and administrators to assist in version control.

This provides the basis for production redeployment as it is implemented for the WebLogic Server Deployment Service. Please refer to the Redeployment Strategies documentation for more information.

## Administration (Test) Mode

A web application may be started in normal or administration (test) mode. Normal mode indicates the web app is fully accessible to clients. Administration (test) mode indicates the application only listens for requests via the admin channel. Administration (test) mode is specified via a DeploymentOptions argument on the WebLogic Server extensions for `start`, `deploy` and `redeploy`. See the DeploymentOptions Javadoc for more information.

# Progress Reporting

ProgressObjects are the interface for the deployment state in the SPI. These objects are associated with DeploymentTaskRuntimeMBeans. ProgressObjects support the cancel operation but not the stop operation.

ProgessObjects are associated with one or more TargetModuleIDs, each of which represents an application and its association with a particular target. For any ProgressObject, its associated TargetModuleIDs represent the application that is being monitored.

The ProgressObject maintains a live connection with the deployment framework, allowing it to provide the tools with up-to-date deployment status. Once this status goes to completed, failed or released, the tools should not expect any further changes. Deployment state transitions from running to completed or failed only after all TargetModuleIDs involved have completed their individual deployments. The resulting state is 'completed' only if all TargetModuleIDs were successfully deployed.

The `released' state means that the DeploymentManager was disconnected during the deployment. This may be due to a manual release, a network outage, or similar communication failures.

The following code sample shows how a ProgressObject can be used to wait for a deployment to complete:

>     package weblogic.deployer.tools;

>     import javax.enterprise.deploy.shared.*;

>     import javax.enterprise.deploy.spi.*;

>     import javax.enterprise.deploy.spi.status.*;

>     /**

>      * Example of class that waits for the completion of a deployment

>      * using ProgressEvent's.

>      */

>     public class ProgressExample implements ProgressListener {

>      private boolean failed = false;

>      private DeploymentManager dm;

>      private TargetModuleID[] tmids;

>      public void main(String[] args) {

>         // set up DeploymentManager, TargetModuleIDs, etc

>         try {

>           wait(dm.start(tmids));

>     } catch (IllegalStateException ise) {

>           //... dm not connected

>     }

>         if (failed) System.out.println("oh no!");

>     }

>      void wait(ProgressObject po) {

>         ProgressHandler ph = new ProgressHandler();

>         if (!po.getDeploymentStatus().isRunning()) {

>           failed = po.getDeploymentStatus().isFailed();

>           return;

>     }

>         po.addProgressListener(ph);

>         ph.start();

>         while (ph.getCompletionState() == null) {

>           try {

>             ph.join();

>     } catch (InterruptedException ie) {

>             if (!ph.isAlive()) break;

>     }

>     }

>         StateType s = ph.getCompletionState();

>         failed = (s == null ||

>                   s.getValue() == StateType.FAILED.getValue());

>         po.removeProgressListener(ph);

>     }

>      class ProgressHandler extends Thread implements ProgressListener {

>         boolean progressDone = false;

>         StateType finalState = null;

>         public void run(){

>           while(!progressDone){

>             Thread.currentThread().yield();

>     }

>     }

>         public void handleProgressEvent(ProgressEvent event){

>           DeploymentStatus ds = event.getDeploymentStatus();

>           if (ds.getState().getValue() != StateType.RUNNING.getValue()) {

>             progressDone = true;

>             finalState = ds.getState();

>     }

>     }

>         public StateType getCompletionState(){

>           return finalState;

>     }

>     }

>     }

# Module Types

The standard modules types are defined by javax.enterprise.deploy.shared.ModuleType. This is extended to support WebLogic Server-specific module types: JMS, JDBC, INTERCEPT and CONFIG.

# Target Objects

The J2EE Deployment API specification's definition of a target does not include any notion of its type. WebLogic Server recognizes types - servers, clusters, JMS servers and virtual hosts - as valid targets for deployment. These concepts are introduced into the API via the weblogic.deploy.api.spi.WebLogicTarget and weblogic.deploy.api.spi.WebLogicTargetType classes. WebLogicTargetType follows the form of the classes in the javax.enterprise.deploy.shared. It enumerates the known target types.

WebLogicTarget and WebLogicTargetType are defined in more detail in the Javadocs. WebLogicTarget extends javax.enterprise.deploy.spi.Target.

## TargetModuleID Objects

The TargetModuleID objects uniquely identify a module and a target it is associated with. TargetModuleIDs are the objects that specify where modules are to be started and stopped. The object name used to identify the TargetModuleID is of the form:

>     Application=parent-name,Name=configured-name,Target=target-name,TWebLogicTargetType=target-type

where

- parent-name is the name of the ear this module is part of.
- configured-name is the name used in the WebLogic Server configuration for this application or module
- target-name is the server, cluster or virtual host where there module is targeted
- target-type is the description of the target derived from Target.getDescription.

TargetModuleID.toString() will return this object name.

## WebLogic Server TargetModuleID Extensions

TargetModuleID is extended by weblogic.deploy.api.spi.WebLogicTargetModuleID. This class provides the following additional functionality:

- `getServers` - servers associated with the `TargetModuleID`'s target.
- `isOnCluster` - whether target is a cluster
- `isOnServer` - whether target is a server
- `isOnHost` - whether target is a virtual host
- `isOnJMSServer` - whether target is a JMS server
- `getVersion` - the version name
- `createTargetModuleID` - factory for creating module specific targeting

WebLogicTargetModuleID is defined in more detail in the Javadocs.

The WebLogicDeploymentManager is also extended with convenience methods that simplify working with TargetModuleIDs. They are:

- `filter` - returns a list of TargetModuleIDs that match on application, module, and version
- `getModules` - creates TargetModuleIDs based on an `AppDeploymentMBean`

`TargetModuleIDs` have a hierarchical relationship based on the application upon which they are based. The root `TargetModuleID` of an application represents an EAR module or a standalone module. Child `TargetModuleIDs` are modules that are defined by the root module's descriptor. For EARs, these are the modules identified in the `application.xml` descriptor for the EAR. JMS modules have a notion of sub-module, hence any JMS module may have child `TargetModuleIDs` as dictated by the JMS deployment descriptor. These may be children of an embedded module or the root module. Therefore, there can be 3 levels of `TargetModuleIDs` for an application.

`TargetModuleIDs` are generally acquired via some deployment operation, or one of the `DeploymentManager.get*Modules()` methods. These will only provide `TargetModuleIDs` based on existing configuration. In certain scenarios where more specific targeting is desired than is currently defined in the configuration, the `createTargetModuleID` method is provided. This method will create a root `TargetModuleID` that is specific to a module or submodule within the application. This `TargetModuleID` can then be used in any deployment operation. For operations that include the application archive (e.g. `deploy()`), using one of these `TargetModuleIDs` may result in the application being reconfigured. For example, given the following configuration

>     <AppDeployment Name="myapp", Targets="s1,s2"/>

the application is currently configured for all modules to run on `s1` and `s2`. To provide more specific targeting, a deployment tool can do the following:

>     Target s1 = find("s1",dm.getTargets());

>     // find() is not part of this api

>     WebLogicTargetModuleID root = dm.createTargetModuleID("myapp",ModuleType.EAR,s1);

>     WebLogicTargetModuleID web = dm.createTargetModuleID(root,"webapp1",ModuleType.WAR);

>     dm.deploy(new TargetModuleID[]{web},myapp,myplan,null);

`myapp` is reconfigured and `webapp` is specifically targeted to only run on `s1`. The new configuration is:

>     <AppDeployment Name="myapp", Targets="s1,s2">

>      <SubDeployment Name="webapp", Targets="s1"/>

>     </AppDeployment>

## Extended Module Support

JSR-88 defines a secondary descriptor as additional descriptors that a module can refer to or make use of. These descriptors are linked to the root DConfigBean of a module such that they are visible to a java Beans based tool-- they are child properties of a DConfigBeanRoot object. Secondary descriptors are automatically included in the configuration process for a module.

### Web Services

An EJB or Web App may include a `webservers.xml` descriptor. If present the module will be automatically configured with the WebLogic Server equivalent descriptor for configuring the web services. These are treated as secondary descriptors in JSR-88 terminology. The deployment plan includes these descriptors as part of the module, not as a separate module.

### CMP

CMP support in EJBs is configured via RDBMS descriptors that are identified for CMP beans in the weblogic-ejb-jar.xml descriptor. The RDBMS descriptors support CMP11 and CMP20 currently. Any number of RDBMS descriptors may be included with an EJB module. These descriptors must be provided in the application archive or configuration area (approot/plan). They are not created by the configuration process, but may be modified as with any other descriptor. RDBMS descriptors are treated as secondary descriptors in the deployment plan.

### JDBC

JDBC modules are described by a single deployment descriptor. There is no archive involved. If the module is part of an EAR, the JDBC descriptors are specified in weblogic-application.xml. These are configurable properties. JDBC modules can be deployed to WebLogic servers and clusters. Configuration changes to JDBC descriptors are handled as overrides to the descriptor.

If the JDBC module is part of an EAR its configuration overrides are treated as with secondary descriptors; they are incorporated in the deployment plan as part of the EAR, not as separate modules.

### JMS

JMS modules are described by a single deployment descriptor. There is no archive involved. If part of an EAR the JMS descriptors are specified in weblogic-application.xml. These are configurable properties. JMS modules can be deployed to JMS servers. Configuration changes to JMS descriptors are handled as overrides to the descriptor. JMS descriptors may identify "targetable groups". These groups are treated as sub-modules during deployment.

If the JMS module is part of an EAR its configuration overrides are treated as with secondary descriptors; they are incorporated in the deployment plan as part of the EAR, not as separate modules.

### INTERCEPT

Intercept modules are described by a single deployment descriptor. There is no archive involved. If part of an EAR the Intercept descriptors are specified in weblogic-application.xml. These are configurable properties. Intercept modules can be deployed to WebLogic Server servers and clusters. Configuration changes to Intercept descriptors are handled as overrides to the descriptor.

If the INTERCEPT module is part of an EAR its configuration overrides are treated as with secondary descriptors; they are incorporated in the deployment plan as part of the EAR, not as separate modules.

# Examples

Consider the deployment of a standalone JMS module, one that employs sub-modules. The module is defined by the file, `jms.xml`, which defines sub-modules, `sub1` and `sub2`. The descriptor is fully configured for the environment hence no deployment plan is required, although the scenario described here would be the same if there was a deployment plan.

The tool to deploy this module performs the following steps:

>     // init the jsr88 session. This uses a WLS specific helper class,

>     // which does not employ any WLS extensions

>     DeploymentManager dm = SessionHelper.getDeploymentManager(host,port, user,pword);

>     // get list of all configured targets

>     // The filter method is where the tool might ask the user to select from the

>     // list of all configured targets

>     Target[] targets = filter(dm.getTargets());

>     // the module is distributed to the selected targets.

>     ProgressObject po = dm.distribute(targets,new File("jms.xml"),plan);

>     // when the wait comes back the task is done

>     waitForCompletion(po);

>     // It is assumed here that it worked (there is no exception handling)

>     // the TargetModuleIDs (tmids) returned from the PO correspond to all the

>     // configured app/module mbeans for each target the app was distributed to.

>     // This should include 3 tmids per target: the root module tmid and the

>     // submodules' tmids.

>     TargetModuleID[] tmids = po.getResultTargetModuleIDs();

>     // then to deploy the whole thing everywhere you would do this

>     po = dm.start(tmids);

>     // the result is that all sub-modules would be deployed on all the selected

>     // targets, since they are implicitly targeted wherever the their parent is

>     // targeted

>     // To get sub-module level deployment you need to use WebLogic Server

>     // extensions to create TargetModuleIDs that support module level targeting.

>     // The following deploys the topic "xyz" on a JMS server

>     WebLogicTargetModuleID root = dm.createTargetModuleID(tmids[i].getModuleID(),tmids[i],jmsServer);

>     WebLogicTargetModuleID topic = dm.createTargetModuleID(root,"xyz",WebLogicModuleType.JMS);

>     // now we can take the original list of tmids and let the user select

>     // specific tmids to deploy

>     po = dm.start(topic);