Skip navigation.

eDocs Home > BEA WebLogic Server 9.1 Documentation > Programming WebLogic Deployment > Performing Deployment Operations

Programming WebLogic Deployment

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Performing Deployment Operations

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

 

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:

 

DeploymentManager Behaviors

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

 

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:

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:

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:

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:

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

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:

WebLogicTargetModuleID is defined in more detail in the Javadocs.

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

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);

 

Back to Top Previous Next