The Jakarta Deployment API specification (see https://jakarta.ee/specifications/deployment/1.7/) 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
  

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. For more information, see the weblogic.Deployer Command-Line Reference.

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 https://javaee.github.io/javaee-spec/javadocs/javax/enterprise/deploy/spi/DeploymentManager.html) for use with the weblogic.deploy.api.spi. See Application Evaluation and the Jakarta Deployment API specification at https://jakarta.ee/specifications/deployment/1.7/.

• You need to create your own deployment interface instead of using the WebLogic Remote Console or weblogic.Deployer. In this case, you may implement some or all WebLogic Deployment API Deployment Phases using the WebLogic Deployment API classes and interfaces.

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

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

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

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.

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.

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.

This package contains the interfaces used to represent the Jakarta 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 Jakarta EE application, with extensions to support applications residing in an application installation directory.

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

Jakarta Deployment API dictates that Jakarta EE deployment descriptors be accessed through a DeployableObject (see https://javaee.github.io/javaee-spec/javadocs/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 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 Jakarta Deployment API specification, see https://jakarta.ee/specifications/deployment/1.7/), 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.

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.

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

Targets, which were not implemented in the Jakarta 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 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 Jakarta Deployment API specification (see https://jakarta.ee/specifications/deployment/1.7/) interfaces. They provide easy access to deployment operations provided by the WebLogic Deployment API.

Although configuration sessions can be controlled from a WebLogicDeploymentManager directly, SessionHelper provides simplified methods. If your tools code directly to the WebLogic Server Jakarta 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.

weblogic.PlanGenerator creates a deployment plan template based on the Jakarta 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 Remote 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 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 1-2 summarizes the supported deployment option names and values.

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

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.

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

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.

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.