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:

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

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

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:

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

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

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

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

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.

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

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.