5 Exporting an Application for Deployment to New Environments
This chapter includes the following sections:
Overview of the Export Process
Exporting an application's deployment configuration is the process of creating a custom deployment plan for deploying the application into new WebLogic Server environments. When the process is complete, the application deployment files and the custom deployment plan are distributed to deployers (for example, testing, staging, or production administrators) who then use the deployment plan as a blueprint for configuring the application for their environment.
An administrator can install the application and the custom deployment plan using the WebLogic Server Administration Console, which validates the deployment plan and allows the administrator to update configuration properties needed for a specific deployment.
See the Understanding Deployment Plan Contents 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 WebLogic Server 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
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 byweblogic.PlanGenerator
, either manually or using the WebLogic Server Administration Console, to delete extraneous variable definitions or add variables for individual properties. -
The WebLogic Server Administration Console updates or creates new deployment plans as necessary when you change configuration properties for an installed application. You can use the WebLogic Server Administration Console to generate a new deployment plan or to add or override variables in an existing plan. The WebLogic Server 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 Java EE module descriptors as well as JDBC, JMS, and WLDF application modules) can be classified into one of 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 Java EE deployment descriptors. For example, if the Java EE 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.
Use these categories during the configuration export process to select properties to expose as variables in the deployment plan. For example, a developer 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 WebLogic Server 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 several steps.
-
Generating a Template Deployment Plan using weblogic.PlanGenerator
-
Customizing the Deployment Plan Using the Administration Console
The sections that follow describe each procedure in detail.
Staging Application Files for Export
Oracle 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:
If you choose not to use an installation directory when exporting an application, Oracle 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 (such as declaration or configurable properties) of deployment descriptors.
Oracle 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 -rootinstall_root
category
where:
install_root
specifies the fully qualified name of the root directory for the application and plan.
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 Java EE 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 WebLogic Server Administration Console is directed to assign valid resource names and tuning properties for each null variable before the application can be deployed.
Customizing the Deployment Plan Using the Administration Console
A developer generally customizes the template plan to add one or more WebLogic Server tuning properties for the application.
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. The WebLogic Server Administration Console enables you to easily add deployment plan variables for individual deployment descriptor properties as needed. To customize a deployment plan using the WebLogic Server Administration Console:
Install the Exported Application and Template Deployment Plan
To modify a deployment configuration using the WebLogic Server Administration Console, you must first install the application and existing deployment plan as described in Steps for Creating an Application Installation Directory.
Add Variables for Selected Tuning Properties
After installing the exported application, follow the steps in Update a deployment plan in Oracle WebLogic Server 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 WebLogic Server 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 modify any deployment properties defined as variables in the application's deployment plan, your changes are written back to a new version of the plan file. If the application that was installed from an installation directory, the WebLogic Server Administration Console stores the 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 WebLogic Server Administration Console to remove variable definitions from the deployment plan or assign a null value for a deployment property.
See http://xmlns.oracle.com/weblogic/deployment-plan/1.01/deployment-plan.xsd
and Understanding Deployment Plan Contents 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 thevariable-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 WebLogic Server Administration Console automatically validates the deployment configuration for a newly-installed application or module. Take these steps to validate a custom deployment plan that you have created during the export process.
- Follow the steps under Add Variables for Selected Tuning Properties to install the application or module with the final version of the custom deployment plan. The WebLogic Server Administration Console automatically uses a deployment plan named
Plan.xml
in theplan
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 recommended 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. Usingweblogic.PlanGenerator
to export other categories of deployment descriptor properties generally results in too many variables in the deployment plan. -
Use the WebLogic Server Administration Console to add individual tuning property values to the deployment plan, or to validate a custom deployment plan.
-
Neither the WebLogic Server 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.