Deploying Applications to WebLogic Server

Exporting an Application for Deployment to New Environments

The following sections describe how to export an application's WebLogic Server deployment configuration to a custom deployment plan, which helps administrators easily deploy the application into non-development environments:

Overview of the Export Process

Exporting an application's deployment configuration is the process of creating a custom deployment plan that administrators can use for deploying the application into new WebLogic Server environments. You distribute both the application deployment files and the custom deployment plan to deployers (for example, testing, staging, or production administrators) who use the deployment plan as a blueprint for configuring the application for their environment.

An administrator can install both the application and the custom deployment plan using the Administration Console, which validates the deployment plan and indicates when specific configuration properties need to be filled in before deployment.

See the Deployment Plan Reference and Schema for more information about deployment plans.

Goals for Exporting a Deployment Configuration

The primary goals in exporting a deployment configuration are:

To expose the external resources requirements of the application as null variables in a deployment plan. Any external resources required by the application are subject to change when the application is deployed to a different environment. For example, the JNDI names of datasources used in your development environment may be different from those used in testing or production. Exposing those JNDI names as variables makes it easy for deployers to use available resources or create required resources when deploying the application. Using empty (null) variables forces the deployer to fill in a valid resource name before the application can be deployed.

To expose additional configurable properties, such as tuning parameters, as variables in a deployment plan. Certain tuning parameters that are acceptable in a development environment may be unacceptable in a production environment. For example, it may suffice to accept default or minimal values for EJB caching on a development machine, whereas a production cluster would need higher levels of caching to maintain acceptable performance. Exporting selected tunables as deployment plan variables helps an administrator focus on important tuning parameters when deploying the application. The Administration Console highlights tuning parameters exposed as variables in a deployment plan, but does not require a deployer to modify them before deployment.

Tools for Exporting a Deployment Configuration

BEA WebLogic Server provides the following tools to help you export an application's deployment configuration:

weblogic.PlanGenerator creates a template deployment plan with null variables for selected categories of WebLogic Server deployment descriptors. This tool is recommended if you are beginning the export process and you want to create a template deployment plan with null variables for an entire class of deployment descriptors (see Understanding Deployment Property Classifications). You typically need to manually modify the deployment plan created by weblogic.PlanGenerator, either manually or using the Administration Console, to delete extraneous variable definitions or add variables for individual properties.
The Administration Console updates or creates new deployment plans as necessary when you change configuration properties for an installed application. You can use the Administration Console to generate a new deployment plan or to add or override variables in an existing plan. The Administration Console provides greater flexibility than weblogic.PlanGenerator, because it allows you to interactively add or edit individual deployment descriptor properties in the plan, rather than export entire categories of descriptor properties.

Understanding Deployment Property Classifications

Each WebLogic Server deployment descriptor property (for all J2EE module descriptors as well as JDBC, JMS, and WLDF application modules) is formally classified into one of the following four categories:

Non-configurable properties cannot be changed by an administrator during a deployment configuration session. Non-configurable properties are used to describe application behavior that is fundamental to the basic operation of the application. For example, the ejb-name property is categorized as non-configurable, because changing its value also requires changing the EJB application code.
Dependency properties resolve resource dependencies defined in the J2EE deployment descriptors. For example, if the J2EE descriptor for an EJB defines a datasource name that is used within the EJB code, the WebLogic Server descriptor uses a dependency property to bind the datasource name to an actual datasource configured in the target WebLogic Server domain.
Declaration properties declare a resource that other applications can use. For example, the JNDI name of an EJB declares the EJB name that other applications or modules would use to access the EJB.
Configurable properties are the remaining properties not classified as dependency or declaration properties. Generally configurable properties enable or configure WebLogic Server-specific features and tuning parameters for the deployed application. For example, the WebLogic Server descriptor for an EJB might define the number of EJBs that WebLogic Server caches in memory.

These categories are used during the configuration export process to select properties to expose as variables in the deployment plan. For example, you can generate a new deployment plan containing variable definitions for all properties tagged as "dependencies" in an application's WebLogic Server deployment descriptors. The variables can then be easily changed by an administrator deploying the application to an environment having different resource names.

All changeable descriptor properties (dependency, declaration, and configurable properties) are further classified as either dynamic or non-dynamic properties. Dynamic properties can be changed in a deployed application without requiring you to redeploy for the changes to take effect. Non-dynamic properties can be changed but require redeployment for the changes to take effect. The Administration Console identifies non-dynamic properties as a reminder for when redeployment is necessary.

Steps for Exporting an Application's Deployment Configuration

Exporting an application's deployment configuration typically involves the following procedures:

Staging Application Files for Export

Generating a Template Deployment Plan using weblogic.PlanGenerator

Customizing the Deployment Plan Using the Administration Console

Manually Customizing the Deployment Plan

Validating the Exported Deployment Configuration

The sections that follow describe each procedure in detail.

Staging Application Files for Export

BEA recommends placing application files into an application installation directory before exporting the deployment configuration. When using an installation directory, generated configuration files, such as the deployment plan, are automatically copied to the \plan subdirectory during export.

To create an application installation directory:

Create a top-level installation directory for your application:

mkdir c:\exportapps\myApplication

Create \app and \plan subdirectories:

mkdir c:\exportapps\myApplication\app

mkdir c:\exportapps\myApplication\plan

Copy the complete application to be exported into the \app subdirectory. The application can be either in archive or exploded archive form:

cp -r c:\dev\myApplication c:\exportapps\myApplication\app

The \app directory must include the full application distribution, and can include the WebLogic Server descriptor files that you use for deployment to your development environment.

If you choose not to use an installation directory when exporting an application, BEA recommends using the -plan option to weblogic.PlanGenerator to specify the location and filename of the generated plan. By default, weblogic.PlanGenerator stores generated files in the TEMP/weblogic-install/application_name/config directory, where TEMP is the temporary directory for your environment. For Windows platforms, this means generated configuration files are stored in C:\Documents and Settings\username\Local Settings\Temp\weblogic\install\myApplication.ear\config. Use the -plan option to place generated files in a known location.

Generating a Template Deployment Plan using weblogic.PlanGenerator

The weblogic.PlanGenerator tool provides a quick and easy way to generate a template deployment plan with null variables for an entire category of deployment descriptors. BEA recommends using weblogic.PlanGenerator to generate a new deployment plan with null variables for all of an application's dependencies. This ensures that all global resources required for an application can be easily configured by administrators who must deploy the application in a new environment.

When using an application staged in an installation root directory, the basic syntax for using weblogic.PlanGenerator is:

java weblogic.PlanGenerator -root install_root category

category specifies the category of WebLogic Server deployment descriptors for which you want to create variables. (See Understanding Deployment Property Classifications for a description of each category.) For the purposes of generating a template deployment plan, you should usually use only the -dependencies option, which is the default option, as this limits variables to external resources required by the application.

Note: The -dependencies option creates null variables for every possible dynamically-configurable deployment property, which can result in a large number of variable definitions that may not be required for your application. The -declarations option is generally not required, because declaration properties are typically associated with the basic functioning of the application and should not be changed before deployment to a new environment.

For example:

java weblogic.PlanGenerator -root c:\exportapps\myApplication -dependencies

java weblogic.PlanGenerator -root c:\exportapps\myApplication

With the above commands, which are synonymous because -dependencies is the default option so you are not required to specify it in your weblogic.PlanGenerator command, weblogic.PlanGenerator inspects all J2EE deployment descriptors in the selected application, and creates a deployment plan with null variables for all relevant WebLogic Server deployment properties that configure external resources for the application. Using this template deployment plan, an administrator using the Administration Console would be directed to assign valid resource names for each null variable before the application could be deployed.

Customizing the Deployment Plan Using the Administration Console

The template deployment plan generated in Generating a Template Deployment Plan using weblogic.PlanGenerator contains only those deployment properties that resolve external dependencies for the application. You will generally customize the template plan to add one or more WebLogic Server tuning properties for the application. The Administration Console enables you to easily add deployment plan variables for individual deployment descriptor properties as needed. To customize a deployment plan using the Administration Console:

Install the Exported Application and Template Deployment Plan

Add Variables for Selected Tuning Properties

Retrieve the Customized Deployment Plan

Install the Exported Application and Template Deployment Plan

To modify a deployment configuration using the Administration Console, you must first install the application and existing deployment plan as described in Install applications and modules in Administration Console Online Help.

Add Variables for Selected Tuning Properties

After installing the exported application, follow the steps in Update a deployment plan in Administration Console Online Help to add new tuning properties to the deployment plan:

Retrieve the Customized Deployment Plan

When you modify an application's deployment configuration using the Administration Console, your changes to deployment properties are stored in a WebLogic Server deployment plan and/or in generated WebLogic Server deployment descriptor files. If you modified only those deployment properties that were already defined as variables in the application's deployment plan, your changes are written back to a new version of the plan file. If you modified deployment properties that were not specified in the deployment plan, new variables are added to the plan.

When you configure an application that was installed from an installation directory, the Administration Console stores generated configuration files in the plan subdirectory by default.

Manually Customizing the Deployment Plan

In some cases you may need to edit a custom deployment plan manually, using a text editor. This may be necessary for the following reasons:

You want to remove an existing deployment plan variable.
You want to assign a null value to a generated variable in the plan.

Note: You cannot use the Administration Console to remove variable definitions from the deployment plan or assign a null value for a deployment property.

See Deployment Plan Schema before manually editing deployment plan entries.

Removing Variables from a Deployment Plan

The variable-definition stanza in a deployment plan defines the names and values of variables used for overriding WebLogic Server deployment descriptor properties. The module-override element may contain one or more variable-assignment elements that define where a variable is applied to a given deployment descriptor. To remove a variable from a deployment plan, use a text editor to delete:

the variable definition from the variable-definition stanza
all variable-assignment elements that reference the deleted variable.

Assigning Null Variables to Require Administrator Input

To assign a null value to an existing variable definition, simply change any text value that is present in the value subelement in the variable element to <value xsi:nil="true"></value> where the xsi namespace is defined as: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance". For example, change:

...
  <variable-definition>
    <variable>
      <name>SessionDescriptor_InvalidationIntervalSecs_11029744771850</name>
      <value>80</value>
    </variable>
  </variable-definition>
...

to:

...
  <variable-definition>
    <variable>
      <name>SessionDescriptor_InvalidationIntervalSecs_11029744771850</name>
      <value xsi:nil="true"></value>
    </variable>
  </variable-definition>
...

Validating the Exported Deployment Configuration

The Administration Console automatically validates the deployment configuration for a newly-installed application or module. To validate a custom deployment plan that you have created during the export process:

Follow the steps under Install the Exported Application and Template Deployment Plan to install the application or module with the final version of the custom deployment plan. The Administration Console automatically uses a deployment plan named plan.xml in the plan subdirectory of an installation directory, if one is available.

On the Summary of Deployments page, select the name of the application or module that you installed.

Select the Deployment Plan > Dependencies tab.

Verify that the dependencies configured for the deployed module are valid for the selected target servers.

Best Practices for Exporting a Deployment Configuration

Keep in mind these best practices when exporting an application's deployment configuration:

The primary goal for exporting an application is to create null variables for all of an application's external resource dependencies. This ensures that deployers have the ability to assign resource names based on resources available in their target environment.
Use weblogic.PlanGenerator only for exporting resource dependencies. Using weblogic.PlanGenerator to export other categories of deployment descriptor properties generally results in too many variables in the deployment plan.
Use the Administration Console to add individual tuning property values to the deployment plan, or to validate a custom deployment plan.
Neither the Administration Console nor weblogic.PlanGenerator allow you to remove variables from a plan or set null values for variables. Use a text editor when necessary to complete these tasks.