Deploying Applications to WebLogic Server

Configuring Applications for Production Deployment

The following sections describe how you configure applications for deployment to a production WebLogic Server environment:

Overview of Deployment Configuration

When you receive a new application, or a new version of an application, from your development or quality assurance teams, the application has generally been configured for a development or testing environment. This means that the application may use specific resource names and performance tuning settings that match the available resources on the target servers used in the development or QA environments where the application was last deployed.

Because development and testing environments can be significantly different from the production environment in which the application is ultimately deployed, an Administrator must configure the application to use resource names and performance tuning parameters that are valid and appropriate for the production environment.

Understanding Application Deployment Descriptors

The basic deployment configuration for an application is defined in multiple XML documents, known as deployment descriptors, that are included as part of the application archive file that you receive for deployment. Deployment descriptor files fall into two separate categories:

J2EE deployment descriptors define the fundamental organization and behavior of a J2EE application or module, regardless of where the application is deployed. Each J2EE application and module requires a specific J2EE deployment descriptor as defined in the J2EE 1.4 specification.
WebLogic Server deployment descriptors define the resource dependencies and tuning parameters that an application uses in a specific WebLogic Server environment.

For the purposes of a production deployment, you should treat both the J2EE and WebLogic Server deployment descriptors as part of the application's source code, which is owned by your development team. Do not edit application deployment descriptors in order to configure an application for deployment to a production environment. Instead, use the Administration Console to persist configuration changes into a WebLogic Server deployment plan, which is described in the next section.

Understanding WebLogic Server Deployment Plans

A WebLogic Server deployment plan is an optional XML document that resides outside of an application archive and configures an application for deployment to a specific WebLogic Server environment. A deployment plan works by setting deployment property values that would normally be defined in an application's WebLogic Server deployment descriptors, or by overriding property values that are already defined in a WebLogic Server deployment descriptor.

Deployment plans are created and owned by the Administrator or deployer for a particular environment, and are stored outside of an application archive or exploded archive directory. As a best practice, BEA recommends storing each deployment plan for a single application in its own plan subdirectory of the application's root directory (See Creating an Application Installation Directory).

Deployment plans help the Administrator easily modify an application's WebLogic Server configuration for deployment into to multiple, differing WebLogic Server environments without modifying the deployment descriptor files included in the application archive. For example, a deployment plan enables you to deploy an application to multiple domains, or to multiple target servers and clusters within the same domain, that have are different configurations. To deploy the application to a new environment, an Administrator simply creates or uses a new deployment plan as necessary.

Figure 4-1 Configuring an Application for Multiple Deployment Environments

Configuring an Application for Multiple Deployment Environments

Figure 4-1 shows how deployment plans are typically used when releasing a new version of an application. During development, a programmer creates both J2EE and WebLogic Server deployment descriptors to configure the application for repeated deployments to their development environment. At this point, the application is generally deployed from an split development directory, rather than an archive file, to facilitate easy editing and redeployment of the application. A deployment plan is not necessary during deployment, because the developer has full access to the application's deployment descriptors, and the development environment is typically a simple, single-server domain. Figure 4-1 shows that the development server uses a simple PointBase database for development, named "DevDataSource," and the weblogic-ejb-jar.xml descriptor identifies the resource. Application tuning parameters are not defined in the development configuration, because the developer is focused on the basic semantics and behavior of the application.

To release a new version of the application, the developer packages the application into an archive file and delivers it to an Administrator or deployer in the quality assurance team. At this point, the embedded deployment descriptors provide a configuration that is valid for the development environment used by the developer, but are not valid for the testing environment where the application must be deployed. Figure 4-1 shows that the testing environment uses a different datasource name than the one used during development. To deploy the application, the Administrator of the testing environment generates a deployment plan to override the datasource name configured in the application's embedded deployment descriptors. Figure 4-1 shows that the deployment plan configures the application to use the resource named "QADataSource."

Similarly, when the application is released into production, the Administrator of the staging or production environment creates or uses another deployment plan to configure the application. Figure 4-1 shows that the production deployment plan once again overrides the application deployment descriptor to identify a new JDBC datasource name. For this environment, the deployment plan also defines tuning parameters to make better use of the additional resources available in the production domain.

Goals for Production Deployment Configuration

For the Administrator, the primary goal of configuring an application for production deployment is to generate a new deployment plan that is valid and appropriate for the target WebLogic Server environment. Specifically, the deployment plan must resolve all external resources references for the application to refer to valid resources available in the target environment. If the Application's configuration does not define to valid external resources for the target servers, the application cannot be deployed.

A deployment plan can optionally define or override WebLogic Server tuning parameters, to make ideal use of resources in the target environment. Defining tuning parameters is not required in order to successfully deploy an application. If an application's deployment descriptors and deployment plan do not define tuning parameters, WebLogic Server uses default values.

Creating a New Deployment Plan to Configure an Application

The Administration Console automatically generates (or updates) a valid XML deployment plan for an application when you interactively change deployment properties for an application that you have installed to the domain. You can use the generated deployment plan to configure the application in subsequent deployments, or you can generate new versions of the deployment plan by repeatedly editing and saving deployment properties.

Generating a deployment plan using the Administration Console involves these steps:

Preparing the Deployment Files

Installing the Application Archive

Saving Configuration Changes to a Deployment Plan

The following sections describe these steps for the WebLogic Server sample application jspExpressionEar.ear though the steps can also be applied for your own application.

Preparing the Deployment Files

If you did not install WebLogic Server sample applications when you installed WebLogic server, follow the directions in this section to prepare your application for deployment. If you installed WebLogic Server sample applications when you installed WebLogic Server, proceed to the next section Installing the Application Archive.

Create a new root directory and app and plan subdirectories for your application. For example:

mkdir c:\sample_root
mkdir c:\sample_root\app
mkdir c:\sample_root\plan

Download the WebLogic Server sample application jspExpressionEar.ear from http://download.oracle.com/docs/cd/E13222_01/wls/docs90/jspExpressionEar.ear. Be sure to save the application to the c:\sample_root\app directory you created in Step 1.

Installing the Application Archive

The Administration Console uses an application installation assistant to help you install a new application for configuration and deployment to a WebLogic Server environment. The installation assistant copies deployment files to the Administration Server and selects target WebLogic Server instances for deploying the application. After installing an application or module, the deployment files are available in the WebLogic Server domain and can be configured, distributed, and deployed as necessary.

Follow these steps to install the sample application to the examples server domain:

Start the examples server WebLogic server by using the Windows start menu or by running the WL_HOME\samples\domains\wl_server\startWebLogic.cmd script.

Access the Administration Console by pointing your browser to http://localhost:7001/console.

Follow the steps in Install applications and modules in Administration Console Online Help to install your application or the jspExpressionEar.ear sample application you downloaded in the previous section (Preparing the Deployment Files).

Saving Configuration Changes to a Deployment Plan

Use the Administration Console to edit deployment configuration properties for the application you installed in the previous section (Installing the Application Archive) and save the configuration to a deployment plan. For example, you could change properties such as the following in the jspExpressionEar.ear sample application:

On the Configuration page, edit one or more configuration properties. For example, change the Session Invalidation Interval to 80 seconds, and the Session Timeout to 8000 seconds.

Click Save to save your changes. The Administration Console stores your configuration changes to a new deployment plan. If you deployed the sample application from a root directory, the Administration Console automatically places the new deployment plan in the \plan subdirectory of the root directory. For example, c:\sample_root\plan\Plan.xml.

Understanding Deployment Plan Contents

The deployment plan generated in Creating a New Deployment Plan to Configure an Application is shown in Sample Deployment Plan.

Listing 4-1 Sample Deployment Plan

<deployment-plan xmlns="http://www.bea.com/ns/weblogic/90">
  <application-name>sample_root</application-name>
    <variable-definition>
    <variable>       <name>SessionDescriptor_InvalidationIntervalSecs_11029744771850</name>
      <value>80</value>
    </variable>
    <variable>
      <name>SessionDescriptor_TimeoutSecs_11029744772011</name>
      <value>8000</value>
    </variable>
    </variable-definition>
  <module-override>
    <module-name>jspExpressionEar.ear</module-name>
    <module-type>ear</module-type>
    <module-descriptor external="false">
      <root-element>weblogic-application</root-element>
      <uri>META-INF/weblogic-application.xml</uri>
    </module-descriptor>
    <module-descriptor external="false">
      <root-element>application</root-element>
      <uri>META-INF/application.xml</uri>
    </module-descriptor>
  </module-override>
  <module-override>
    <module-name>jspExpressionWar</module-name>
    <module-type>war</module-type>
    <module-descriptor external="false">
      <root-element>weblogic-web-app</root-element>
      <uri>WEB-INF/weblogic.xml</uri>
      <variable-assignment>
        <name>SessionDescriptor_InvalidationIntervalSecs_11029744771850</name>
        <xpath>/weblogic-web-app/session-descriptor/invalidation-interval-secs</xpath>
      </variable-assignment>
      <variable-assignment>
        <name>SessionDescriptor_TimeoutSecs_11029744772011</name>
        <xpath>/weblogic-web-app/session-descriptor/timeout-secs</xpath>
      </variable-assignment>
    </module-descriptor>
    <module-descriptor external="false">
      <root-element>web-app</root-element>
      <uri>WEB-INF/web.xml</uri>
    </module-descriptor>
  </module-override>
  <module-override>
    <module-name>sample_root</module-name>
    <module-type>ear</module-type>
    <module-descriptor external="false">
      <root-element>weblogic-application</root-element>
      <uri>META-INF/weblogic-application.xml</uri>
    </module-descriptor>
    <module-descriptor external="false">
      <root-element>application</root-element>
      <uri>META-INF/application.xml</uri>
    </module-descriptor>
  </module-override>
  <config-root>C:\sample_root\plan</config-root>
</deployment-plan>

The basic elements in the deployment plan serve the following functions:

deployment-plan encapsulates all of the deployment plan's contents.
application-name corresponds to the deployment name for the application or module.
variable-definition defines one or more variable elements. Each variable defines the name of a variable used in a plan and a value to assign (which can be null). The sample plan shown in Sample Deployment Plan contains variable definitions for the changes you made to the Session Invalidation Interval and Session Timeout properties.
module-override elements define each module name, type, and deployment descriptor that the deployment plan overrides. A module-descriptor element can optionally contain a variable-assignment which identifies a variable name used to override a property in the descriptor, and the exact location within the descriptor where the property is overridden.

The sample plan shown in Sample Deployment Plan contains module override elements for the Enterprise Application, the embedded Web application, and the enclosing root directory. The module-descriptor entry for the weblogic.xml descriptor file contains two variable-assignment elements that override the property values for the Session Invalidation Interval and Session Timeout properties shown in Saving Configuration Changes to a Deployment Plan.
By default, the values in variable-assignment elements are added to the values that are already defined in the descriptor. You can change this behavior and cause the variable-assignment element to replace or remove the values that are defined in the descriptor by setting the operation subelement in the variable-assignment element to the value replace or remove, respectively.
For example, if:

In ejb-jar.xml, you create a policy to allow access only to the security role named ejbRole.

...
<assembly-descriptor>
<security-role>
<role-name>ejbRole</role-name>
</security-role>
<method-permission>
<role-name>ejbRole</role-name>
<method>
<ejb-name>ejb.SearchHandlerWrapperEJB</ejb-name>
<method-name>*</method-name>
</method>
</method-permission>
</assembly-descriptor>
...

In the security-role-assignment element in weblogic-ejb-jar.xml, you map ejbRole to the principal named user1.

...
<security-role-assignment>
<role-name>ejbRole</role-name>
<principal-name>user1</principal-name>
</security-role-assignment>
...

You want use a deployment plan to override the security-role-assignment element defined in weblogic-ejb-jar.xml, so that ejbRole is mapped to user2 instead of user1, you could achieve the desired override behavior by setting appropriate values for the variable, variable-assignment, and operation elements in the deployment plan. Make sure to set the value of operation to replace.

...
<variable> <name>SecurityRoleAssignment_ejbRole_PrincipalNames_11168815313911</name>
<value>user2</value>
</variable>

<variable-assignment>
<name>SecurityRoleAssignment_ejbRole_PrincipalNames_11168815313911</name>
<xpath>/weblogic-ejb-jar/security-role-assignment/[role-name="ejbRole"]/principal-name</xpath>
<operation>replace</operation>
</variable-assignment>

For more information about the contents of a WebLogic Server deployment plan, see the Deployment Plan Reference and Schema.

Using an Existing Deployment Plan to Configure an Application

Applications that you receive for deployment may come with varying levels of configuration information. If you have an existing deployment plan for an application, simply prepare the application as described in Preparing the Deployment Files and place the deployment plan in the plan subdirectory of the application root. Then install the application using the instructions in Installing the Application Archive. The Administration Console automatically uses a deployment plan named plan.xml in the \plan subdirectory of an application root directory if one is available. If multiple plans are available for your application, they are placed in their own \plan subdirectories (for example \plan1 and \plan2), and the Administration Console cannot identify them. Therefore, you must specify, in config.xml, the plan you want to use. For information on config.xml, see Creating WebLogic Domains Using the Configuration Wizard.

After you install a new application and existing deployment plan, the Administration Console validates the deployment plan configuration against the target servers and clusters that were selected during installation. If the deployment plan contains empty (null) variables, or if any values configured in the deployment plan are not valid for the target server instances, you must override the deployment plan before you can deploy the application. You can also configure tuning parameters to better suit the target environment in which you are deploying the application, as described in Saving Configuration Changes to a Deployment Plan. Changes you make to the application's configuration are saved to a new deployment plan.

If you have a valid deployment plan that fully configures an application for the environment in which you are deploying, you can use either the Administration Console or the weblogic.Deployer utility to identify the application and plan to use for deployment. Note that any deployment plan you use with the weblogic.Deployer utility must be complete and valid for your target servers; weblogic.PlanGenerator does not allow you to set or override individual deployment properties that are defined in the plan. To deploy a new application and existing deployment plan using weblogic.Deployer, see Deploying an Application with a Deployment Plan.

Additional Configuration Tasks

See the following sections for information about additional deployment configuration tasks:

Deploying an Application with a Deployment Plan describes how to deploy an application with a valid deployment plan using the weblogic.Deployer tool.
Updating the Deployment Configuration for an Application describes how to update the deployment configuration for a currently-deployed application.
Exporting an Application for Deployment to New Environments explains how developers can create portable deployment plans using the weblogic.PlanGenerator tool.
weblogic.PlanGenerator Command Line Reference provides a complete reference to the weblogic.PlanGenerator tool.

Best Practices for Managing Application Configuration

Always manage multiple deployment configurations using deployment plans, rather than multiple versions of the WebLogic Server deployment descriptor files.
Always store each existing deployment plan for an application in its own plan subdirectory of an application root directory.
If your organization requires standardized, repeatable deployments to several environments, use the Application with Single Deployment Plan workflow to maintain a single deployment plan in your source control system.
If you make extensive changes to an application's deployment configuration using the Administration Console, back up or safely store the updated deployment plan for future use. BEA recommends storing the entire application root directory in a source control system, so that you can maintain configuration information for multiple environments and multiple versions of an application.