Programming WebLogic Deployment

Understanding the WebLogic Deployment API

The following sections describe the structure and functionality of the WebLogic Deployment API:

Overview of the Deployment API

The WebLogic Deployment API implements and extends the J2EE Deployment API standard (JSR-88) interfaces to provide specific deployment functionality for WebLogic Server applications. This document and the WebLogic Deployment API JavaDocs are intended to be used by developers and Independent Software Vendors (ISVs) who want to perform deployment operations programmatically for the WebLogic Server.

Note: WebLogic Server 9.0 deprecates the use of the weblogic.management.deploy API used in earlier releases.

Phases of Deployment

The functionality described here is in support of a deployer tool's ability to effectively configure and deploy applications. The deployment process has the following phases, which a tool may implement and all of which are optional:

1) Application evaluation - this phases inspects and evaluates the application files to determine the structure of the application and content of the standard descriptors embedded in it.

2) Front-end configuration - this phase establishes configuration information based on information embedded within the application. This information may be in the form of WebLogic Server descriptors, defaults, and user provided deployment plans.

3) Deployment configuration - this phase involves a conversation with the user to establish desired configuration and tuning for the specific deployment. This phase resolves previously unresolved elements and allows for overriding existing configuration and/or establishment of environment specific information.

4) Deployment preparation - this phase generates the final deployment plan and performs some level of client-side validation of the application.

5) Application deployment - this phases handles the distribution of the application and plan to the admin server for server-side processing and application startup.

The implementations of these phases are described in the Configuring Applications for Deployment and Performing Deployment Operations chapters that follow this chapter. This chapter introduces the packages necessary to perform these operations and general information about each of them.

J2EE Deployment API Compliance

The WebLogic Deployment API classes and interfaces extend and implement the J2EE Deployment API standard (JSR-88) interfaces, which are described in the javax.enterprise.deploy sub-packages (model, shared, and spi). In addition, the WebLogic Deployment API provides a Tools package with helper classes to perform common deployment tasks easily.

WebLogic supports the "Product Provider" role described in the J2EE Deployment API standard (JSR-88) and thus provides utilities specific to the WebLogic Server environment in addition to extensible components for any J2EE network client. These extended features include:

Support for WebLogic features (enables you to add optional information which only makes sense to WebLogic server. For example, starting in Admin mode, redeploying with versioning, etcetera)
Finer grain control (module level targeting - not part of J2EE Deployment API)
Support of WebLogic module extensions (JMS, JDBC, Interception, Application Specific Configuration[Custom/Config modules]) these are not required by J2EE Deployment API, it is extended for additional configuration.
Remote Operation
Additional Operations

The `Deploy' verb: combines `distribute' and `start'
Partial Redeployment: redeployment/removal of parts of an application
Configuration update: redeployment of a new deployment with only dynamic configuration changes

The SPI Package

As a J2EE product provider, BEA extends the javax SPI package to control how configuration and deployment is done to the WebLogic Server specifically. The core interface for this package is the DeploymentManager, from which all other deployment activities can be initiated, monitored, and controlled.

The WebLogicDeploymentManager interface provides WebLogic Server extensions to the javax.enterprise.deploy.spi.DeploymentManager interface. A WebLogicDeploymentManager object is a stateless interface for the Weblogic Server deployment framework. It provides basic deployment features as well as extended WebLogic Server deployment features such as production redeployment and partial deployment for modules in an Enterprise Application. You generally acquire a WebLogicDeploymentManager object using SessionHelper.getDeploymentManager method from the SessionHelper helper class from the Tools package. This and other ways to obtain a WebLogicDeploymentManager are described in the discussion on Application Evaluation.

weblogic.deploy.api.spi

The weblogic.deploy.api.spi package provides the interfaces required to configure and deploy applications for deployment to WebLogic Server targets. This package enables a deployment tool to represent the WebLogic Server-specific deployment configuration for an Enterprise Application or standalone module.

weblogic.deploy.api.spi includes the WebLogicDeploymentManager interface, as noted above. Deployment tools use this deployment manager to perform all deployment-related operations such as distributing, starting, and stopping applications in WebLogic Server. The WebLogicDeploymentManager provides important extensions to the J2EE DeploymentManager interface to support features such as module-level targeting for Enterprise Application modules, production redeployment, application versioning, application staging modes, and constraints on Administrative access to deployed applications.

The WebLogicDeploymentConfiguration and WebLogicDConfigBean classes in the spi package represent the deployment and configuration descriptors (WebLogic Server deployment descriptors) for an application. A WebLogicDeploymentConfiguration object is a wrapper for a deployment plan. A WebLogicDConfigBean encapsulates the properties in Weblogic deployment descriptors.

weblogic.deploy.api.spi.factories

This package contains only one interface - WebLogicDeploymentFactory. This is a WebLogic extension to javax.enterprise.deploy.spi.factories.DeploymentFactory. Use this factory interface to select and allocate DeploymentManager objects that have different characteristics. The WebLogicDeploymentManager characteristics are defined by public fields in the WebLogicDeploymentFactory.

Module Targeting

Module targeting is deploying specific modules in an application to different targets (as opposed to only deploying all modules to the same set of targets as specified by jsr88). The tools provided in support for module targeting are the WebLogicDeploymentManager.createTargetModuleID methods. Using TargetModuleID's is described in the discussion on Target Objects.

The WebLogicTargetModuleID class contains the WebLogic Server extensions to the javax.enterprise.deploy.spi.TargetModuleID interface. The WebLogicTargetModuleIDs in this class have a close relationship to the configured TargetInfoMBeans (AppDeploymentMBean and SubDeploymentMBean). The TargetModuleID's provide more detailed descriptions of the application modules and their relationship to targets than those in MBeans.

Support for Querying WebLogic Target Types

For WebLogic Server, the WebLogicTarget class provides a direct interface for maintaining the target types available to WebLogic Server. Target accessor methods are described in Table 2-1.

Table 2-1 Target Accessor Methods

Method	Description
`boolean isCluster()`	Indicates whether this target represents a cluster target.
`boolean isJMSServer()`	Indicates whether this target represents a JMS server target.
`boolean isSAFAgent()`	Indicates whether this target represents a SAF agent target.
`boolean isServer()`	Indicates whether this target represents a server target.
`boolean isVirtualHost()`	Indicates whether this target represents a virtual host target.

Server Staging Modes

The staging mode of an application affects its deployment behavior. The application's staging behavior is set using DeploymentOptions.setStageMode(string) and the following values yielding the following results:

STAGE - Force copying of files to target servers.
NO_STAGE - Inhibit copying of files to target servers.
EXTERNAL_STAGE - files are to be staged manually.

DConfigBean Validation

The property setters in a DConfigBean will reject attempts to set invalid values. This includes property type validation such as attempting to set an integer property to a non-numeric value. Some properties will also do more semantic validation, such as ensuring a maximum value is not smaller than its associated minimum value.

The Model Package

These classes are the WebLogic Server extensions to and implementations of the javax.enterprise.deploy.model interfaces. The model interfaces describes the standard elements, such as deployment descriptors, of a J2EE application.

weblogic.deploy.api.model

This package contains the interfaces used to represent the J2EE configuration of a deployable object. A deployable object is a deployment container for an Enterprise Application or standalone module.

The WebLogic Server implementation of the javax.enterprise.deploy.model interfaces enable you to work with applications that are stored in a WebLogic Server application installation directory, a formal directory structure used for managing application deployment files, deployments, and external WebLogic Deployment descriptors generated during the configuration process. See Preparing Applications and Modules for Deployment for more information about the layout of an application installation directory. It supports any J2EE application, with extensions to support applications residing in an application installation directory.

Note: weblogic.deploy.api.model does not support dynamic changes to J2EE deployment descriptor elements during configuration and therefore does not support registration and removal of Xpath listeners. DDBean.addXPathListener and removeXPathListener are not supported.

The WebLogicDeployableObject class and WebLogicDDBean interface in the weblogic.deploy.api.model package represent the standard deployment descriptors in an application.

Accessing Deployment Descriptors

J2EE Deployment API dictates that J2EE deployment descriptors be accessed through a DeployableObject. A DeployableObject represents a module in an application. Elements in the descriptors are represented by DDBeans, one for each element in a deployment descriptor. The root element of a descriptor is represented by a DDBeanRoot object. All of these interfaces are implemented in corresponding interfaces and classes in this package.

The WebLogicDeployableObject class, which is the weblogic server implementation of DeployableObject, provides the createDeployableObject methods, which create the WebLogicDeployableObjects and WebLogicDDBeans for the application's deployment descriptors. Basic configuration tasks are accomplished by associating these WebLogicDDBeans with WebLogicDConfigBeans, which represent the server configuration properties required for deploying the application on a WebLogic Server. These are discussed in the Overview of the Configuration Process.

Unlike DConfigbeans, which contain configuration information specifically for a server environment (in this case WebLogic server), the DDBean objects take in the general deployment descriptor elements for the application. For example, if you were deploying a Web application, the deployment descriptors that would end up in WebLogicDDBeans come from WEB-INF/web.xml file in the .war archive. The information for the WebLogicDConfigBeans would come from WEB-INF/weblogic.xml in the .war archive based on the WebLogicDDBeans. Though they serve the same fundamental purpose of holding configuration information, they are logically separate as DDBeans describe the application while the DConfigBeans configure the application for a specific environment.

Both of these objects are generated during the initiation of a configuration session. The WebLogicDeployableObject, WebLogicDDBeans, and WebLogicDConfigBeans are all instantiated and manipulated in a configuration session. The possible operations that can occur during a Configuration Session are described in Configuring an Application.

The Shared Package

The WebLogic Deployment API extends the weblogic.deploy.api.shared interfaces and provides the types listed below for complete server operability.

weblogic.deploy.api.shared

The weblogic.deploy.api.shared package provides classes that represent the WebLogic Server-specific deployment commands, module types, and target types as classes. These objects can be shared by model and SPI package members.

The definitions of the standard javax.enterprise.deploy.shared classes ModuleType and CommandType are extended in this package to include more specific information that the WebLogic Server can use. The additions provided by the extensions are as follows:

Module types (JMS, JDBC, Interception, Submodules, Diagnostics, WSEE, Custom)
Commands (deploy, update)

The WebLogicTargetType class, which is not required by the J2EE Deployment API standard (JSR-88), enumerates the different types of deployment targets supported by WebLogic Server. This class does not extend a javax deployment class. It defines the following target types (server, cluster, virtual hosts, JMS servers). See Target Objects for more information on targets.

Command Types for Deploy and Update

The deploy and update command types were added to the required command types defined in the javax.enterprise.spi.shared package. These commands are therefore available to a WebLogicDeploymentManager.

Support for Module Types

Supported module types include JMS, JDBC, Interception, WSEE, Config, and WLDF. These are defined in the weblogic.deploy.api.shared.WebLogicModuleType class as fields.

Support for all WebLogic Server Target Types

Targets, which were not implemented in the J2EE Deployment API specification, are implemented in the WebLogic Deployment API. The valid target values are:

Cluster
JMS Server
SAF (Software Agent Framework) Agent
Server
Virtual Host

These are enumerated field values in the weblogic.deploy.api.shared.WebLogicTargetType class.

The Tools Package

Use the tools in this package to perform common deployment tool tasks with a minimum of number of controls and explicit object manipulations. This includes controlling, WebLogicDeploymentManagers, WebLogicDeployableObjects and generating deployment plans.

weblogic.deploy.api.tools

The weblogic.deploy.api.tools package provides convenience classes that can help you:

Obtain a WebLogicDeploymentManager
Populate a configuration for an application
Create a new or updated deployment plan

The classes in the tools package are not extensions of the J2EE Deployment API standard (JSR-88) interfaces. They provide easy access to deployment operations provided by the WebLogic Deployment API.

SessionHelper

Although configuration sessions can be controlled from a WebLogicDeploymentManager directly, SessionHelper has simplified methods for this. These methods include:

getDeplymentManager, getDisconnectedDeploymentManager, getRemoteDeploymentManager: Accessing a WebLogicDeploymentManager
setApplication, setApplicationRoot, setPlan - identify the application and deployment plan to use in the session
initializeConfiguration, inspect: Initializing a configuration session
savePlan: Saving a deployment
getdefaultJMSTargetModuleIDs, getJMSDescriptor: JMS Submodule targeting
getApplication, getDescriptorURIs, getModuleInfo, etcetera: Application inspection - this provides information about the application components.

If your tools code directly to WebLogic Server's J2EE Deployment API implementation, you should always use SessionHelper.

As noted in the discussion of The SPI Package, SessionHelper can obtain a WebLogicDeploymentManager automatically with one method call. To do this effectively, it must be able to locate the application. The SessionHelper views an application and deployment plan artifacts using an "install root" abstraction, which ideally is the actual organization of the application. The install root appears as follows:

install-root (eg myapp)

-- app

----- archive (eg myapp.ear)

-- plan

----- deployment plan (eg plan.xml)

----- external descriptors (eg META-INF/weblogic-application.xml...)

There is no requirement that the above structure be used for applications, although it is a preferred approach as it serves to keep the application and its configuration artifacts under a common root, thus providing SessionHelper with a format it can interpret.

SessionHelper.getModuleInfo() returns an object that is useful for understanding the structure of an application without having to work directly with DDBeans and DeployableObjects. It provides such information as

Names and types of modules and submodules in the application
Names of web services provided by the application
Context roots for web applications
Names of enterprise beans in an EJB

Internally, the deployment descriptors are represented as descriptor bean trees, trees of typed Java Bean objects that represent the individual descriptor elements. These bean tress are easier to work with than the more generic DDBean and DConfigBean objects. The descriptor bean trees for each module are directly accessible from the associated WebLogicDDBeanRoot and WebLogicDConfigBeanRoot objects for each module via their getDescriptorBean methods. Modifying the bean trees obtained from a WebLogicDConfigBean has the same effect as modifying the associated DConfigBean, and therefore the application's deployment plan.

Deployment Plan Creation

weblogic.PlanGenerator creates a deployment plan template based on the standard and WebLogic Server descriptors included in an application. The resulting plan will describe the application structure, identify all deployment descriptors and will export a subset of the application's configurable properties. Exporting a property exposes it to tools like the WebLogic Server console which can use the plan to assist the administrator in providing appropriate values for those properties. By default, the PlanGenerator tool only exports application dependencies; those properties required for a successful deployment. This behavior can be overridden with one of the following options:

Dependencies: Export resources referenced by the application (this is the default)
Declarations: Export resources defined by the application
Configurables: Export non-resource oriented configurable properties
Dynamics: Export properties that may be changed in a running application
All: Export all changeable properties
None: Export no properties