This chapter includes the following sections:
When an administrator or deployer receives a new application, or a new version of an application, from development or quality assurance teams, the application is usually configured for a development or testing environment. 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.
Deployment configuration for an application can occur at several points in the life cycle of an application. Each phase of deployment configuration typically involves creating and working with different deployment files:
Development configuration—During development, a programmer creates Java EE deployment descriptors for an application or module. The programmer also creates WebLogic Server deployment descriptors to configure the application for deployment to a WebLogic Server development environment. See Developing Applications for Oracle WebLogic Server.
Applications developed outside of the WebLogic Server development environment (for example, a sample or third-party Java EE application such as PetStore) may include only Java EE descriptors.
Export configuration—Before releasing an application from development, a programmer or designer may optionally export the application's deployment configuration to a WebLogic Server deployment plan. Exporting a configuration creates deployment plan variables for all or a subset of the deployment properties already defined by a developer in the application's WebLogic Server deployment descriptor files. See Exporting an Application for Deployment to New Environments.
Exporting an application helps deployers in other areas of the organization (such as engineers on the QA team or production administrators) easily deploy the application to environments that differ from the programmer's development environment. The ideal deployment plan includes all of the properties that a deployer needs to change before deploying the application in a new environment.
Deployment-time configuration—An administrator or deployer configures the application before deploying the application into the target environment. Deployment-time configuration may use:
The same WebLogic Server deployment configuration and deployment plan created during development.
Modified versions of the development configuration and deployment plan.
A custom deployment plan that the deployer previously created for the environment, depending on the deployment configuration workflow for your organization.
Post-deployment configuration—After an application has been deployed to a target environment, an administrator or deployer can reconfigure the application by redeploying with a new deployment plan or by using the WebLogic Server Administration Console to update and redeploy an existing deployment plan. See Redeploying Applications in a Production Environment and Managing Deployed Applications.
Because deployment configuration is performed by different people at different points in the life cycle of an application, administrators, deployers, and developers need to work together to create a repeatable configuration workflow for their organization. See Typical Deployment Configuration Workflows.
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:
Java EE deployment descriptors define the fundamental organization and behavior of a Java EE application or module, regardless of where the application is deployed. Each Java EE application and module requires a specific Java EE deployment descriptor as defined in the Java EE 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 Java EE 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, persist configuration changes into a WebLogic Server deployment plan, which is described in the next section.
You cannot use deployment plans with applications using DTD-based deployment descriptors. You must upgrade the application to use schema-based descriptors.
As previously discussed, a WebLogic Server deployment plan is an optional XML document that you use to configure an application for deployment to a specific WebLogic Server environment. A deployment plan specifies setting deployment property values that would normally be defined in an application's WebLogic Server deployment descriptors, or overrides property values that are already defined in a WebLogic Server deployment descriptor. When exporting an application, the deployment plan typically acts to override selected properties in the WebLogic Server deployment descriptors you created during development.
You can configure or override any Java EE or WebLogic-specific deployment descriptors, except items annotated as transient.
You can update deployment plans using JSR 88 DConfigBeans setter methods to change the values of the descriptor elements and the remove methods to remove descriptor elements. Also, you can call the setter and remove methods from the descriptor bean tree returned by
getDescriptorBean() for both standard and WebLogic-specific descriptors. These methods result in overrides in the plan. See "Configuring Applications for Deployment" in Deploying Applications with the WebLogic Deployment API.
Typically, deployment plans are created by developers along with the associated application files, then distributed to the administrator or another deployer, who updates the plan for a particular environment (such as staging, testing, or production). The deployment plan is stored outside of an application archive or exploded archive directory. As a best practice, Oracle 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 to multiple, differing WebLogic Server environments without modifying the deployment descriptor files included in the application archive. Configuration changes are applied by adding or changing variables in the deployment plan, which define both the location of the WebLogic Server descriptor properties to change and the value to assign to those properties. Administrators deploying an application need only change the deployment plan—the original deployment files and deployment descriptors remain unchanged as shown in Figure 4-1. To determine the deployment configuration workflow for your environment, see Typical Deployment Configuration Workflows.
Figure 4-1 WebLogic Server Deployment Plan
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.
Deployment plans enable you to define a convenient, repeatable workflow for configuring an application for deployment to multiple WebLogic Server environments. A configuration workflow for production applications requires cooperation between your development and design teams, which create and package the deployable application, and the administrator or deployer for each target WebLogic Server environment.
The ideal deployment configuration workflow for your organization is determined by:
Number of different environments in which you deploy the same application
Difference in resources provided by each target environment
Frequency with which each target environment changes
Frequency with which the application's Java EE configuration changes
Ownership requirements for configuration information in different areas of your organization
The sections that follow describe common deployment configuration workflows for managing deployment plans and deploying applications to multiple WebLogic Server domains.
Organizations that know the exact configuration of different deployment environments can use a single, well-defined deployment plan to deploy an application to multiple WebLogic Server domains. The single deployment plan configuration workflow works in the following way:
The development team, cooperating with administrators and deployers, creates a master deployment plan for use with all target environments. The number of target environments will vary depending on your organizational structure. Common deployment environments include one or more Quality Assurance (QA) or testing domains, staging domains, and production domains.
The deployment plan that the team creates at this phase defines variables for all configuration properties that are known to differ between each target environment. For example, the plan might define empty variables for resource names that differ between environments and must be configured before the application can be deployed. The plan may also define default values for common tuning parameters that deployers may want to change in their environments.
For more information about creating a deployment plan during development, see Exporting an Application for Deployment to New Environments.
When a version of the application is ready to be released, the development team packages the application deployment files and delivers both the deployment files and a master deployment plan to deployers for each target environment.
Each deployer uses the WebLogic Server Administration Console to install the application and identify the deployment plan to use for configuration. The WebLogic Server Administration Console validates the overall deployment configuration based on the resources available in the target domain. The Console then presents a list of configurable properties defined in the plan (as well as any invalid properties) to the deployer for editing.
Figure 4-2 Single Deployment Plan Workflow
The deployer uses the WebLogic Server Administration Console to interactively configure properties that were defined in the deployment plan. Deployment plan variables that have null values, or invalid values for the target WebLogic Server instances or clusters, must be configured before the application can be deployed. Deployment plan variables that already have valid values need not be changed before deployment.
Deployers in each environment agree to limit their configuration changes to those properties defined in the deployment plan. If additional configuration changes are required, the deployer must communicate those requirements to the development or design team that modifies the master deployment plan.
Using the single deployment plan workflow provides the following benefits:
It enables the development or design team to control the deployment configuration of the application.
It reduces the number of configuration decisions that a deployer must make when deploying the application to a target environment.
It minimizes the number of configuration files associated with the application, making it easy to store deployment configuration information in a source control system.
In general, you would use a single deployment plan workflow if your organization has a few, well-understood target environments, and you want to easily replicate a standardized deployment configuration in each environment.
The single deployment plan workflow assumes that the development or design team maintains ownership of the deployment plan, and that deployers limit their plan changes to those variables defined in the plan. If the deployer modifies only those properties defined in the deployment plan, their changes are written back to the same deployment plan as updates to the variables.
However, WebLogic Server imposes no restrictions on the configuration properties that a deployer can modify using the WebLogic Server Administration Console. If a deployer configures deployment properties that were not originally defined in a plan, the Console generates a new deployment plan having the additional variable entries, and uses the new plan for deployment or redeployment operations. This can lead to a situation where the deployer uses a deployment plan that is drastically different from the master deployment plan owned by the development team.
To incorporate new changes into the master deployment plan, the deployer retrieves the new, customized deployment plan created by the Console. Ideally, those changes should be applied to the master deployment plan.
Organizations that have numerous deployment environments that frequently change should use a configuration workflow with multiple deployment plans. In a multiple deployment plan workflow, each deployment plan is owned by the deployer of the application rather than the development team. The multiple deployment plan configuration workflow works in the following way:
The development team releases a version of the packaged application deployment files (containing Java EE and WebLogic Server descriptors). The development team may or may not include a template deployment plan with exported variables for resource definitions or common tunable parameters.
Before deploying the application, each deployer generates a custom deployment plan to configure the application for their target environment.
A custom deployment plan can be created by starting with a template deployment plan (or no deployment plan) and making changes to the application's deployment configuration using the WebLogic Server Administration Console. See "Update a deployment plan" in Oracle WebLogic Server Administration Console Online Help.
After defining the deployment configuration for their environment, each deployer retrieves their custom deployment plan and maintains it for future deployments of the application. Oracle recommends storing custom configuration plans in a source control system so that new versions can be tracked and reverted to if necessary.
Figure 4-3 Multiple Deployment Plan Workflow
For subsequent releases of the application, each deployer uses their customized deployment plan to configure the application for deployment. Using the customized plan allows deployers to perform deployments with the
weblogic.Deployer or automate deployments using WLST.
Using the multiple deployment plan workflow provides the following benefits:
It enables the administrator or deployer to manage both the application configuration and environment configuration in tandem.
It enables deployers to automate the deployment process by using a custom plan that fully configures the application for their application.
In general, you would use a multiple deployment plan workflow if your organization has many deployment environments that change frequently, making it difficult or impossible to maintain a single master deployment plan.
The multiple deployment plan workflow assumes that the deployer or administrator (rather than the programming or design team) owns and maintains the deployment configuration for an application. It also assumes that the basic Java EE configuration of the application rarely changes, because certain Java EE configuration changes would render a deployer's custom configuration plans invalid. For example, if a module in an enterprise application is added, removed, or changed, custom deployment plans referencing the module would become invalid. In this case, each deployer would need to re-create a custom plan by configuring the application using the WebLogic Server Administration Console.
The WebLogic Server 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.
weblogic.PlanGenerator also enables you to generate a basic WebLogic Server deployment plan for applications that have only Java EE deployment descriptors. See weblogic.PlanGenerator Command-Line Reference.
Generating a deployment plan using the WebLogic Server Administration Console involves these steps:
Use the following directions to prepare your application for deployment.
plansubdirectories for your application. For example:
mkdir c:\sample_root mkdir c:\sample_root\app mkdir c:\sample_root\plan
c:\sample_root\appdirectory you created in Step 1.
The WebLogic Server Administration Console uses an application installation assistant to help you install a new application for configuration and deployment to a new WebLogic Server environment. After you install an application or module and select deployment targets, the deployment files are available in the WebLogic Server domain and can be configured, distributed, and deployed as necessary.
Follow the steps in Install applications and modules in Oracle WebLogic Server Administration Console Online Help to install your application to your WebLogic Server domain.
Use the WebLogic Server Administration Console to edit any deployment configuration properties for the application you installed in Installing the Application Archive and save the configuration to a deployment plan.
\plansubdirectory of the root directory. For example,
Example 4-1 shows a sample deployment plan generated by the steps in Creating a New Deployment Plan to Configure an Application.
Example 4-1 Sample Deployment Plan
<deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan"> <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>myApp.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>myWebApp.war</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 Example 4-1 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 Example 4-1 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, as changed in the example 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 sub-element in the
variable-assignment element to the value
For example, suppose that in ejb-jar.xml, a developer created a policy to allow access only to the security role named
... <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> ...
security-role-assignment element in weblogic-ejb-jar.xml,
ejbRole is mapped to the principal named
... <security-role-assignment> <role-name>ejbRole</role-name> <principal-name>user1</principal-name> </security-role-assignment> ...
If you want to 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
operation elements in the deployment plan. Make sure to set the value of
... <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
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 WebLogic Server 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
\plan2), and the WebLogic Server Administration Console cannot identify them. Therefore, the
config.xml must specify the plan you want to use. For information on
config.xml, see Domain Configuration Files in Understanding Domain Configuration for Oracle WebLogic Server.
After you install a new application and existing deployment plan, the WebLogic Server 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 WebLogic Server Administration Console or the
weblogic.Deployer utility to deploy an application with a deployment plan to use for deployment.
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 when it creates a plan. To deploy a new application and existing deployment plan using
weblogic.Deployer, see Deploying an Application with a Deployment Plan.
You can use a deployment plan to override the
context-root element defined in the
application.xml deployment descriptor. The following example shows how to use a
plan.xml file to change the
context-root of an application, with the relevant sections in bold.
Example 4-2 Using a Deployment Plan to Change the context-root of an Application
<deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan"> <application-name>test</application-name> <variable-definition> <variable> <name>myNewRoot</name> <value>DEF</value> </variable> </variable-definition> <module-override> <module-name>test</module-name> <module-type>ear</module-type> <module-descriptor external="false"> <root-element>application</root-element> <uri>META-INF/application.xml</uri> <variable-assignment> <name>myNewRoot</name> <xpath>/application/module/web/[context-root="ABC"]/</xpath> <operation>replace</operation> </variable-assignment> </module-descriptor> </module-override> <config-root>D:\Cases\WLS\PlanXML\test</config-root> </deployment-plan>
In Example 4-2:
context-root defined in the
application.xml file is
Using the deployment plan, the
context-root successfully changes from
The URL used to access the application changes from
This feature allows you to place application-specific files to be overridden into an optional subdirectory (named
/AppFileOverrides) in the existing plan directory structure. The presence or absence of this new optional subdirectory controls whether file overrides are enabled for the deployment. If this subdirectory is present, an internal ClassFinder is added to the front of the application and module classloaders for the deployment. As a result, the file override hierarchy rules follow the existing classloader and resource loading rules and behaviors for applications. For more information on WebLogic Server application classloading, see WebLogic Server Application Classloading in Developing Applications for Oracle WebLogic Server.
This mechanism is only for overriding resources and does not override classes.
These are application-specific files and the contents are opaque to WebLogic Server, so the entire file contents will be overridden when an override file is supplied.
The files placed in the
/AppFileOverrides subdirectory are staged and distributed along with the rest of the plan directory contents and are available on all of the targets. Applications are then able to load these files as resources using the current classloader (for example, using the
ClassLoader.getResourceAsStream method.) This either finds the overridden files or the files packaged in the application, depending on the configuration and whether overridden files are supplied.
For Web applications, application file overrides only apply to the classpath related resources (which are in
WEB-INF/lib), and do not apply to the resource path for the Web application. Therefore, overrides are seen by Web applications using the
classloader.getResourceAsStream() method to lookup resources, but overrides do not affect Web application calls to the
In order to use this feature, you must:
Specify a plan for the deployment (see Creating a New Deployment Plan to Configure an Application).
config-root within in the plan.
The contents of the
/AppFileOverrides subdirectory use the existing plan directory structure and directory naming conventions that already exist for descriptor overrides. For more information on directory naming conventions, see Packaging Files for Deployment.
Enabling application file overrides causes a directory ClassFinder to be added to the application and module level classloaders, which point to the appropriate root directories within the
/AppFileOverrides subdirectory (which is in the plan directory). The ClassFinder inserted into the front of the application's classloader is given a structure of
"/AppFileOverrides". The ClassFinder inserted into the front of the module's classloaders is given a structure of
Table 4-1 Directory Structure for Generic File Overrides
Directory put in front of the main application classloader's classpath
Directory put in front of the
Directory put in front of the
It is important to note that the application controls the file contents and format and controls whether the contents of the files are accessed by the application code. As a best practice, generic file loading overrides should be used by application code that has environment-specific properties files, and which is loading those properties files as resources using the application's classloader. For example, the application code may do the following:
Properties myAppProps = new Properties(); InputStream iostream = Thread.currentThread().getContextClassLoader().getResourceAsStream("myCfg/myApp.properties"); myAppProps.load(iostream);
See the following sections for information about additional deployment configuration tasks:
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 Command-Line Reference, provides a complete reference to the
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 WebLogic Server Administration Console, back up or safely store the updated deployment plan for future use. Oracle 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.