Oracle® Fusion Middleware

Deploying Applications with the WebLogic Deployment API

12c (12.2.1.2.0)

E77960-02

December 2016

This document describes the WebLogic Deployment API and performing deployment operations programmatically for WebLogic Server applications.

Oracle Fusion Middleware Deploying Applications with the WebLogic Deployment API, 12c (12.2.1.2.0)

E77960-02

Copyright © 2007, 2016, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

- Documentation Accessibility

- Conventions

1 Introduction and Roadmap

- Document Scope and Audience

- Guide to This Document

- Related Documentation

- New and Changed Features in This Release

2 Understanding the WebLogic Deployment API

- The WebLogic Deployment API

- WebLogic Deployment API Deployment Phases

- Configure an Application for Deployment

- Deploy an Application

- weblogic.Deployer Implementation of the WebLogic Deployment API

- When to Use the WebLogic Deployment API

- Java EE Deployment API Compliance

- WebLogic Server Value-Added Deployment Features

- The Service Provider Interface Package

- weblogic.deploy.api.spi

- weblogic.deploy.api.spi.factories

- Module Targeting

- Support for Querying WebLogic Target Types

- Server Staging Modes

- Deployment Plan Staging Modes

- DConfigBean Validation

- The Model Package

- weblogic.deploy.api.model

- Accessing Deployment Descriptors

- The Shared Package

- weblogic.deploy.api.shared

- Command Types for Deploy and Update

- Support for Module Types

- Support for all WebLogic Server Target Types

- The Tools Package

- weblogic.deploy.api.tools

- SessionHelper

- Deployment Plan Creation

- The JMX API for Deployment Operations

- Supported Deployment Options

- Using the JMX API for Deployment Operations

- Using a Deployment Validation Plug-In with WebLogic Server

- Configuring the Deployment Validation Plug-In

- Using the Deployment Validation Plug-In

3 Configuring Applications for Deployment

- Overview of the Configuration Process

- Types of Configuration Information

- Java EE Configuration

- WebLogic Server Configuration

- Representing Java EE and WebLogic Server Configuration Information

- DDBeans

- The Relationship Between Java EE and WebLogic Server Descriptors

- DConfigBeans

- Application Evaluation

- Obtain a Deployment Manager

- Types of Deployment Managers

- Connected and Disconnected Deployment Manager URIs

- Using SessionHelper to Obtain a Deployment Manager

- Create a Deployable Object

- Using the WebLogicDeployableObject class

- Using SessionHelper to obtain a Deployable Object

- Perform Front-end Configuration

- What is Front-end Configuration

- Deployment Configuration

- Example Code

- Reading In Information with SessionHelper

- Validating a Configuration

- Customizing Deployment Configuration

- Modifying Configuration Values

- Targets

- Application Naming

- Deployment Preparation

- Session Cleanup

4 Performing Deployment Operations

- Register Deployment Factory Objects

- Allocate a DeploymentManager

- Getting a DeploymentManager Object

- Understanding DeploymentManager URI Implementations

- Server Connectivity

- Deployment Processing

- DeploymentOptions

- Distribution

- Application Start

- Application Deploy

- Application Stop

- Undeployment

- Production Redeployment

- In-Place Redeployment

- Module Level Targeting

- Retirement Policy

- Version Support

- Administration (Test) Mode

- Progress Reporting

- Target Objects

- Module Types

- Extended Module Support

- Web Services

- CMP

- JDBC

- JMS

- INTERCEPT

- Recognition of Target Types

- TargetModuleID Objects

- WebLogic Server TargetModuleID Extensions

- Example Module Deployment

Preface

This preface describes the document accessibility features and conventions used in this guide—Deploying Applications with the WebLogic Deployment API.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1 Introduction and Roadmap

This chapter describes the contents and organization of this guide— Deploying Applications with the WebLogic Deployment API.

This chapter includes the following sections:

- Document Scope and Audience

- Guide to This Document

- Related Documentation

- New and Changed Features in This Release

Document Scope and Audience

This document is a resource for:

- Software developers who want to understand the WebLogic Deployment API. This API adheres to the specifications described in the Java EE Deployment API standard (JSR-88, see http://jcp.org/en/jsr/detail?id=88) and extends the interfaces provided by that standard.

- Developers and Independent Software Vendors (ISVs) who want to perform deployment operations programmatically for WebLogic Server applications.

- System architects who are evaluating WebLogic Server or considering the use of the WebLogic Deployment API.

- Design, development, test, and pre-production phases of a software project. It does not directly address production phase administration, monitoring, or tuning application performance with the WebLogic Deployment API. The deployment API includes utilities to make software updates during production but it mirrors the functionality of the deployment tools already available.

This guide emphasizes:

- Value-added features of the WebLogic Deployment API.

- How to manage application deployment using the WebLogic Deployment API.

It is assumed that the reader is familiar with Java EE concepts, the Java EE Deployment API standard (JSR-88) at http://www.jcp.org/en/jsr/detail?id=088, the Java programming language, Enterprise Java Beans (EJBs), and Web technologies.

Guide to This Document

- This chapter, Introduction and Roadmap, describes the organization and scope of this guide.

- Understanding the WebLogic Deployment API, describes the packages, interfaces, and classes of the API. This section also includes information on extensions to the Java EE Deployment API standard (JSR-88, see http://jcp.org/en/jsr/detail?id=88), utilities, helper classes, and new concepts for WebLogic Server deployment.

- Configuring Applications for Deployment, describes the process of preparing an application or deployable resource for deployment to WebLogic Server.

- Performing Deployment Operations, provides information on the deployment life cycle and controls for a deployed application.

Related Documentation

For additional information about deploying applications and modules to WebLogic Server, see these documents:

- Developing Applications for Oracle WebLogic Server describes how to deploy applications during development using the wldeploy Ant task, and provides information about the WebLogic Server deployment descriptor for enterprise applications.

- The WebLogic Server Java EE programming guides describe the Java EE and WebLogic Server deployment descriptors used with each Java EE application and module:

- Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server

- Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server

- Developing Resource Adapters for Oracle WebLogic Server

- Developing JAX-WS Web Services for Oracle WebLogic Server

- Deploying Applications to Oracle WebLogic Server

- Developing JDBC Applications for Oracle WebLogic Server describes the XML deployment descriptors for JDBC application modules.

- Developing JMS Applications for Oracle WebLogic Server describes the XML deployment descriptors for JMS application modules.

New and Changed Features in This Release

For a comprehensive listing of the new WebLogic Server features introduced in this release, see What's New in Oracle WebLogic Server 12.2.1.2.0.

2 Understanding the WebLogic Deployment API

This chapter describes the structure and functionality of the WebLogic Deployment API, which implements and extends the Java EE Deployment API specification (JSR-88). It also describes the JMX API for deployment operations, which can be used as an alternative to JSR-88.

This chapter includes the following sections:

- The WebLogic Deployment API

- Java EE Deployment API Compliance

- WebLogic Server Value-Added Deployment Features

- The Service Provider Interface Package

- The Model Package

- The Shared Package

- The Tools Package

- The JMX API for Deployment Operations

- Using a Deployment Validation Plug-In with WebLogic Server

For more on JSR-88, see http://jcp.org/en/jsr/detail?id=88.

The WebLogic Deployment API

Note:

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

The following sections provide an overview of the WebLogic Server Deployment API:

- WebLogic Deployment API Deployment Phases

- weblogic.Deployer Implementation of the WebLogic Deployment API

- When to Use the WebLogic Deployment API

WebLogic Deployment API Deployment Phases

The Java EE Deployment API specification (JSR-88, see http://jcp.org/en/jsr/detail?id=88) 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:

- Configure an Application for Deployment

- Deploy an Application

Configure an Application for Deployment

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.

Deploy an Application

Application deployment is the process of distributing an application and plan to the Administration Server for server-side processing and application startup. See Performing Deployment Operations.

weblogic.Deployer Implementation of the WebLogic Deployment API

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.Deployer.

When to Use the WebLogic Deployment API

Note:

weblogic.Deployer is the recommended deployment tool for the WebLogic Server environment. See Deploying Applications to Oracle WebLogic Server for information on how to use weblogic.Deployer and 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 javax.enterprise.deploy.spi.DeploymentManager (see http://docs.oracle.com/javaee/7/api/javax/enterprise/deploy/spi/DeploymentManager.html) for use with the weblogic.deploy.api.spi. See Application Evaluation and the Java EE Deployment API specification at http://jcp.org/en/jsr/detail?id=88.

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

Java EE Deployment API Compliance

The WebLogic Deployment API classes and interfaces extend and implement the Java EE Deployment API specification (JSR-88) interfaces, which are described in the javax.enterprise.deploy sub-packages (see http://docs.oracle.com/javaee/7/api/overview-summary.html). The WebLogic Deployment API provides the following packages:

- weblogic.deploy.api.spi

- weblogic.deploy.api.spi.factories

- weblogic.deploy.api.model

- weblogic.deploy.api.shared

- weblogic.deploy.api.tools

WebLogic Server Value-Added Deployment Features

WebLogic supports the "Product Provider" role described in the Java EE Deployment API specification (JSR-88) at http://jcp.org/en/jsr/detail?id=88 and provides utilities specific to the WebLogic Server environment in addition to extensible components for any Java EE 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 distribute and start.

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.

The Service Provider Interface Package

As a Java EE product provider, Oracle extends the 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.

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. See Application Evaluation.

The following sections provide basic information on the functionality of the WebLogic Server SPI:

- weblogic.deploy.api.spi

- weblogic.deploy.api.spi.factories

- Module Targeting

- Support for Querying WebLogic Target Types

- Server Staging Modes

- Deployment Plan Staging Modes

- DConfigBean Validation

weblogic.deploy.api.spi

The 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 Java EE 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.

The WebLogicDeploymentConfiguration and WebLogicDConfigBean classes in the weblogic.deploy.api.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, 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 WebLogicDeploymentFactory.

Module Targeting

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 WebLogicDeploymentManager.createTargetModuleID methods.

The WebLogicTargetModuleID class contains the WebLogic Server extensions to the javax.enterprise.deploy.spi.TargetModuleID interface. This class is closely related to the configured TargetInfoMBeans (AppDeploymentMBean and SubDeploymentMBean). The WebLogicTargetModuleID class provides more detailed descriptions of the application modules and their relationship to targets than those in TargetInfoMBeans. See Module Types.

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(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.

Deployment Plan Staging Modes

An application's deployment plan can be staged independently of the application archive, allowing you to stage a deployment plan when the application is not staged. You can configure the staging behavior of the deployment plan by using DeploymentOptions.setPlanStageMode (plan stage mode), where the value of plan stage mode is one of the following:

- STAGE—Deployment plan is copied to target servers.

- NO_STAGE—Deployment plan is not copied to target servers.

- EXTERNAL_STAGE—Deployment plan is copied manually to target servers.

If you do not specify a staging mode, the deployment plan uses the value specified for application staging as the default. For example, if deployment plan staging is not specified and application staging is set to STAGE, the deployment plan staging mode is set to STAGE.

DConfigBean Validation

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.

The Model Package

These classes are the WebLogic Server extensions to and implementations of the javax.enterprise.deploy.model interfaces (see http://docs.oracle.com/javaee/7/api/javax/enterprise/deploy/model/package-summary.html). The model interfaces describes the standard elements, such as deployment descriptors, of a Java EE application.

- weblogic.deploy.api.model

- Accessing Deployment Descriptors

weblogic.deploy.api.model

This package contains the interfaces used to represent the Java EE configuration of a deployable object. A deployable object is a deployment container for an enterprise application or stand-alone 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 Java EE application, with extensions to support applications residing in an application installation directory.

Note:

weblogic.deploy.api.model does not support dynamic changes to Java EE 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

Java EE Deployment API dictates that Java EE deployment descriptors be accessed through a DeployableObject (see http://docs.oracle.com/javaee/7/api/javax/enterprise/deploy/model/DeployableObject.html). 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 WebLogicDeployableObject and 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.

Unlike a 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 WebLogicDeployableObject, WebLogicDDBeans, and WebLogicDConfigBeans are all instantiated and manipulated in a configuration session. See Overview of the Configuration Process.

The Shared Package

The following sections provide information on classes that represent WebLogic Server-specific deployment commands, module types, and target types as classes:

- weblogic.deploy.api.shared

- Command Types for Deploy and Update

- Support for Module Types

- Support for all WebLogic Server Target Types

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 weblogic.deploy.api.model and weblogic.deploy.api.spi packages.

The definitions of the standard javax.enterprise.deploy.shared classes ModuleType and CommandType are extended to provide support for:

- The module type, see Support for Module Types

- Commands, see Command Types for Deploy and Update

The WebLogicTargetType class, which is not required by the Java EE Deployment API specification (JSR-88, see http://jcp.org/en/jsr/detail?id=88), 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.

Command Types for Deploy and Update

The deploy and update command types are added to the required command types defined in the javax.enterprise.spi.shared package and are 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 Java EE Deployment API specification, are implemented in the WebLogic Deployment API. The valid target values are:

- Cluster

- JMS Server

- SAF (Store-and-Forward) Agent

- Server

- Virtual Host

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

The Tools Package

The following sections provide information on API tools you can use to perform common deployment tool tasks with a minimum number of controls and explicit object manipulations:

- weblogic.deploy.api.tools

- SessionHelper

- Deployment Plan Creation

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 Java EE Deployment API specification (JSR-88, see http://jcp.org/en/jsr/detail?id=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 provides simplified methods. If your tools code directly to the WebLogic Server Java EE Deployment API implementation, you should always use SessionHelper.

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 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 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 DDBean and DConfigBean objects. The descriptor bean trees for each module are directly accessible from the associated WebLogicDDBeanRoot and 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.

Deployment Plan Creation

weblogic.PlanGenerator creates a deployment plan template based on the Java EE 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

The JMX API for Deployment Operations

The Java Management Extensions (JMX) API for deployment operations supports all of the common functionality available in the Java EE Deployment API specification (JSR-88). You can use the JMX API as an alternative to JSR-88 to perform deployment tasks on specified target servers, such as:

- Starting

- Stopping

- Distributing

- Deploying

- Redeploying

- Undeploying

- Updating deployment plans without redeploying applications

The JMX API for deployment operations uses open MBean data types so that no WebLogic Server classes are required on the client side. These new MBeans for deployment are similar conceptually to JSR-88 and are located in the Domain Runtime MBean Server. In this model, you must initiate deployment operations on the Administration Server.

The following four runtime MBeans support the JMX API for deployment operations:

- DeploymentManagerMBean
The DeploymentManagerMBean provides deployment operations, including deploy and distribute, and provides access to the AppDeploymentRuntime MBeans for each application deployed to the domain. It also manages the deployment progress objects and emits notifications when an application is created or removed and when the application state changes.

- AppDeploymentRuntimeMBean
The AppDeploymentRuntimeMBean provides the deployment operations for an application, including start, stop, undeploy, redeploy, and updating a deployment plan without redeploying the application.

- DeploymentProgressObjectMBean
The DeploymentProgressObjectMBean monitors deployment operations initiated by the AppDeploymentRuntime MBeans.

- LibDeploymentRuntimeMBean
The LibDeploymentRuntimeMBean provides deployment operations for a library, including undeploy and redeploy.

For more information, see the MBean Reference for Oracle WebLogic Server.

Supported Deployment Options

The JMX API for deployment operations supports all of the deployment options available in JSR-88, which are specified as Property name-value pairs. By specifying deployment options, you can override the default values. Table 2-2 summarizes the supported deployment option names and values.

Table 2-2 Deployment Options Supported by the JMX API

Deployment Option

Description

adminMode

Option that indicates that a running application should switch to ADMIN mode and accept only administration requests over a configured administration channel.

altDD

Location of the alternate application deployment descriptor on the Administration Server.

altWlsDD

Location of the alternate WebLogic application deployment descriptor on the Administration Server.

appVersion

Version identifier of the application.

clusterDeploymentTimeout

Time, in milliseconds, granted for a cluster deployment task on this application.

createPlan

Boolean value indicating that the user wants to create a default plan. The default value for this option is false.

defaultSubmoduleTargets

Boolean value indicating that targeting for qualifying JMS submodules should be derived by the system. The default value for this option is true.

deploymentOrder

Option that controls the load order of deployments relative to one another.

deploymentPrincipalName

String value specifying the principal for deploying the file or archive during server starts (static deployment; it does not affect the current deployment task).

forceUndeployTimeout

Force undeployment timeout value.

gracefulIgnoreSessions

Boolean value specifying whether graceful production to ADMIN mode operation should ignore pending HTTP sessions. The default value of this option is false and only applies if gracefulProductionToAdmin is set to true.

gracefulProductionToAdmin

Boolean value specifying whether the production to ADMIN mode operation should be graceful. The default value for this option is false.

library

The deployment as a shared Java EE library or optional package.

libImplVer

Implementation version of the library, if it is not present in the manifest.

libSpecVer

Specification version of the library, if it is not present in the manifest.

noVersion

Versioning information is ignored.

planVersion

Version identifier of the deployment plan.

retireGracefully

Retirement policy to gracefully retire an application only after it completes all in-flight work. This policy is only meaningful for stop and redeploy operations and is mutually exclusive to the retire timeout policy.

retireTimeout

Time (in seconds) WebLogic Server waits before retiring an application that is replaced with a newer version. The default value for this option is -1, which specifies graceful timeout.

rmiGracePeriod

The amount of time, in seconds, that the Work Manager accepts and schedules RMI calls until there are no more RMI requests arriving within the RMI grace period during a graceful shutdown or a retirement.

securityModel

Security model. Valid values include: DDOnly, CustomRoles, CustomRolesAndPolicies, and Advanced.

securityValidationEnabled

Boolean value specifying whether security validation is enabled.

stageMode

The staging mode for the application you are deploying. Valid values are stage, nostage, and external_stage. If not specified, WebLogic Server uses the default stage mode. The default stage mode is nostage for the Administration Server and stage for Managed Servers.

subModuleTargets

Submodule level targets for JMS modules. For example: submod@mod-jmx.xml@target | submoduleName@!target.

timeout

Time (in milliseconds) WebLogic Server waits for the deployment process to complete before canceling the operation. A value of 0 indicates no timeout for the operation. The default value for this argument is 300,000 ms (or five minutes).

useNonExclusiveLock

Deployment operation uses an existing lock, already acquired by the same user, on the domain. This option is helpful in environments where multiple deployment tools are used simultaneously and one of the tools has already acquired a lock on the domain configuration.

versionIdentifier

Version identifier.

Using the JMX API for Deployment Operations

Example 2-1 demonstrates the use of the WebLogic Server JMX API for deployment operations. The example includes inline comments and demonstrates how to:

- deploy an application both synchronously and asynchronously

- monitor the progress of a deployment operation

- stop an application

- undeploy an application

- handle notifications

Note:

This example uses JMX proxies for readability. The WebLogic Server JMX API uses open types so it can be run in a JMX client without WebLogic Server classes. In addition, error handling has been omitted to keep the example as small as possible.

For more information about understanding and using JMX, see Developing Custom Management Utilities Using JMX for Oracle WebLogic Server and Developing Manageable Applications Using JMX for Oracle WebLogic Server.

Example 2-1 Using the JMX API for Deployment Operations

import weblogic.management.mbeanservers.domainruntime.DomainRuntimeServiceMBean;
import weblogic.management.runtime.AppDeploymentRuntimeMBean;
import weblogic.management.runtime.DeploymentManagerMBean;
import weblogic.management.runtime.DeploymentProgressObjectMBean;

import java.util.Hashtable;
import java.util.Properties;

import javax.management.MBeanServerConnection;
import javax.management.Notification;
import javax.management.NotificationListener;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
import javax.naming.Context;

public class JMXDeploymentExample {

// Deployment Manager JMX proxy
DeploymentManagerMBean deploymentManager;

// Domain Runtime MBean Server connection
MBeanServerConnection connection;

private void setUp() throws Exception {
System.out.println("*** Setting up...");

// Get connection to the Domain Runtime MBean Server.
// For more information, see Make Remote Connections to an MBean Server.
// in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.
connection = getDomainRuntimeJMXConnection();

// Get DeploymentManager JMX proxy.
// For more information, see Oracle WebLogic Server MBean Reference.
DomainRuntimeServiceMBean svcBean = (DomainRuntimeServiceMBean)
weblogic.management.jmx.MBeanServerInvocationHandler.newProxyInstance(
connection, new ObjectName(DomainRuntimeServiceMBean.OBJECT_NAME));
deploymentManager = svcBean.getDomainRuntime().getDeploymentManager();

// Add a JMX notification listener that outputs the JMX notifications generated during deployment operations.
connection.addNotificationListener(new ObjectName("com.bea:Name=DeploymentManager,Type=DeploymentManager"),
new DeployListener(), null, null);
}

/*
* Demonstrates synchronously deploying an application.
*/

private void deploySynchronously() throws Exception {
System.out.println("*** Deploying SimpleApp...");

// This form of the deploy operation is synchronous.
// Errors are still returned through a progress object.
// By default, the SimpleApp is deployed to all servers.

DeploymentProgressObjectMBean progressObj = deploymentManager.deploy(
"SimpleApp", "/apps/simpleapp.war", /* no plan */ null);
printCompletionStatus(progressObj);
}

/*
* Demonstrates asynchronously deploying an application to a server instance.
*/

private void deployASynchronously() throws Exception {
System.out.println("*** Deploying VersionedApp...");

// This form of the deploy operation is asynchronous.
// The caller should utilize the returned progress object to monitor the progress of the deployment.

Properties deploymentOptions = new Properties();
deploymentOptions.put("appVersion", "V1");
deploymentOptions.put("planVersion", "P1");

DeploymentProgressObjectMBean progressObj = deploymentManager.deploy("VersionedApp", "/apps/app-v1.war",
new String[] { "myserver" },
"/apps/app-v1-plan.xml", deploymentOptions);

waitForCompletion(progressObj, 200);
}

/*
* Demonstrates using a deployment progress object to display the status of the deployment operation.
*/

private void printCompletionStatus(DeploymentProgressObjectMBean progressObj) throws Exception {

System.out.println(" State: " + progressObj.getState());
if ("STATE_FAILED".equals(progressObj.getState())) {
Exception[] exceptions = progressObj.getRootExceptions();
for (int i = 0; exceptions != null && i < exceptions.length; i++)
System.out.println(" Exception: " + exceptions[i]);
}
}

/*
* Demonstrates using a deployment progress object to wait for the completion of the deployment operation.
*/

private void waitForCompletion(DeploymentProgressObjectMBean progressObj, int timeoutSecs) throws Exception {

for (int i = 0; i < timeoutSecs; i++) {
String state = progressObj.getState();
if ("STATE_COMPLETED".equals(state) || "STATE_FAILED".equals(state))
break;
try {
Thread.currentThread().sleep(1000);
} catch (InterruptedException ex) {
//ignore
}
}

printCompletionStatus(progressObj);
}

/*
* Demonstrates stopping an application asynchronously.
*/

private void stopAsynchonously() throws Exception {
System.out.println("*** Stopping SimpleApp...");

// The DeploymentManagerMBean is used for the initial deployment of an application.
// After the initial deployment, the AppDeploymentRuntimeMBean is used for stop, start,
// redeploy, and undeploy of an application.

AppDeploymentRuntimeMBean appRuntime = deploymentManager.lookupAppDeploymentRuntime("SimpleApp");

Properties deploymentOptions = new Properties();
deploymentOptions.put("gracefulIgnoreSessions", "true");

DeploymentProgressObjectMBean progressObj = appRuntime.stop(new String[]{"myserver"}, deploymentOptions);
waitForCompletion(progressObj, 200);

}

/*
* Demonstrates using an AppDeploymentRuntimeMBean to undeploy an application.
*/

private void undeploySynchronously() throws Exception {
System.out.println("*** Undeploying SimpleApp...");

// The DeploymentManagerMBean is used for the initial deployment of an application.
// After the initial deployment, the AppDeploymentRuntimeMBean is used for stop, start,
// redeploy, and undeploy of an application.

AppDeploymentRuntimeMBean appRuntime = deploymentManager.lookupAppDeploymentRuntime("SimpleApp");

DeploymentProgressObjectMBean progressObj = appRuntime.undeploy();
printCompletionStatus(progressObj);

}

/*
* Demonstrates the notifications that are generated by WebLogic Server deployment operations.
*/

private class DeployListener implements NotificationListener {

public void handleNotification(Notification notification, Object handback) {
System.out.println(" Notification from DeploymentManagerMBean");
System.out.println("  notification type:  " + notification.getType());
String userData = (String)notification.getUserData();
System.out.println("  userData:  " + userData);
}

}

private MBeanServerConnection getDomainRuntimeJMXConnection() throws Exception {

JMXServiceURL serviceURL = new JMXServiceURL("t3", "localhost", 7001,
"/jndi/weblogic.management.mbeanservers.domainruntime");

Hashtable h = new Hashtable();
h.put(Context.SECURITY_PRINCIPAL, "weblogic");
h.put(Context.SECURITY_CREDENTIALS, "password");
h.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, "weblogic.management.remote");

JMXConnector connector = JMXConnectorFactory.connect(serviceURL, h);
MBeanServerConnection connection = connector.getMBeanServerConnection();
return connection;
}

public static void main(String args[]) throws Exception {
JMXDeploymentExample example = new JMXDeploymentExample();

example.setUp();
example.deploySynchronously();
example.deployASynchronously();
example.stopAsynchonously();
example.undeploySynchronously();
}

}

Using a Deployment Validation Plug-In with WebLogic Server

You can validate applications before allowing them to be deployed to your WebLogic Server domain by creating a deployment validation plug-in. At the start of the deployment process, the Administration Server executes the plug-in, which determines whether the application is valid for the domain. If validation passes, the application is deployed. If validation fails, the application is not deployed, and there is no configuration change or evidence of deployment.

When using a deployment validation plug-in, you determine what it should consider invalid based on the specific needs of your domain. For example, you can configure the plug-in to reject bad formats or EJBs. You can only register one deployment validation plug-in per domain, and the plug-in must be unique to the domain. You can configure a new deployment validation plug-in to replace the original, but you cannot add a second plug-in to the same domain.

Using a deployment validation plug-in with WebLogic Server provides the following capabilities:

- rejects invalid application code to protect your domain from malicious applications

- modifies the deployment plan of an application

- tailors the plug-in to suit your specific needs through configuration parameters

- logs messages

The deployment process is the same with or without a deployment validation plug-in, as validation is an optional step. The validation process occurs when deploying an application for the first time, not at server startup for applications that are already deployed or during auto-deployment.

The following sections describe how to validate applications using a deployment validation plug-in with WebLogic Server:

- Configuring the Deployment Validation Plug-In

- Using the Deployment Validation Plug-In

Configuring the Deployment Validation Plug-In

To enable the deployment validation plug-in to run with WebLogic Server, you must add the <deployment-validation-plugin> element to the config.xml file so that the Administration Server can access and use the plug-in classes. The <deployment-validation-plugin> element should contain the fully qualified class name of the plug-in and declare any parameters. You can add the <deployment-validation-plugin> element manually or by using the DeploymentConfigurationMBean available from the DomainMBean.

The following three configuration MBeans support the deployment validation plug-in:

- DeploymentConfigurationMBean
The DeploymentConfigurationMBean contains the DeploymentValidationPlugIn attribute. This attribute is a DeploymentValidationPluginMBean and corresponds to the <deployment-validation-plugin> element, which enables or disables the deployment validation plug-in.

- DeploymentValidationPluginMBean
The DeploymentValidationPluginMBean specifies the deployment validation plug-in configuration information. This MBean includes the FactoryClassname attribute, which is the fully qualified plug-in class name. This class must be available from the Administration Server CLASSPATH. The DeploymentValidationPluginMBean also includes parameters that can be passed to the plug-in. You declare these parameters with the ParameterMBean.

- ParameterMBean
The ParameterMBean specifies the configuration and user parameters for the deployment validation plug-in, including Name, Value, and Description.

Using the Deployment Validation Plug-In

WebLogic Server does not provide the code for the deployment validation plug-in itself, but provides a way to run a plug-in as part of the deployment process to validate and protect your domain from malicious applications. As the domain administrator, you program and compile the code for your domain-specific plug-in according to the needs and specifications of your environment. The plug-in class and other classes it uses need to be available from the Administration Server CLASSPATH.

The deployment validation plug-in must implement the plug-in factory interface, weblogic.deployment.configuration.DeploymentValidationPlugin. The implementation must contain an empty constructor in order to create an instance of the deployment validation plug-in.

The weblogic.deployment.configuration interface includes an initialize method and a validation method. The initialize method provides the parameters that are declared in the <deployment-validation-plugin> element of the config.xml file to the instance of the deployment validation plug-in. The validation method provides the context of the application information and returns the validation result for the application.

The validation result is a class that implements the ValidationResult interface. Implement the isDeploymentValid method to indicate whether the deployment is valid and should proceed. Implement the getException method to provide an exception that should be set as the cause if the deployment is not valid. The argument passed to the validate method is DeploymentValidationContext, which provides access to the proposed application through an instance of SessionHelper. The deployment validation plug-in can then use the getSessionHelper attribute on the DeploymentValidationContext argument to examine the application information that SessionHelper allows.

The DeploymentValidationContext argument also provides access to the DeploymentValidationLogger. The DeploymentValidationLogger logs messages about the actions the plug-in takes to validate the application or the reasons the application is invalid.

If the validation result indicates that the application is valid, the deployment passes and continues the deployment process. If the validation result indicates that the application is invalid, the plug-in sends an exception message describing the reason the application failed to validate, and the application is not deployed. There is no configuration change or evidence of deployment. Since the validation process occurs on the Administration Server, if the deployment fails, the Managed Servers are not aware of the deployment, and you would not have to undeploy or undo any configuration.

3 Configuring Applications for Deployment

This chapter describes how to configure an application or deployable resource for deployment to a WebLogic Server instance using deployment descriptors. Certain elements in these descriptors refer to external objects and may require special handling depending on the server vendor. WebLogic Server uses descriptor extensions—WebLogic Server specific deployment descriptors. The mapping between standard descriptors and WebLogic Server descriptors is managed using DDBeans and DConfigBeans.

This chapter includes the following sections:

- Overview of the Configuration Process

- Types of Configuration Information

- Application Evaluation

- Perform Front-end Configuration

- Customizing Deployment Configuration

- Deployment Preparation

- Session Cleanup

Overview of the Configuration Process

This section provides information on the basic steps a deployment tool must implement to configure an application for deployment:

1. Application Evaluation—Inspection and evaluation of application files to determine the structure of the application and content of the embedded descriptors.

- Initialize a deployment session by obtaining a WebLogicDeploymentManager. See Application Evaluation.

- Create a WebLogicJ2eeApplicationObject or WebLogicDeployableObject to represent the Java EE Configuration of an enterprise application (EAR) or stand-alone module (WAR, EAR, RAR, or CAR). If the object is an EAR, child objects are generated. See Java EE Deployment API standard (JSR-88) at http://jcp.org/en/jsr/detail?id=88 and Create a Deployable Object.

2. 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.

- Create a WebLogicDeploymentConfiguration object to represent the WebLogic Server configuration of an application. This is the first step in creating a deployment plan for this object. See Deployment Configuration.

- Restore existing WebLogic Server configuration values from an existing deployment plan, if available. See Perform Front-end Configuration.

3. Deployment Configuration—Modification of individual WebLogic Server configuration values based on user inputs and the selected WebLogic Server targets.
A deployment tool must provide the ability to modify individual WebLogic Server configuration values based on user inputs and selected WebLogic Server targets. See Customizing Deployment Configuration.

4. Deployment Preparation—Generation of the final deployment plan and preliminary client-side validation of the application.
A deployment tool must have the ability to save the modified WebLogic Server configuration information to a new deployment plan or to variable definitions in an existing Deployment Plan.

Types of Configuration Information

The following sections provide background information on the types of configuration information, how it is represented, and the relationship between Java EE and WebLogic Server descriptors:

- Java EE Configuration

- WebLogic Server Configuration

- Representing Java EE and WebLogic Server Configuration Information

- The Relationship Between Java EE and WebLogic Server Descriptors

Java EE Configuration

The Java EE configuration for an application defines the basic semantics and run-time behavior of the application, as well as the external resources that are required for the application to function. This configuration information is stored in the standard Java EE deployment descriptor files associated with the application, as listed in Table 3-1.

Table 3-1 Standard Java EE Deployment Descriptors

Application or Standalone Module

Java EE Descriptor

Enterprise Application

META-INF/application.xml

Web Application

WEB-INF/web.xml

Enterprise JavaBean

META-INF/ejb.xml

Resource Adapter

META-INF/ra.xml

Client Application Archive

META-INF/application-client.xml

Complete and valid Java EE deployment descriptors are a required input to any application configuration session.

Because the Java EE configuration controls the fundamental behavior of an application, the Java EE descriptors are typically defined only during the application development phase, and are not modified when the application is later deployed to a different environment. For example, when you deploy an application to a testing or production domain, the application's behavior (and therefore its Java EE configuration) should remain the same as when application was deployed in the development domain. See Perform Front-end Configuration for more information.

WebLogic Server Configuration

The WebLogic Server descriptors provide for enhanced features, resolution of external resources, and tuning associated with application semantics. Applications may or may not have these descriptors embedded in the application. The WebLogic Server configuration for an application:

- Binds external resource names to resource definitions in the Java EE deployment descriptor so that the application can function in a given WebLogic Server domain

- Defines tuning parameters for the application containers

- Provides enhanced features for Java EE applications and stand-alone modules

The attributes and values of a WebLogic Server configuration are stored in the WebLogic Server deployment descriptor files, as shown in Table 3-2.

Table 3-2 WebLogic Server Deployment Descriptors

Application or Standalone Module

WebLogic Server Descriptor

Enterprise Application

META-INF/weblogic-application.xml

Web Application

WEB-INF/weblogic.xml

Enterprise JavaBean

META-INF/weblogic-ejb-jar.xml

Resource Adapter

META-INF/weblogic-ra.xml

Client Archive

META-INF/weblogic-appclient.xml

Because different WebLogic Server domains provide different types of external resources and different levels of service for the application, the WebLogic Server configuration for an application typically changes when the application is deployed to a new environment. For example, a production staging domain might use a different database vendor and provide more usable memory than a development domain. Therefore, when moving the application from development to the staging domain, the application's WebLogic Server descriptor values need to be updated in order to make use of the new database connection and available memory.

The primary job of a deployment configuration tool is to ensure that an application's WebLogic Server configuration is valid for the selected WebLogic targets.

Representing Java EE and WebLogic Server Configuration Information

Both the Java EE deployment descriptors and any available WebLogic Server descriptors are used as inputs to the application configuration process. You use the deployment API to represent both the Java EE configuration and WebLogic Server configuration as Java objects.

The Java EE configuration for an application is obtained by creating either a WebLogicJ2eeApplicationObject for an EAR, or a WeblogicDeployableObject for a stand-alone module. (A WebLogicJ2eeApplicationObject contains multiple DeployableObject instances to represent individual modules included in the EAR.)

Each WebLogicJ2eeApplicationObject or WeblogicDeployableObject contains a DDBeanRoot to represent a corresponding Java EE deployment descriptor file. Java EE descriptor properties for EARs and modules are represented by one or more DDBean objects that reside beneath the DDBeanRoot. DDBean components provide standard getter methods to access individual deployment descriptor properties, values, and nested descriptor elements.

DDBeans

DDBeans are described by the javax.enterprise.deploy.model package. These objects provide a generic interface to elements in standard deployment descriptors, but can also be used as an XPath based mechanism to access arbitrary XML files that follow the basic form of the standard descriptors. Examples of such files would be WebLogic Server descriptors and Web services descriptors.

The DDBean representation of a descriptor is a tree of DDBeans, with a specialized DDBean, a DDBeanRoot, at the root of the tree. DDBeans provide accessors for the element name, ID attribute, root, and text of the descriptor element they represent.

The DDBeans for an application are populated by the model plug-in, the tool provider implementation of javax.enterprise.deploy.model. An application is represented by the DeployableObject interface. The WebLogic Server implementation of this interface is a public class, weblogic.deploy.api.model.WebLogicDeployableObject. A WebLogic Server based deployment tool acquires an instance of WebLogicDeployableObject object for an application using the createDeployableObject factory methods. This results in the DDBean tree for the application being created and populated by the elements in the Java EE descriptors embedded in the application. If the application is an EAR, multiple WebLogicDeployableObject objects are created. The root WebLogicDeployableObject, extended as WebLogicJ2eeApplicationObject, would represent the EAR module, with its child WebLogicDeployableObject instances being the modules contained within the application, such as WARs, EJBs, RARs and CARs.

The Relationship Between Java EE and WebLogic Server Descriptors

Java EE descriptors and WebLogic Server descriptors are directly related in the configuration of external resources. A Java EE descriptor defines the types of resources that the application requires to function, but it does not identify the actual resource names to use. The WebLogic Server descriptor binds the resource definition in the Java EE descriptor name to the name of an actual resource in the target domain.

The process of binding external resources is a required part of the configuration process. Binding resources to the target domain ensures that the application can locate resources and successfully deploy.

Java EE descriptors and WebLogic Server descriptors are also indirectly related in the configuration of tuning parameters for WebLogic Server. Although no elements in the standard Java EE descriptors require tuning parameters to be set in WebLogic Server, the presence of individual descriptor files indicates which tuning parameters are of interest during the configuration of an application. For example, although the ejb.xml descriptor does not contain elements related to tuning the WebLogic Server EJB container, the presence of an ejb.xml file in the Java EE configuration indicates that tuning properties can be configured before deployment.

DConfigBeans

DConfigBeans (config beans) are the objects used to convey server configuration requirements to a deployment tool, and are also the primary source of information used to create deployment plans. Config beans are Java Beans and can be introspected for their properties. They also provide basic property editing capabilities.

DConfigBeans are created from information in embedded WebLogic Server descriptors, deployment plans, and input from an IDE deployment tool.

A DConfigBean is potentially created for every weblogic Descriptor element that is associated with a dependency of the application. Descriptors are entities that describe resources that are available to the application, represented by a JNDI name provided by the server.

Descriptors are parsed into memory as a typed bean tree while setting up a configuration session. The DConfigBean implementation classes delegate to the WebLogic Server descriptor beans. Only beans with dependency properties, such as resource references, have a DConfigBean. The root of descriptor always has a DConfigBeanRoot.

Bean Property accessors return a child DConfigBean for elements that require configuration or a descriptor bean for those that do not. Property accessors return data from the descriptor beans.

Modifications to bean properties result in plan overrides. Plan overrides for existing descriptors are handled using variable assignments. If the application does not come with the relevant WebLogic Server descriptors, they are automatically created and placed in an external plan directory. For external deployment descriptors, the change is made directly to the descriptor. Embedded descriptors are never modified on disk.

Application Evaluation

Application evaluation consists of obtaining a deployment manager and a deployable object container for your application. Use the following steps:

1. Obtain a deployment factory class by specifying its name, weblogic.deployer.spi.factories.internal.DeploymentFactoryImpl.

2. Register the factory class with a javax.enterprise.deploy.spi.DeploymentFactoryManager instance.

For instance:

Class WlsFactoryClass =   Class.forname("weblogic.deployer.spi.factories.internal.DeploymentFactoryImpl");
DeploymentFactory myDeploymentFactory =
(DeploymentFactory) WlsFactoryClass.newInstance();
DeploymentFactoryManager.getInstance().registerDeploymentFactory(myDeploymentFactory);

3. Obtain a Deployment Manager

4. Create a Deployable Object

Obtain a Deployment Manager

The following sections provide information on how to obtain a deployment manager:

- Types of Deployment Managers

- Connected and Disconnected Deployment Manager URIs

- Using SessionHelper to Obtain a Deployment Manager

Types of Deployment Managers

WebLogic Server provides a single implementation for javax.enterprise.deploy.spi.DeploymentManager that behaves differently depending on the URI specified when instantiating the class from a factory. WebLogic Server provides two basic types of deployment manager:

- A disconnected deployment manager has no connection to a WebLogic Server instance. Use a disconnected deployment manager to configure an application on a remote client machine. It cannot be used it to perform deployment operations. (For example, a deployment tool cannot use a disconnected deployment manager to distribute an application.)

- A connected deployment manager has a connection to the Administration Server for the WebLogic Server domain, and by a deployment tool to both to configure and deploy applications.

A connected deployment manager is further classified as being either local to the Administration Server, or running on a remote machine that is connected to the Administration Server. The local or remote classification determines whether file references are treated as being local or remote to the Administration Server.

Table 3-3 summarizes deployment manager types.

Table 3-3 WebLogic Server Deployment Manager Usage

Deployment Manager Connectivity

Type

Usage

Notes

Disconnected

n/a

Configuration tools only

Cannot perform deployment operations

Connected

Local

Configuration and deployment tools local to the Administration Server

All files are local to the Administration Server machine

Connected

Remote

Configuration and Deployment for Tools on a remote machine (not on the Administration Server)

Distribution and Deployment operations cause local files to be uploaded to the Administration Server

Connected and Disconnected Deployment Manager URIs

Each DeploymentManager obtained from the WebLogicDeploymentFactory supports WebLogic Server extensions. When creating deployment tools, obtain a specific type of deployment manager by calling the correct method on the deployment factory instance and supplying a string constant defined in weblogic.deployer.spi.factories.WebLogicDeploymentFactory that describes the type of deployment manager required. Connected deployment managers require a valid server URI and credentials to the method in order to obtain a connection to the Administration Server.

Table 3-4 summarizes the method signatures and constants used to obtain the different types of deployment managers.

Table 3-4 URIs for Obtaining a WebLogic Server Deployment Manager

Type of Deployment Manager

Method

Argument

disconnected

getDisconnectedDeploymentManager()

String value of WebLogicDeploymentFactory.LOCAL_DM_URI

connected, local

getDeploymentManager()

URI consisting of:

- WebLogicDeploymentFactory.LOCAL_DM_URI

- Administration Server host name

- Administration Server port

- Administrator username

- Administrator password

connected, remote

getDeploymentManager()

URI consisting of:

- WebLogicDeploymentFactory.REMOTE_DM_URI

- Administration Server host name

- Administration Server port

- Administrator username

- Administrator password

The sample code in Example 3-1 shows how to obtain a disconnected deployment manager.

Example 3-1 Obtaining a Disconnected Deployment Manager

Class WlsFactoryClass = Class.forname("weblogic.deployer.spi.factories.internal.DeploymentFactoryImpl");
DeploymentFactory myDeploymentFactory = (DeploymentFactory) WlsFactoryClass.newInstance();
DeploymentFactoryManager.getInstance().registerDeploymentFactory(myDeploymentFactory);
WebLogicDeploymentManager myDisconnectedManager =
(WebLogicDeploymentManager)myDeploymentFactory.getDisconnectedDeploymentManager(WebLogicDeploymentFactory.LOCAL_DM_URI);

The deployment factory contains a helper method, createUri() to help you form the URI argument for creating connected deployment managers. For example, to create a disconnected remote deployment manager, replace the final line of code with:

(WebLogicDeploymentManager)myDeploymentFactory.getDeploymentManager(myDeploymentFactory.createUri(WebLogicDeploymentFactory.REMOTE_DM_URI, "localhost", "7001", "weblogic", "weblogic"));

Using SessionHelper to Obtain a Deployment Manager

The SessionHelper helper class provides several convenience methods to help you easily obtain a deployment manager without manually creating and registering the deployment factories as shown in Example 3-1. The SessionHelper code required to obtain a disconnected deployment manager consists of a single line:

DeploymentManager myDisconnectedManager = SessionHelper.getDisconnectedDeploymentManager();

You can use the SessionHelper to obtain a connected deployment manager, as shown below:

DeploymentManager myConnectedManager = SessionHelper.getDeploymentManager("adminhost", "7001", "weblogic", "weblogic"));

This method assumes a remote connection to an Administration Server (adminhost). See the Javadocs for more information about SessionHelper.

Create a Deployable Object

The following sections provide information on how to create a deployable object, which is the container your deployment tool uses to deploy applications. Once you have initialized a configuration session by Obtain a Deployment Manager, create a deployable object for your deployment tool in one of the following ways:

- Using the WebLogicDeployableObject class

- Using SessionHelper to obtain a Deployable Object

Using the WebLogicDeployableObject class

The direct approach uses the WebLogicDeployableObject class of the model package as shown below:

WebLogicDeployableObject myDeployableObject = WebLogicDeployableObject.createWebLogicDeployableObject("myAppFileName");

Once the deployable object is created, a configuration can be created for the applications deployment.

Using SessionHelper to obtain a Deployable Object

The SessionHelper helper class provides a convenient method to obtain a deployable object. The SessionHelper code required to obtain a deployable object is shown below:

SessionHelper.setApplicationRoot(root);
WebLogicDeployableObject myDeployableObject = SessionHelper.getDeployableObject();

There is no application specified in the getDeployableObject() call. SessionHelper uses the application in the root directory set by setApplicationRoot(). Once the application root directory is set, SessionHelper can be used to perform other operations, such as explicitly naming the dispatch file location or the deployment plan location.

You can also set the application file name using the setApplication method as shown below:

SessionHelper.setApplication(AppFileName);

This method allows you to continue using SessionHelper independent of the directory structure. The getDeployableObject method returns the application specified.

Perform Front-end Configuration

Front-end configuration involves creating a WebLogicDeploymentPlan and populating it and its associated bean trees with configuration information:

- What is Front-end Configuration

- Deployment Configuration

- Validating a Configuration

What is Front-end Configuration

Front-end configuration phase consists of two logical operations:

- Loading information from a deployment plan to a deployment configuration. If a deployment configuration does not yet exist, this includes creating a WebLogicDeploymentConfiguration object to represent the WebLogic Server configuration of an application. This is the first step in the process of process of creating a deployment plan for this object.

- Restoring any existing WebLogic Server configuration values from an existing deployment plan.

A deployment tool must be able to:

- Extract information from a deployment configuration. The deployment configuration is the active Java object that is used by the Deployment Manager to obtain configuration information. The deployment plan exists outside of the application so that it can be changed without manipulating the application.

A deployment plan is an XML document that contains the environmental configuration for an application and is sometimes referred to as an application's front-end configuration. A deployment plan:

- Separates the environment specific details of an application from the logic of the application.

- Is not required for every application. However, a deployment plan typically exists for each environment an application is deployed to.

- Describes the application structure, such as what modules are in the application.

- Allows developers and administrators to update the configuration of an application without modifying the application archive.

- Contains environment-specific descriptor override information (tunables). By modifying a deployment plan, you can provide environment specific values for tunable variables in an application.

Deployment Configuration

The server configuration for an application is encapsulated in the javax.enterprise.deploy.spi.DeploymentConfiguration interface. A DeploymentConfiguration provides an object representation of a deployment plan. A DeploymentConfiguration is associated with a DeployableObject using the DeploymentManager.createConfiguration method. Once a DeploymentConfiguration object is created, a DConfigBean tree representing the configurable and tunable elements contained in any and all WebLogic Server descriptors is available. If there are no WebLogic Server descriptors for an application, then a DConfigBean tree is created using available default values. Binding properties that have no defaults are left unset.

When creating a deployment tool, you must ensure that the DConfigBean tree is fully populated before the tool distributes an application.

Example Code

The following code provides an example on how to populate DConfigBeans:

Example 3-2 Example Code to Populate DConfigBeans

public class DeploymentSession {
DeploymentManager dm;
DeployableObject dObject = null;
DeploymentConfiguration dConfig = null;
Map beanMap = new HashMap();
.
.
.
// Assumes app is a Web app.
public void initializeConfig(File app) throws Throwable {
/**
* Init the wrapper for the DDBeans for this module. This example assumes
* it is using the WLS implementation of the model api.
*/
dObject= WebLogicDeployableObject.createDeployableObject(app);
//Get basic configuration for the module
dConfig = dm.createConfiguration(dObject);
/**
* At this point the DeployableObject is populated. Populate the
* DeploymentConfigurationbased on its content.
* We first ask the DeployableObject for its root.
*/
DDBeanRoot root = dObject.getDDBeanRoot();
/**
* The root DDBean is used to start the process of identifying the
* necessary DConfigBeans for configuring this module.
*/
System.out.println("Looking up DCB for "+root.getXpath());
DConfigBeanRoot rootConfig = dConfig.getDConfigBeanRoot(root);
collectConfigBeans(root, rootConfig);
/**
* The DeploymentConfiguration is now initialized, although not necessarily
* completely setup.
*/
FileOutputStream fos = new FileOutputStream("test.xml");
dConfig.save(fos);

}

// bean and dcb are a related DDBean and DConfigBean.
private void collectConfigBeans(DDBean bean, DConfigBean dcb) throws Throwable{
DConfigBean configBean;
DDBean[] beans;
if (dcb == null) return;
/**
* Maintain some sort of mapping between DDBeans and DConfigBeans
* for later processing.
*/
beanMap.put(bean,dcb);
/**
* The config bean advertises xpaths into the web.xml descriptor it
* needs to know about.
*/
String[] xpaths = dcb.getXpaths();
if (xpaths == null) return;
/**
* For each xpath get the associated DDBean and collect its associated
* DConfigBeans. Continue this recursively until we have all DDBeans and
* DConfigBeans collected.
*/
for (int i=0; i<xpaths.length; i++) {
beans = bean.getChildBean(xpaths[i]);
for (int j=0; j<beans.length; j++) {
/**
* Init the DConfigBean associated with each DDBean
*/
System.out.println("Looking up DCB for "+beans[j].getXpath());
configBean = dcb.getDConfigBean(beans[j]);
collectConfigBeans(beans[j], configBean);
}
}

This example merely iterates through the DDBean tree, requesting the DConfigBean for each DDBean to be instantiated.

DeploymentConfiguration objects may be persisted as deployment plans using DeploymentConfiguration.save(). A deployment tool may allow the user to import a saved deployment plan into the DeploymentConfiguration object instead of populating it from scratch. DeploymentConfiguration.restore() provides this capability. This supports the idea of having a repository of deployment plans for an application, with different plans being applicable to different environments.

Similarly the DeploymentConfiguration may be pieced together using partial plans, which were presumably saved in a repository from a previous configuration session. A partial plan maps to a module-root of a DConfigBean tree. DeploymentConfiguration.saveDConfigBean() and DeploymentConfiguration.restoreDConfigBean() provide this capability.

Parsing of the WebLogic Server descriptors in an application occurs automatically when a DeploymentConfiguration is created. The descriptors ideally conform to the most current schema. For older applications that include descriptors based on WebLogic Server 8.1 and earlier DTDs, a transformation is performed. Old descriptors are supported but they cannot be modified using a deployment plan. Therefore, any DOCTYPE declarations must be converted to name space references and element specific transformations must be performed.

Reading In Information with SessionHelper

SessionHelper.initializeConfiguration processes all standard and WebLogic Server descriptors in the application.

Prior to invoking initializeConfiguration, you can specify an existing deployment plan to associate with the application using the SessionHelper.setPlan() method. With a plan set, you can read in a deployment plan using the DeploymentConfiguration.restore() method. In addition, the DeploymentConfiguration.initializeConfiguration() method automatically restores configuration information once a plan is set.

When initiating a configuration session with the SessionHelper class, you can easily initiate and fill a deploymentConfiguration object with deployment plan information as illustrated below:

DeploymentManager dm = SessionHelper.getDisconnectedDeploymentManager();
SessionHelper helper = SessionHelper.getInstance(dm);
// specify location of archive
helper.setApplication(app);
// specify location of existing deployment plan
helper.setPlan(plan);
// initialize the configuration session
helper.initializeConfiguration();
DeploymentConfiguration dc = helper.getConfiguration();

The above code produces the deployment configuration and its associated WebLogicDDBeanTree.

Validating a Configuration

Validation of the configuration occurs mostly during the parsing of the descriptors which occurs when an application's descriptors are processed. Validation consists of ensuring the descriptors are valid XML documents and that the descriptors conform to their respective schemas.

Customizing Deployment Configuration

The Customizing Deployment Configuration phase involves modifying individual WebLogic Server configuration values based on user inputs and the selected WebLogic Server targets.

- Modifying Configuration Values

- Targets

- Application Naming

Modifying Configuration Values

In this phase, a configuration is only as good as the descriptors or pre-existing plan associated with the application. The DConfigBeans are designed as Java Beans and can be introspected, allowing a tool to present their content in some meaningful way. The properties of a DConfigBean are, for the most part, those that are configurable. Key properties (those that provide uniqueness) are also exposed. Setters are only exposed on those properties that can be safely modified. In general, properties that describe application behavior are not modifiable. All properties are typed as defined by the descriptor schemas.

The property getters return subordinate DConfigBeans, arrays of DConfigBeans, descriptor beans, arrays of descriptor beans, simple values (primitives and java.lang objects), or arrays of simple values. Descriptor beans represent descriptor elements that, while modifiable, do not require DConfigBean features, meaning there are no standard descriptor elements they are directly related to. Editing a configuration is accomplished by invoking the property setters.

The Java JSR-88 DConfigBean class allows a tool to access beans using the getDConfigBean(DDBean) method or introspection. The former approach is convenient for a tool that presents the standard descriptor based on the DDBeans in the application's DeployableObject and provides direct access to each DDBean's configuration (its DConfigBean). This provides configuration of the essential resource requirements an application may have. Introspection allows a tool to present the application's entire configuration, while highlighting the required resource requirements.

Introspection is required in both approaches in order to present or modify descriptor properties. The difference is in how a tool presents the information:

- Driven by standard descriptor content or

- WebLogic Server descriptor content.

A system of modifying configuration information must include a user interface to ask for configuration changes. See Example 3-3.

Example 3-3 Code Example to Modify Configuration Information

.
.
.
// Introspect the DConfigBean tree and ask for input on properties with setters
private  void processBean(DConfigBean dcb) throws Exception {
if (dcb instanceof DConfigBeanRoot) {
System.out.println("Processing configuration for descriptor: "+dcb.getDDBean().getRoot().getFilename());
}
// get property descriptor for the bean
BeanInfo info =
Introspector.getBeanInfo(dcb.getClass(),Introspector.USE_ALL_BEANINFO);
PropertyDescriptor[] props = info.getPropertyDescriptors();
String bean = info.getBeanDescriptor().getDisplayName();
PropertyDescriptor prop;
for (int i=0;i<props.length;i++) {
prop = props[i];
// only allow primitives to be updated
Method getter = prop.getReadMethod();
if (isPrimitive(getter.getReturnType())) // see isPrimitive method below
{
writeProperty(dcb,prop,bean); //see writeProperty method below
}
// recurse on child properties
Object child = getter.invoke(dcb,new Object[]{});
if (child == null) continue;
// traversable if child is a DConfigBean.
Class cc = child.getClass();
if (!isPrimitive(cc)) {
if (cc.isArray()) {
Object[] cl = (Object[])child;
for (int j=0;j<cl.length;j++) {
if (cl[j] instanceof DConfigBean) processBean((DConfigBean) cl[j]);
}
} else {
if (child instanceof DConfigBean) processBean((DConfigBean) child);
}
}
}
}

// if the property has a setter then invoke it with user input
private void writeProperty(DConfigBean dcb, PropertyDescriptor prop, String bean)
throws Exception {
Method getter = prop.getReadMethod();
Method setter = prop.getWriteMethod();
if (setter != null) {
PropertyEditor pe =
PropertyEditorManager.findEditor(prop.getPropertyType());
if (pe == null &&
String[].class.isAssignableFrom(getter.getReturnType())) pe =
new StringArrayEditor();  // see StringArrayEditor class below
if (pe != null) {
Object oldValue = getter.invoke(dcb,new Object[0]);
pe.setValue(oldValue);
String val =
getUserInput(bean,prop.getDisplayName(),pe.getAsText());
// see getUserInput method below
if (val == null || val.length() == 0) return;
pe.setAsText(val);
Object newValue = pe.getValue();
prop.getWriteMethod().invoke(dcb,new Object[]{newValue});
}
}
}

private String getUserInput(String element, String property, String curr) {
try {
System.out.println("Enter value for "+element+"."+property+". Current value is: "+curr);
return br.readLine();
} catch (IOException ioe) {
return null;
}
}
// Primitive means a java primitive or String object here
private  boolean isPrimitive(Class cc) {
boolean prim = false;
if (cc.isPrimitive() || String.class.isAssignableFrom(cc)) prim = true;
if (!prim) {
// array of primitives?
if (cc.isArray()) {
Class ccc = cc.getComponentType();
if (ccc.isPrimitive() || String.class.isAssignableFrom(ccc)) prim = true;
}
}
return prim;
}

/**
* Custom editor for string arrays. Input text is converted into tokens using
* commas as delimiters
*/
private class StringArrayEditor extends PropertyEditorSupport {
String[] curr = null;

public StringArrayEditor() {super();}

// comma separated string
public String getAsText() {
if (curr == null) return null;
StringBuffer sb = new StringBuffer();
for (int i=0;i<curr.length;i++) {
sb.append(curr[i]);
sb.append(',');
}
if (curr.length > 0) sb.deleteCharAt(sb.length()-1);
return sb.toString();
}

public Object getValue() { return curr; }

public boolean isPaintable() { return false; }

public void setAsText(String text) {
if (text == null) curr = null;
StringTokenizer st = new StringTokenizer(text,",");
curr = new String[st.countTokens()];
for (int i=0;i<curr.length;i++) curr[i] = new String(st.nextToken());
}

public void setValue(Object value) {
if (value == null) {
curr = null;
} else {
String[] v = (String[])value; // let caller handle class cast issues
curr = new String[v.length];
for (int i=0;i<v.length;i++) curr[i] = new String(v[i]);
}
}
}
.
.
.

Beyond the mechanics of the rudimentary user interface, any interface that enables changes to the configuration by an administrator or user can use the property setters shown in Example 3-3.

Targets

Targets are associated with WebLogic Servers, clusters, Web servers, virtual hosts and JMS servers. See weblogic.deploy.api.spi.WebLogicTarget and Support for Querying WebLogic Target Types.

Application Naming

In WebLogic Server, application names are provided by a deployment tool. Names of modules contained within an application are based on the associated archive or root directory name of the modules. These names are persisted in the configuration MBeans constructed for the application.

In Java EE deployment there is no mention of the configured name of an application or its constituent modules, other than in the TargetModuleID object. Yet TargetModuleIDs exist only for applications that have been distributed to a WebLogic Server domain. Hence there is a need to represent application and module names in a deployment tool prior to distribution. This representation should be consistent with the names assigned by the server when the application is finally distributed.

Your deployment tool plug-in must construct a view of an application using the DeployableObject and J2eeApplicationObject classes. These classes represent stand-alone modules and EARs, respectively. Each of these classes is directly related to a DDBeanRoot object. When presented with a distribution where the name is not configured, the deployment tool must create a name for the distribution. If the distribution is a File object, use the filename of the distribution. If an archive is offered as an input stream, a random name is used for the root module.

Deployment Preparation

The deployment preparation phase involves saving the resulting plan from a configuration session. Use the DeploymentConfiguration.save() method (a standard Java EE Deployment API method). You can also use the SessionHelper.savePlan() method to save a new copy of deployment plan along with any external documents in the plan directory.

The DeploymentConfiguration.save methods creates an XML file based on the deployment plan schema that consists of a serialization of the current collection of DConfigBeans, along with any variable assignments and definitions. DConfigBean trees are always saved as external descriptors. These descriptors are only be saved if they do not already exist in the application archive or the external configuration area, meaning a save operation does not overwrite existing descriptors. The DeploymentConfiguration.saveDConfigBean method does overwrite files. This is does not mean that any changes made to a configuration are lost, it means that they are handled using variable assignments.

As noted before, the DeploymentConfiguration.restore methods are used to create configuration beans based on a previously saved deployment plan (see Perform Front-end Configuration). You can restore an entire collection of configuration beans or you can restore a subset of the configuration beans. It is also possible to save or restore the configuration beans for a specific module in an application.

Session Cleanup

Temporary files are created during a configuration session. Archives are exploded into the temp area and can only be removed after session configuration is complete. There is no standard API defined to close out a session. Use the close() methods to WebLogicDeployableObject and WebLogicDeploymentConfiguration. SessionHelper.close() to clean up after a session. If you do not clean up after closing sessions, the disk containing your temp directories may fill up over time.

4 Performing Deployment Operations

This chapter describes application deployment in WebLogic Server. Application deployment distributes the information created inConfiguring Applications for Deployment to the Administration Server for server-side processing and application startup. Your deployment tool must be able to successfully complete the deployment operations outlined in this chapter.

This chapter includes the following sections:

- Register Deployment Factory Objects

- Allocate a DeploymentManager

- Deployment Processing

- Production Redeployment

- Progress Reporting

- Target Objects

Register Deployment Factory Objects

Your deployment tool must instantiate and register the DeploymentFactory objects it uses. You can implement your own mechanism for managing DeploymentFactory objects. WebLogic Server DeploymentFactory objects are advertised in a manifest file stored in the wldeploy.jar file. The manifest contains entries of the fully qualified class names of the factories, separated by whitespace. For example, if you assume that the DeploymentFactory- objects reside in a fixed location and are included in the deployment tool classpath, the deployment tool registers any DeploymentFactory objects it recognizes at startup. See Example 4-1.

Example 4-1 Registered Deployment Factory in the Manifest File

MANIFEST.MF:
Manifest-version: 1.0
Implementation-Vendor: BEA Systems
Implementation-Title: WebLogic Server 9.0 Mon May 29 08:16:47 PST 2006 221755
Implementation-Version: 9.0.0.0
J2EE-DeploymentFactory-Implementation-Class:
weblogic.deploy.spi.factories.DeploymentFactoryImpl
.
.
.

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.

Allocate a DeploymentManager

Your deployment tool must allocate a DeploymentManager from a DeploymentFactory, which is registered with the DeploymentFactoryManager class, in order to perform deployment operations. In addition to configuring an application for deployment, the DeploymentManager is responsible for establishing a connection to a Java EE server. The DeploymentManager implementation is accessed using a DeploymentFactory.

The following sections provide information on how a DeploymentManager connects to a server instance:

- Getting a DeploymentManager Object

- Understanding DeploymentManager URI Implementations

- Server Connectivity

Getting a DeploymentManager Object

Use the DeploymentFactory.getDeploymentManager method to get a DeploymentManager object. This method takes a URI, user ID and password as arguments. The URI has the following patterns:

- deployer:WebLogic<:host:port>

- deployer:WebLogic.remote<:host:port>

- deployer:WebLogic.authenticated<:host:port>

When connecting to an Administration Server, the URI must also include the host and port, such as deployer:WebLogic:localhost:7001. See Understanding DeploymentManager URI Implementations.

The following provides additional information on DeploymentManager arguments:

- When obtaining a disconnected DeploymentManager, you do not need to include the host:port because there is no connection to an Administration Server. For example, the URI can be deployer:WebLogic.

- The user ID and password arguments are ignored if the deployment tool uses a pre-authenticated DeploymentManager.

- You can access the URI of any DeploymentManager implementation using the DeploymentFactory.getUris() method. getUris is an extension of DeploymenFactory.

Understanding DeploymentManager URI Implementations

Depending on the URI specified during allocation, the DeploymentManager object will have one of the following characteristics:

- deployer:WebLogic: The DeploymentManager is running locally on an Administration Server and any files referenced during the deployment session are treated as if they are local to the Administration Server.

- deployer:WebLogic.remote: The DeploymentManager is running remotely to the WebLogic Server Administration Server and any files referenced during the deployment session are treated as being remote to the Administration Server and may require uploading. For example, a distribute operation includes 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 is running locally on a WebLogic Administration Server and any files referenced during the deployment session are treated as if they are local to the Administration Server.

You can explicitly force the uploading of application files by using the WebLogicDeploymentManager method enableFileUploads() method.

Server Connectivity

DeploymentManagers are either connected or disconnected. Connected DeploymentManagers imply a connection to a WebLogic Server Administration Server. This connection is maintained until it is explicitly disconnected or the connection is lost. If the connection is lost, the DeploymentManager reverts to a disconnected state.

Explicitly disconnecting a DeploymentManager is accomplished using the DeploymentManager.release method. There is no corresponding method for reconnecting the DeploymentManager. Instead the deployment tool must allocate a new DeploymentManager.

Note:

Allocating a new DeploymentManager does not affect any configuration information being maintained within the tool through a DeploymentConfiguration object.

Deployment Processing

Most of the functional components of a DeploymentManager are defined in the Java EE Deployment API specification. However, Oracle has extended the DeploymentManager interface with the capabilities required by existing WebLogic Server-based deployment tools. Oracle WebLogic Server deployment extensions are documented at weblogic.deploy.api.spi.WebLogicDeploymentManager.

The JSR-88 programming model revolves around employing TargetModuleID objects (TargetModuleIDs) and ProgressObject objects. In general, 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 deployment operations and tracks their progress. A deployment tool needs to query progress using a ProgressObject returned for each operation. When the ProgressObject indicates the operation is completed or failed, the operation is done.

The following sections provide an overview of WebLogic DeploymentManager features:

- DeploymentOptions

- Distribution

- Application Start

- Application Deploy

- Application Stop

- Undeployment

DeploymentOptions

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 standard behavior. Some of the options supported in this release are:

- admin (test) mode

- Retirement Policy

- Staging

See DeploymentOptions Javadoc.

Distribution

Distribution of new applications results in:

- the application archive and plan is staged on all targets.

- the application being configured into the domain.

Note:

Redistribution honors the staging mode already configured for an application.

The standard distribute operations does not support version naming. WebLogic Server provides WebLogicDeploymentManager to extend the standard with a distribute operation that allows you to associate a version name with an 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 represents the application's module availability on each target.

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

If you use the distribute(Target[],InputStream,InputStream) method to distribute an application, the archive and plan represented by the input streams are copied from the streams into a temporary area prior to deployment which impacts performance.

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) looks like:

myapp on serverx (implied)
webapp1 on serverx
webapp2 on serverx

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

To start webapp1, module level control is required. Configure module level control 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. Web applications may be deployed in normal or administration (test) mode. You can specify application staging using the DeploymentOptions argument. deploy operations use TargetModuleIDs instead of Targets for targeting, 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.

Oracle provides versioning support, allowing you to stop a specific version of an application. The stop operation does not modify the application configuration. See Version Support.

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 you to remove static pages. See Version Support.

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 and provides the following additional support:

- In-Place Redeployment

- Module Level Targeting

- Retirement Policy

- Version Support

- Administration (Test) Mode

In-Place Redeployment

The in-place redeployment strategy works by immediately replacing a running application's deployment files with updated deployment files, such as:

- Partial redeployment which involves adding or replacing specific files in an existing deployment.

- Updating a configuration using a redeployment of a deployment plan

Module Level Targeting

A DeploymentManager implements the JSR-88 specification and restricts operations to root modules. Module level control is provided by manually constructing a module specific TargetModuleID hierarchy using WebLogicDeploymentManager.createTargetModuleID

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) The 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:

The old version is not retired if the new version is in administration (test) mode.

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 without interruption in service to its current clients. Details on deploying side-by-side versions can be found in Redeploying Applications in a Production Environment in Deploying Applications to Oracle WebLogic Server.

Administration (Test) Mode

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

Progress Reporting

Use ProgressObjects to determine deployment state of your applications. 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 connection with the deployment framework, allowing it to provide a deployment tool with up-to-date deployment status. The 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 are 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.

Example 4-2 shows how a ProgressObject can be used to wait for a deployment to complete:

Example 4-2 Example Code to Wait for Completion of a Deployment

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

Target Objects

The following sections provide information on how to target objects:

- Module Types

- Extended Module Support

- Recognition of Target Types

- TargetModuleID Objects

- WebLogic Server TargetModuleID Extensions

- Example Module Deployment

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.

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 as 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 application may include a webservers.xml descriptor. If present, the module is automatically configured with the WebLogic Server equivalent descriptor for configuring Web services as secondary descriptors. The deployment plan includes these descriptors as part of the module, not as a separate module.

CMP

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

JDBC

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

If a JDBC module is part of an EAR, its configuration overrides 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 with no archive. If the module is part of an EAR, the JMS descriptors are specified in weblogic-application.xml as configurable properties. JMS modules are 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 incorporated in the deployment plan as part of the EAR, not as separate modules.

INTERCEPT

Intercept modules are described by a single deployment descriptor with no archive. If the module is part of an EAR, the Intercept descriptors are specified in weblogic-application.xml as configurable properties. Intercept modules are 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 incorporated in the deployment plan as part of the EAR, not as separate modules.

Recognition of Target Types

The Java EE Deployment API specification's definition of a target does not include any notion of its type. WebLogic Server supports standard modules and Oracle-specific module types as valid deployment targets. Target support is provided by the weblogic.deploy.api.spi.WebLogicTarget and weblogic.deploy.api.spi.WebLogicTargetType classes. See Module Types.

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 stand-alone 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 may have child TargetModuleIDs (sub-modules) as dictated by the JMS deployment descriptor. These may be children of an embedded module or the root module. Therefore, JMS modules can have three levels of TargetModuleIDs for an application.

Typically, you get TargetModuleIDs in a deployment operation or one of the DeploymentManager.get*Modules() methods. These operations provide TargetModuleIDs based on the existing configuration. In certain scenarios where more specific targeting is desired than is currently defined in the configuration, you may use the createTargetModuleID method. This method creates a root TargetModuleID that is specific to a module or sub-module within the application. This TargetModuleID can then be used in any deployment operation. For operations that include the application archive, such as deploy(), using one of these TargetModuleIDs may result in the application being reconfigured. For example:

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

Example Module Deployment

Consider the deployment of a stand-alone JMS module, one that employs sub-modules. The module is defined by the file, simple-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 a location where you could 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);

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2017, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.

Private Alpha and Beta Draft Documentation Notice

If this document is in private preproduction status:

The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your beta trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.