|Oracle® Fusion Middleware Programming Deployment for Oracle WebLogic Server
11g Release 1 (10.3.1)
Part Number E13703-01
The WebLogic Deployment API implements and extends the J2EE Deployment API standard (JSR-88, see
http://java.sun.com/j2ee/tools/deployment/index.jsp) interfaces to provide specific deployment functionality for WebLogic Server applications. The following sections describe the structure and functionality of the WebLogic Deployment API:
Note:WebLogic Server 9.0 deprecates the use of the
weblogic.management.deployAPI used in earlier releases.
The following sections provide an overview of the WebLogic Server Deployment API:
The J2EE Deployment API standard (JSR-88, see
http://java.sun.com/j2ee/tools/deployment/index.jsp) differentiates between a configuration session and deployment. They are distinguished as follows:
Application Configuration which involves the generation of descriptors for a deployment plan
Deployment tasks such as Distributing, Starting, Stopping, Redeploying, Undeploying
In order to effectively manage the deployment process in your environment, you must use the WebLogic Deployment API to:
In this document, the term configuration refers to the process of preparing an application or deployable resource for deployment to a WebLogic Server instance. Configuring an application consists of the following phases:
Application Evaluation - Inspection and evaluation of application files to determine the structure of the application and content of the embedded descriptors. See Application Evaluation.
Front-end Configuration - Creation of configuration information based on content embedded within the application. This content may be in the form of WebLogic Server descriptors, defaults, and user provided deployment plans. See Perform Front-end Configuration.
Deployment Configuration - Modification of individual WebLogic Server configuration values based on user inputs and the selected WebLogic Server targets. See Customizing Deployment Configuration.
Deployment preparation - Generation of the final deployment plan and preliminary client-side validation of the application. See Deployment Preparation.
Application deployment is the process of distributing an application and plan to the Administration Server for server-side processing and application startup. See Chapter 4, "Performing Deployment Operations".
WebLogic Server provides a packaged deployment tool,
weblogic.Deployer, to provide deployment services for WebLogic Server. Any deployment operation that can be implemented using the WebLogic Deployment API is implemented, either in part or in full, by
webLogic.Deployeris the recommended deployment tool for the WebLogic Server Environment. See Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server for information on how to use
webLogic.Deployerand the WebLogic Server Administration Console.
You may need to implement the WebLogic Deployment API in the following cases:
You need to model your own implementation and interface with the WebLogic Service Provider Interface (SPI). In this case, the WebLogic Deployment API deployment factory is used to obtain a
WebLogicDeploymentManager, which extends
http://java.sun.com/javaee/5/docs/api/javax/enterprise/deploy/spi/DeploymentManager.html) for use with the
weblogic.deploy.api.spi. See Application Evaluation and the J2EE Deployment API standard at
You need to create your own deployment interface instead using the WebLogic Server Administration Console and/or
webLogic.Deployer. In this case, you may implement some or all WebLogic Deployment API Deployment Phases using the WebLogic Deployment API classes and interfaces.
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 (see
http://java.sun.com/javaee/5/docs/api/overview-summary.html). The WebLogic Deployment API provides the following packages:
WebLogic supports the "Product Provider" role described in the J2EE Deployment API standard (JSR-88) at
http://java.sun.com/j2ee/tools/deployment/index.jsp and 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, such as starting in
admin mode or redeploying with versioning.
Fine grain control, such as:
Module level targeting
Partial Redeployment, the redeployment or removal of parts of an application.
Dynamic configuration changes.
Support of WebLogic module extensions such as JMS, JDBC, Interception, and Application Specific Configuration (Custom/Configuration) modules.
Additional operations, such as the
Deploy verb which combines
Note:The WebLogic Deployment API does not support an automated fallback procedure for a failed application update. The policy and procedures for this behavior must be defined and configured by the developers and administrators for each deployment environment.
As a J2EE product provider, Oracle extends the Sun Microsystems
javax Service Provider Interface (SPI) package to provide specific configuration and deployment control for WebLogic Server. The core interface for this package is the
DeploymentManager, from which all other deployment activities are initiated, monitored, and controlled.
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. See Application Evaluation.
The following sections provide basic information on the functionality of the WebLogic Server SPI:
weblogic.deploy.api.spi package provides the interfaces required to configure and deploy applications to a target (see Support for Querying WebLogic Target Types for valid target types). This package enables you to create deployment tools that can implement a WebLogic Server-specific deployment configuration for an Enterprise Application or stand-alone module.
weblogic.deploy.api.spi includes the
WebLogicDeploymentManager interface. Use this deployment manager to perform all deployment-related operations such as distributing, starting, and stopping applications in WebLogic Server. The
WebLogicDeploymentManager also provides important extensions to the J2EE
DeploymentManager interface for 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.
WebLogicDConfigBean classes in the
weblogic.deploy.api.spi package represent the deployment and configuration descriptors (WebLogic Server deployment descriptors) for an application.
WebLogicDeploymentConfiguration object is a wrapper for a deployment plan.
WebLogicDConfigBean encapsulates the properties in WebLogic deployment descriptors.
This package contains only one interface, the
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
Module targeting is deploying specific modules in an application to different targets as opposed to deploying all modules to the same set of targets as specified by JSR-88. Module targeting is supported by the
WebLogicTargetModuleID class contains the WebLogic Server extensions to the
javax.enterprise.deploy.spi.TargetModuleID interface. This class is closely related to the configured
WebLogicTargetModuleID class provides more detailed descriptions of the application modules and their relationship to targets than those in
TargetInfoMBeans. See Module 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
Indicates whether this target represents a cluster target.
Indicates whether this target represents a JMS server target.
Indicates whether this target represents a SAF agent target.
Indicates whether this target represents a server target.
Indicates whether this target represents a virtual host target.
The staging mode of an application affects its deployment behavior. The application's staging behavior is set using
DeploymentOptions.setStageMode(stage mode) where the value of
stage mode is one of the following:
STAGE - Force copying of files to target servers.
NO_STAGE - Files are not copied to target servers.
EXTERNAL_STAGE - Files are staged manually.
The property setters in a
DConfigBean 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 perform semantic validations, such as ensuring a maximum value is not smaller than its associated minimum value.
These classes are the WebLogic Server extensions to and implementations of the
javax.enterprise.deploy.model interfaces (see
http://java.sun.com/javaee/5/docs/api/javax/enterprise/deploy/model/package-summary.html). The model interfaces describes the standard elements, such as deployment descriptors, of a J2EE application.
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.
weblogic.deploy.api.modeldoes not support dynamic changes to J2EE deployment descriptor elements during configuration and therefore does not support registration and removal of XPath listeners.
removeXPathListenerare not supported.
WebLogicDeployableObject class and
WebLogicDDBean interface in the
weblogic.deploy.api.model package represent the standard deployment descriptors in an application.
J2EE Deployment API dictates that J2EE deployment descriptors be accessed through 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.
WebLogicDeployableObject class, which is the WebLogic Server implementation of
DeployableObject, provides the
createDeployableObject methods, which create the
WebLogicDDBean for the application's deployment descriptors. Basic configuration tasks are accomplished by associating the
WebLogicDDBean with a
WebLogicDConfigBean, which represent the server configuration properties required for deploying the application on a WebLogic Server. See Application Evaluation.
DConfigbean, which contain configuration information specifically for a server environment (in this case WebLogic server instance), a
DDBean object takes in the general deployment descriptor elements for the application. For example, if you were deploying a Web application, the deployment descriptors 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 a
DDBean describes the application while a
DConfigBeans configures the application for a specific environment.
Both of these objects are generated during the initiation of a configuration session. The
WebLogicDConfigBeans are all instantiated and manipulated in a configuration session. See Overview of the Configuration Process.
The following sections provide information on classes that represent WebLogic Server-specific deployment commands, module types, and target types as classes:
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 weblogic.deploy.api.model and weblogic.deploy.api.spi packages.
The definitions of the standard
CommandType are extended to provide support for:
WebLogicTargetType class, which is not required by the J2EE Deployment API standard (JSR-88, see
http://java.sun.com/j2ee/tools/deployment/index.jsp), enumerates the different types of deployment targets supported by WebLogic Server. This class does not extend a javax deployment class. See Support for all WebLogic Server Target Types.
update command types are added to the required command types defined in the
javax.enterprise.spi.shared package and are available to a
Supported module types include JMS, JDBC, Interception, WSEE, Config, and WLDF. These are defined in the
weblogic.deploy.api.shared.WebLogicModuleType class as fields.
Targets, which were not implemented in the J2EE Deployment API specification, are implemented in the WebLogic Deployment API. The valid target values are:
SAF (Store-and-Forward) Agent
These are enumerated field values in the
The following sections provide information on API tools you can use to perform common deployment tool tasks with a minimum of number of controls and explicit object manipulations:
weblogic.deploy.api.tools package provides convenience classes that can help you:
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, see
http://java.sun.com/j2ee/tools/deployment/index.jsp) interfaces. They provide easy access to deployment operations provided by the WebLogic Deployment API.
Although configuration sessions can be controlled from a
SessionHelper provides simplified methods. If your tools code directly to WebLogic Server's J2EE Deployment API implementation, you should always use
SessionHelper to obtain a
WebLogicDeploymentManager 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 to mandate that this structure be used for applications. It is a preferred approach because it serves to keep the application and its configuration artifacts under a common root and provides
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
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 and trees of typed Java Bean objects that represent the individual descriptor elements. These bean trees are easier to work with than the more generic
DConfigBean objects. The descriptor bean trees for each module are directly accessible from the associated
WebLogicDConfigBeanRoot objects for each module using 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.
weblogic.PlanGenerator creates a deployment plan template based on the J2EE and WebLogic Server descriptors included in an application. The resulting plan describes the application structure, identifies all deployment descriptors, and exports a subset of the application's configurable properties. Export properties to expose them to tools like the WebLogic Server console which then uses the plan to assist the administrator in providing appropriate values for those properties. By default, the
weblogic.PlanGenerator tool only exports application dependencies; those properties required for a successful deployment. This behavior can be overridden using of the following options:
Dependencies: Export resources referenced by the application (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