Deploying Applications to WebLogic Server

Preparing Applications
and Modules for Deployment

The following sections provide a basic overview of key WebLogic Server deployment topics:

Overview of Preparing Applications and Modules

WebLogic Server supports deployment of standard J2EE modules and applications, as well as JDBC and JMS resource modules, as described in Supported Deployment Units. When preparing supported applications and modules for deployment, an Administrator has several options with regard to how the deployment files are arranged:

Archive file or exploded archive directory. Weblogic Server enables you to deploy the application source files as either a Java archive, or as an exploded archive directory. Using an exploded archive directory helps you easily update portions of the application after deployment. If you choose to use an exploded archive directory, you may be required to manually unpack a previously-archived deployment. See Deployment Archive Files Versus Exploded Archive Directories and Exploded Archive Directories.
Application installation directory or other deployment directory. WebLogic Server 9.0 introduces a new application installation directory structure that helps you organize multiple versions of an application's source and configuration files in a standard way. Regardless of whether you deploy from an archive file or exploded archive directory, BEA recommends that you copy deployment files into the appropriate subdirectories of an application installation directory. Doing so ensures that the Administration Console can easily find deployment configuration files, such as WebLogic Server deployment descriptors and deployment plans, and can easily distinguish between multiple versions of the same application.

An application installation directory is not required; you can also deploy archive files and exploded archive directories from any directory that is accessible to the Administration Console.

Deployment Archive Files Versus Exploded Archive Directories

WebLogic Server supports deployments that are packaged either as archive files using the jar utility or Ant's jar tool, or as exploded archive directories.

Note: In general, using archived files is more efficient when deploying applications to managed servers. However, it makes updating the application, such as updating web content, more difficult as it requires a redeployment of the application.

Archive Files

An archive file is a single file that contains all of an application's or module's classes, static files, directories, and deployment descriptor files. In most production environments, the applications an Administrator receives for deployment are stored as archive files.

Deployment units that are packaged using the jar utility have a specific file extension depending on the type:

EJBs and client archives are packaged as .jar files.
Web Applications are packaged as .war files.
Resource Adapters are packaged as .rar files.
Enterprise Applications are packaged as .ear files, and can contain other J2EE modules such as EJBs, Web Applications, and Resource Adapters.
Web Services can be packaged either as .war files or as .jar files, depending on whether they are implemented using Java classes or EJBs.
J2EE libraries are packaged either as an Enterprise Application (.ear file) or as a standard J2EE module.
Client applications and optional packages are packaged as .jar files.

In addition to an archive file, you may also receive a deployment plan, which is a separate file that configures the application for a specific environment. Configuring Applications for Production Deployment describes deployment plans in more detail.

Exploded Archive Directories

An exploded archive directory contains the same files and directories as a JAR archive. However, the files and directories reside directly in your file system and are not packaged into a single archive file with the jar utility.

You may choose to deploy from an exploded archive directory under the following circumstances:

You want to perform partial updates of an Enterprise Application after deployment. Deploying Enterprise Applications as an exploded archive directory makes it easier to update individual modules of the application without having to re-create the archive file.
You are deploying a Web application or Enterprise Application that contains static files that you will periodically update. In this case, it is more convenient to deploy the application as an exploded directory, because you can update and refresh the static files without re-creating the archive.
You are deploying a Web application that performs direct file system I/O through the application context (for example, a Web application that tries to dynamically edit or update parts of the Web application itself). In this case, the modules that perform the I/O operations should have a physical filesystem directory in which to work; you cannot obtain a file when the application is deployed as an archive, as per the specification.

Creating an Exploded Archive Directory from an Archive File

If you have an archive file that you want to deploy as an exploded archive directory, use the jar utility to unpack the archive file in a dedicated directory. For example:

mkdir /myapp

cd /myapp

jar xvf /dist/myapp.ear

If you are unpacking an archive file that contains other module archive files (for example, an Enterprise Application or Web Service that includes JAR or WAR files) and you want to perform partial updates of those modules, you must expand the embedded archive files as well. Make sure that you unpack each module into a subdirectory having the same name as the archive file. For example, unpack a module named myejb.jar into a /myejb.jar subdirectory of the exploded Enterprise Application directory.

Note: If you want to use different subdirectory names for the archived modules in an exploded EAR file, you must modify any references to those modules in the application itself. For example, you must update the URI values specified in application.xml and CLASSPATH entries in the manifest.mf file.

Understanding Default Deployment Names

When you first deploy an application or stand-alone module to one or more WebLogic Server instances, you specify a deployment name to describe collectively the deployment files, target servers, and other configuration options you selected. You can later redeploy or stop the deployment unit on all target servers by simply using the deployment name. The deployment name saves you the trouble of re-identifying the deployment files and target servers when you want to work with the deployment unit across servers in a domain.

If you do not specify a deployment name at deployment time, the deployment tool selects a default name based on the deployment source file(s). For archive files, weblogic.Deployer uses the name of the archive file without the file extension. For example, the file myear.ear has a default deployment name of myear. For an exploded archive directory, weblogic.Deployer uses the name of the top-level directory you deploy.

For J2EE libraries and optional packages, weblogic.Deployer uses the name specified in the library's manifest file. If no name was specified in the library's manifest file, you can specify one with the -name option.

See the following section, Understanding Application Naming Requirements for information on application naming requirements; See Deploying Applications and Modules to specify a non-default deployment name.

Understanding Application Naming Requirements

In order to successfully deploy an application to WebLogic Server, the application name must be valid. Application naming requirements are as follows:

Application names must only contain the following characters:

a-z
A-Z
0-9
_ (underscore)
- (hyphen/dash)
. (period/dot)

No additional characters are allowed in application names.

Application names that contain the . (period/dot) character must contain at least one additional different character; "." and ".." are not valid application names.
Application names must be less than 215 characters in length.

Understanding Deployment Version Strings

In addition to a deployment name, an application or module can also have an associated version string. The version string distinguishes the initial deployment of the application from subsequent redeployed versions. For example, you may want to later update the application to fix problems or add new features. In production systems, it is critical to maintain a version string for both the initial and subsequent deployments of an application. Doing so allows you to update and redeploy an application version without interrupting service to existing clients. See Updating Applications in a Production Environment for more information.

The version string is specified in the manifest file for the application, and should be provided by your development team along with the other deployment files. Specifying Application Versions in Developing WebLogic Server Applications describes the conventions for specifying the version string.

Creating an Application Installation Directory

The application installation directory separates generated configuration files from the core application files, so that configuration files can be easily changed or replaced without disturbing the application itself. The directory structure also helps you to organize and maintain multiple versions of the same application deployment files.

The following figure shows the directory hierarchy for storing a single version of a deployable application or module.

Figure 3-1 Application Installation Directory

Application Installation Directory

BEA recommends copying all new production deployments into an application installation directory before deploying to a WebLogic Server domain. Deploying from this directory structure helps you easily identify all of the files associated with a deployment unit—you simply deploy the installation root using the Administration Console, and the Console automatically locates associated files such as deployment plans and WebLogic Server deployment descriptors that were generated during configuration.

Steps for Creating an Application Installation Directory

To create an application installation directory:

Choose a top-level directory where you want to store deployment files for applications and modules on your system. Follow these best practices:

Do not store deployment files within a WebLogic Server domain directory.
Use source control if available to maintain deployment source files.
If possible, store deployment files in a directory that is accessible by the Administration Server and Managed Servers in your domain.

The instructions that follow use the sample deployment directory, c:\deployments\production.

Create a dedicated subdirectory for the application or module you want to deploy:

mkdir c:\deployments\production\myApplication

Create a subdirectory beneath the application directory to designate the version of the application you are deploying. Name the subdirectory using the exact version string of the application. For example:

mkdir c:\deployments\production\myApplication\91Beta

The version subdirectory will become the installation root directory from which you deploy the directory. Create subdirectories named app and plan under the version subdirectory:

mkdir c:\deployments\production\myApplication\91Beta\app

mkdir c:\deployments\production\myApplication\91Beta\plan

Note: If you have more than one deployment plan associated with the application, create one \plan subdirectory for each plan. For example, if you have two deployment plans associated with the 91Beta version of the application myApplication, you would create two \plan subdirectories. For instance:

mkdir c:\deployments\production\myApplication\91Beta\plan1

mkdir c:\deployments\production\myApplication\91Beta\plan2

Copy your application source deployment files into the \app subdirectory. If you are deploying from an archive file, simply copy the archive file, as in:

cp c:\downloads\myApplication.ear c:\deployments\production\myApplication\91Beta\app

If you are deploying from an exploded archive directory, copy the complete exploded archive directory into \app: cp -r c:\downloads\myApplication c:\deployments\production\myApplication\91Beta\app
This results in the new directory, c:\deployments\production\myApplication\91Beta\app\myApplication.

If you have one or more deployment plans for the application, copy them into the \plan subdirectories.

If you have one deployment plan for the application: cp c:\downloads\myApplicationPlans\plan.xml c:\deployments\production\myApplication\91Beta\plan
If you have two deployment plans for the application:

cp c:\downloads\myApplicationPlans\plan1.xml c:\deployments\production\myApplication\91Beta\plan1
cp c:\downloads\myApplicationPlans\plan2.xml c:\deployments\production\myApplication\91Beta\plan2
Note: If you do not have an existing deployment plan, you can create one using the Administration Console as described in Configuring Applications for Production Deployment. The Administration Console automatically stores newly-generated deployment plans in the \plan subdirectory of the application installation directory.

To install the application into a WebLogic Server domain using Administration Console, select the application installation directory. By default, the Administration Console will use a plan named plan.xml, if one is available in the \plan subdirectory. The Administration Console does not identify plans in subdirectories other than the \plan subdirectory; in other words, plans in \plan1 or \plan2 subdirectories are not identified by the Administration Console. Therefore, if multiple plans for your application are available, you must indicate, in config.xml, the plan you would like to use. See Configuring Applications for Production Deployment. For information on config.xml, see Creating WebLogic Domains Using the Configuration Wizard.

After installing the application, you can configure, deploy, or distribute the application as necessary.

Note: You cannot specify an application installation directory when using the weblogic.Deployer tool, and the tool does not use an available plan.xml file by default. You must specify the actual deployment file(s) and plan to use for deployment. See Deploying Applications and Modules.

Best Practices for Preparing Deployment Files

BEA recommends the following best practices when preparing applications and modules for deployment:

Regardless of whether you deploy an archive file or exploded archive directory, store the deployment files in an installation directory for the application, as described in Creating an Application Installation Directory. Using an installation directory simplifies the deployment process, because the Administration Console understands where to locate deployment and configuration files.
Manage the entire application installation directory in a source control system, so you can easily revert to previous application versions if necessary.

Preparing Applications and Modules for Deployment