Skip navigation.

Deploying WebLogic Server Applications

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Overview of WebLogic Server Deployment

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


Document Scope and Audience

This document is written mainly for Administrators who want to deploy Java 2 Platform, Enterprise Edition (J2EE) applications or application modules to WebLogic Server. This document assumes that you are working in a production environment, which is generally characterized by multiple WebLogic Server instances or clusters running on multiple machines. It also assumes that you have one or more application module archive files that have been tested and are ready to deploy on a production server.

If you are an engineer and need to deploy or package applications in a development environment, see Developing WebLogic Server Applications. Also see Deployment Topics for Developers on page 4-13 for information about deployment features that apply to development environments.


Deployment Units

A deployment unit refers to a J2EE application (an Enterprise Application or Web Application) or a standalone J2EE module (an EJB or Resource Adapter) that has been organized according to the J2EE specification and can be deployed to WebLogic Server.

For each type of deployment unit, the J2EE specification defines both the required files and their location in the directory structure of the application or module. Deployment units may include Java classes for EJBs and servlets, resource adapters, Web pages and supporting files, XML-formatted deployment descriptors, and even other modules.

J2EE does not specify how a deployment unit is deployed on the target server—only how standard applications and modules are organized. WebLogic Server supports deployments that are packaged either as archive files using the jar utility, or as exploded archive directories.

Standalone Modules

J2EE provides specifications for creating standalone modules, which include Enterprise JavaBeans and resource adapter modules. WebLogic Server also supports deploying Web Services modules, which are not part of the J2EE specification.

Standalone modules generally provide parts of a larger, distributed application, but do not necessarily provide a direct user interface. For more information on a particular module type, refer to the J2EE 1.3 specification at:

Enterprise JavaBean

Enterprise JavaBeans (EJBs) are reusable Java components that implement business logic and enable you to develop component-based distributed business applications. EJB modules are packaged as archive files having a .jar extension, but are generally deployed as exploded archive directories. The archive file or exploded archive directory for an EJB contains the compiled EJB classes, optional generated classes, and XML deployment descriptors for the EJB. See Programming WebLogic Server Enterprise JavaBeans for more information on the different types of EJBs.

Resource Adapter

A Resource Adapter (also referred to as a connector) adds Enterprise Information System (EIS) integration to the J2EE platform. Connectors provide a system-level software driver that WebLogic Server can use to connect to an EIS. Connectors contain both the Java classes, and if necessary, the native components required to interact with the EIS. See Programming WebLogic Server J2EE Connectors for more information.

Note: Resource Adapters cannot be deployed as exploded archive directories.

Web Services

Web Services are a type of service that can be shared by and used as components of distributed Web-based applications. They commonly interface with existing back-end applications, such as customer relationship management systems, order-processing systems, and so on.

A Web Service module is a virtual module that includes both a Web Application and a Web Service deployment descriptor at minimum. A Web Service module may also include EJBs that implement the Web Service. See Programming WebLogic Web Services for more information.

Deployable Applications

J2EE also defines several different types of deployable applications: Web Applications, Enterprise Applications, and client applications. Applications generally include one or more standalone J2EE modules to provide a logical service, and may also provide a direct user interface to the applications' contents.

Web Application

A Web Application always includes the following files:

Web Applications may also contain JSP tag libraries, static .html and image files, supporting classes and .jar files, and a weblogic.xml deployment descriptor, which configures WebLogic Server-specific elements for Web Applications. See Developing Web Applications for WebLogic Server for more information.

Enterprise Application

An Enterprise Application consists of one or more of the following J2EE applications or modules:

An Enterprise Application is packaged as a JAR file with an .ear extension, but is generally deployed as an exploded EAR directory. An exploded EAR directory contains all of the JAR, WAR, and RAR modules (also in exploded format) for an application as well as the XML descriptor files for the Enterprise Application and its bundled applications and modules. See Developing WebLogic Server Applications for more information.

Client Application Archives

The J2EE specification provides the ability to include a client application archive file within an Enterprise Application. A J2EE client application module contains the Java classes that execute in the client JVM (Java Virtual Machine) and deployment descriptors that describe EJBs (Enterprise JavaBeans) and other WebLogic Server resources used by the client. This enables both the server-side and client-side components to be distributed as a single unit. Client modules in an EAR are defined using the J2EE standard application-client.xml deployment descriptor and an optional WebLogic Server descriptor, client-application.runtime.xml.

Startup and Shutdown Classes

Startup and shutdown classes are Java classes that you can configure to load and execute when you start up or gracefully shut down a server. The deployment process for startup and shutdown classes differs from other deployable units, because you do not specify any actual deployment files. Instead, you identify the servers that will execute the class, and specify the classpath and optional arguments to use for execution. See Startup and Shutdown Classes in the Administration Console Online Help for more information.

XML Deployment Descriptors for Deployment Units

A key file that defines each type of deployment unit is its XML deployment descriptor. The deployment descriptor is an XML document that defines certain runtime characteristics for the application or module. By editing the XML deployment descriptor, you modify runtime behavior for the deployment unit without having to recompile code or rebuild the deployment unit itself; the new behavior is read from the descriptor file and implemented when you deploy the application or module.

For example, the WebLogic deployment descriptors for an EJB allow you to specify the number of beans to keep in the cache when you deploy the EJB to a server. If you need to change the number of cached beans for performance reasons, you simply change the deployment descriptor.

J2EE defines the organization and content of required XML deployment descriptors for each deployment unit. In addition, you can specify optional WebLogic Server XML deployment descriptors to configure WebLogic-specific behavior for handling the deployment. WebLogic Server deployment descriptors enable you to maintain the portability of the original J2EE module while utilizing features only available in WebLogic Server.

Table 1-1 lists the types of deployment units and their associated J2EE-standard and WebLogic-specific deployment descriptors.

Table 1-1 J2EE and WebLogic Deployment Descriptors

Deployment Unit


Deployment Descriptors

Web Application





Enterprise Bean











Web Service


Web Services have no J2EE descriptor. However, a Web Service module is typically packaged as an Enterprise Application that contains both a Web Application and EJB modules. For this reason, Web Services modules generally require J2EE descriptors required for those modules.



Enterprise Application





Client Application





You create deployment descriptors manually, or generate them with WebLogic Server Java-based utilities. When you receive a J2EE-compliant JAR file from a developer, it should already contain the J2EE-defined and WebLogic Server deployment descriptors. The Administration Console also enables you to modify key deployment descriptor elements of a deployed application, which can help you tune the application's run-time behavior and performance.


Deployment Files

WebLogic Server allows you to store deployment units either as a single archive file, or as an exploded directory that contains the same contents of the archive file.

Archive Files

In most production environments, you receive a deployment unit as an archive file. 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. Archive files are typically created by using the jar utility or Ant's jar tool.

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

Note: Startup and shutdown classes are not packaged—you simply specify the classpath to use when assigning target servers.

Although you can deploy an archive file directly to WebLogic Server, deploying Exploded Archive Directories provides some additional redeployment capabilities.

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.

A deployment unit should be deployed as an exploded archive directory, rather than a single archive file, in the following circumstances:

Unpacking 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 file.

Location of Files

To deploy a new archive or exploded archive directory, the file(s) must be accessible by the Administration Server for your domain. This means they must reside on the Administration Server machine, or they must be available via a remote, network-mounted directory.

When using the Administration Console to deploy a module for the first time, you have the option to upload files to the Administration Server machine if they are not otherwise available. Files are uploaded to the location specified by the Upload Directory Name attribute.


Deployment Targets

Deployment targets are the servers to which you deploy an application or standalone module. Valid deployment targets include WebLogic Server instances, clusters, and virtual hosts. During the deployment process, you select the list of targets from the available servers, clusters, and virtual hosts configured in your domain. You can also change the target list at any time after you have deployed a module.

The following sections describe target types in more detail.

WebLogic Server Instances

You can deploy applications and standalone modules to one or more Managed Servers in a domain, or to the Administration Server in a single-server domain. Although you can deploy to the Administration Server in a multiple-server domain, this practice is not recommended. The Administration Server in a multiple-server domain should be used only for administration purposes.


If you are deploying to a cluster of WebLogic Server instances, by default the deployment targets all server instances in the cluster. This corresponds to homogenous module deployment, which is recommended in most clusters. If you want to deploy a module only to a single server in the cluster (that is, "pin" a module to a servers), you can also select the individual server name. This type of deployment is less common, and should be used only in special circumstances where pinned services are required. See Understanding Cluster Configuration and Application Deployment for more information.

Note: Pinning a deployment to a subset of server instances in a cluster (rather than a single server) is not recommended and will generate a warning message.

Virtual Hosts

Virtual hosting allows you to define host names to which servers or clusters respond. When you use virtual hosting, you use DNS naming to specify one or more host names that map to the IP address of a WebLogic Server or cluster, and you specify which applications are served by each virtual host.

You select a configured virtual host name as you would a WebLogic Server instance or cluster name during deployment. See Configuring Virtual Hosting in Configuring and Managing WebLogic Server for more information.

Note: If the context root for a Web Application is blank in weblogic.xml file and the virtual host is targetted to a server instance, the Web Application should be deployed only to the Virtual Host or to the server instance.


Staging Modes

The deployment staging mode determines how deployment files are made available to target servers that must deploy an application or standalone module. WebLogic Server provides three different options for staging files: stage mode, nostage mode, and external_stage mode. The following table describes the behavior and best practices for using the different deployment staging modes.

Table 1-2 Application Deployment Staging Modes

Deployment Staging Mode


When to Use


The Administration Server first copies the deployment unit source files to the staging directories of target servers specified by the Staging Directory Name attribute.

The target servers then deploy using their local copy of the deployment files.

  • Deploying small or moderate-sized applications to multiple WebLogic Server instances.

  • Deploying small or moderate-sized applications to a cluster.


The Administration Server does not copy deployment unit files. Instead, all servers deploy using the same physical copy of the deployment files, which must be directly accessible by the Administration Server and target servers.

With nostage deployments of exploded archive directories, WebLogic Server automatically detects changes to a deployment's JSPs or Servlets and refreshes the deployment. (This behavior can be disabled if necessary.)

  • Deploying to a single-server domain.

  • Deploying to a cluster on a multi-homed machine.

  • Deploying very large applications to multiple targets or to a cluster where deployment files are available on a shared directory.

  • Deploying exploded archive directories that you want to periodically redeploy after changing content.

  • Deployments that require dynamic update of selected Deployment Descriptors via the Administration Console.


The Administration Server does not copy deployment files. Instead, the Administrator must ensure that deployment files are distributed to the correct staging directory location before deployment (for example, by manually copying files prior to deployment).

With external_stage deployments, the Administration Server requires a copy of the deployment files for validation purposes. Copies of the deployment files that reside in target servers' staging directories are not validated before deployment.

  • Deployments where you want to manually control the distribution of deployment files to target servers.

  • Deploying to domains where third-party applications or scripts manage the copying of deployment files to the correct staging directories.

  • Deployments that do not require dynamic update of selected Deployment Descriptors via the Administration Console (not supported in external_stage mode).

  • Deployments that do not require partial redeployment of application components.

Most deployments use either stage or nostage modes, and the Administration Console automatically suggests the appropriate mode when you deploy an application or module. For more information about staging modes, see Deployment Staging Modes and Staging Directories in Advanced Deployment Topics.


Deployment Names

When you first deploy an application or standalone 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. For exploded archive directories, the default deployment name is the name of the top-level directory you deploy. For archive files, the deployment name is the name of the archive file without the file extension (myear for the file myear.ear).


Deployment Tools

WebLogic Server provides several tools for deploying applications and standalone modules:


Best Practices for Deployment

BEA recommends the following best practices when deploying applications:


Deployment Operations

The deployment tools provide support for performing these common deployment operations:


Security Roles Required for Deployment

The built-in security roles for "Admin" and "Deployer" users allow you to perform deployment tasks using the WebLogic Server Administration Console. See Starting the Administration Console in the Administration Console Online Help for more information about the built-in security roles.


Skip navigation bar  Back to Top Previous Next