bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Using WebLogic Server Clusters

Understanding Cluster Configuration and Application Deployment

The following sections describe how cluster configuration information is stored and maintained:

- Cluster Configuration and config.xml

- Role of the Administration Server

- How Dynamic Configuration Works

- Application Deployment Topics

- Methods of Configuring Clusters

Note: Much of the information in this section also pertains to the process of configuring a WebLogic domain in which the server instances are not clustered.

Cluster Configuration and config.xml

The config.xml file is an XML document that describes the configuration of a WebLogic Server domain. The content and structure of the config.xml is defined in the associated Document Type Definition (DTD), config.dtd.

config.xml consists of a series of XML elements. The Domain element is the top-level element, and all elements in the Domain descend from the Domain element. The Domain element includes child elements, such as the Server, Cluster, and Application elements. These child elements may have children of their own. For example, the Server element includes the child elements WebServer, SSL and Log. The Application element includes the child elements EJBComponent and WebAppComponent.

Each element has one or more configurable attributes. An attribute defined in config.dtd has a corresponding attribute in the configuration API. For example, the Server element has a ListenPort attribute, and likewise, the weblogic.management.configuration.ServerMBean has a ListenPort attribute. Configurable attributes are readable and writable, that is, ServerMBean has a getListenPort and a setListenPort method.

To learn more about config.xml, see BEA WebLogic Server Configuration Reference

Role of the Administration Server

The Administration Server is the WebLogic Server instance that configures and manages the WebLogic Server instances in its domain.

A domain can include multiple WebLogic Server clusters and non-clustered WebLogic Server instances. Strictly speaking, a domain could consist of only one WebLogic Server instance—however, in that case that sole server instance would be an Administration Server, because each domain must have exactly one Administration Server.

There are a variety of ways to invoke the services of the Administration Server to accomplish configuration tasks, as described in Methods of Configuring Clusters. Whichever method is used, the Administration Server for a cluster must be running when you modify the configuration.

When the Administration Server starts, it loads the config.xml for the domain. It looks for config.xml in the current directory. Unless you specify another directory when you create a domain, config.xml is stored in:

BEA_HOME/user_projects/mydomain

where mydomain is a domain-specific directory, with the same name as the domain.

Each time the Administration Server starts successfully, a backup configuration file named config.xml.booted is created in the domain directory. In the unlikely event that the config.xml file should be corrupted during the lifetime of the server instance, it is possible to revert to this previous configuration.

The following figure shows a typical production environment that contains an Administration Server and multiple WebLogic Servers instances. When you start the server instances in such a domain, the Administration Server is started first. As each additional server instance is started, it contacts the Administration Server for its configuration information. In this way, the Administration Server operates as the central control entity for the configuration of the entire domain.

Figure 3-1 WebLogic Server Configuration

What Happens if the Administration Server Fails?

The failure of an Administration Server for a domain does not affect the operation of Managed Servers in the domain. If an Administration Server for a domain becomes unavailable while the server instances it manages—clustered or otherwise—are up and running, those Managed Servers continue to run. If the domain contains clustered server instances, the load balancing and failover capabilities supported by the domain configuration remain available, even if the Administration Server fails.

Note: If an Administration Server fails because of a hardware or software failure on its host machine, other server instances on the same machine may be similarly affected. However, the failure of an Administration Server itself does not interrupt the operation of Managed Servers in the domain.

For instructions on re-starting an Administration Server, see "Restarting an Administration Server When Managed Servers are Running" in Creating and Configuring WebLogic Server Domains.

How Dynamic Configuration Works

WebLogic Server allows you to change the configuration attributes of domain resources dynamically—while server instances are running. In most cases you do not need to restart the server instance for your changes to take effect. When an attribute is reconfigured, the new value is immediately reflected in both the current run-time value of the attribute and the persistent value stored in config.xml.

Not all configuration changes are applied dynamically. For example, if you change a WebLogic Server instance's ListenPort value, the new port will not be used until the next time you start the affected server instance. The updated value is stored in XML file, but the current runtime value is not affected. When the runtime value for a configuration attribute is different than the value stored in config.xml, the Administration Console displays an alert icon next to the attribute, which indicates that the server instance must be restarted for the configuration change to take effect.

The console does a validation check on each attribute that users change. The validation performed includes checking for out-of-range errors and datatype mismatch errors. In both cases, an error dialog box is displayed.

Once the Administration Console has been started, if another process captures the listen port assigned to the Administration Server, you should stop the process that captured the port. If you are not able to remove the process that captured the list port, edit the config.xml file to change the ListenPort value.

Application Deployment Topics

This section is brief introduction to the application deployment process. For more information about deployment, see "WebLogic Server Deployment" in Developing WebLogic Server Applications.

For instructions on how to perform common deployment tasks, see Deploy Applications.

Deployment Methods

You can deploy an application to a cluster using following methods:

- WebLogic Server Administration Console

  The Administration Console is a graphical user interface (GUI) to the BEA Administration Service.

- WebLogic Builder

  WebLogic Builder is a graphical tool for assembling a J2EE component, creating and editing its deployment descriptors, and deploying it to a WebLogic Server.

- weblogic.Deployer

  The weblogic.Deployer utility is a Java-based deployment tool that provides a command-line interface to the WebLogic Server deployment API.

These deployment tools are discussed in "Deployment Tools and Procedures" in Developing WebLogic Server Applications.

Regardless of the deployment tool you use, when you initiate the deployment process you specify the components to be deployed, and the targets to which they will be deployed—your cluster, or individual server instances within the cluster or domain.

The Administration Server for the domain manages the deployment process, communicating with the Managed Servers in the cluster throughout the process. Each Managed Server downloads components to be deployed, and initiates local deployment tasks. The deployment state is maintained in the relevant MBeans for the component being deployed. For more information, see "Deployment Management API" in Developing WebLogic Server Applications.

Note: You must package components before you deploy them to WebLogic Server. For information about packaging applications, see "WebLogic Server Application Packaging" in Developing WebLogic Server Applications.

Introduction to Two-Phase Deployment

In WebLogic Server 7.0, applications are deployed in two phases: the prepare phase and the activation phase.

When the user initiates application deployment to a cluster, before starting the prepare phase, WebLogic Server first determines the availability of the Managed Servers in the cluster.

Preparing a Deployment

During the prepare phase of deployment, application components are distributed to the target servers instances, in accordance with user selections, and the planned deployment is validated. (In a cluster, applications should be targeted to the cluster, rather than to individual Managed Servers.) The purpose of the prepare phase is to verify that the application components can be successfully deployed. During this phase, user requests to the application being deployed are not allowed.

Failures encountered after initiation of the prepare phase will result in the deployment being aborted on all server instances—including those that successfully acknowledged the prepare. Files that have been staged will not be removed; however, container-side changes performed during the preparation will be reverted.

Activating a Deployment

During activation, the application and its component are fully deployed on the target server instances, and the deployed application is made available to clients.

If a failure occurs during the activation phase on a server instance, deployment to that instance will be cancelled. Such a failure on one Managed Server does not prevent activation of the deployment on other clustered server instances.

If a cluster member fails to deploy an application, it will fail at startup in order to ensure cluster consistency—as any failure of a cluster-deployed application on a Managed Server causes the Managed Server to abort its startup.

Guidelines for Deploying to a Cluster

Ideally, all Managed Servers in a cluster should be running and available during the deployment process. Deploying applications while some members of the cluster are unavailable is not recommended. Before deploying applications to a cluster, ensure, if possible, that all Managed Servers in the cluster are running and reachable by the Administration Server.

Cluster membership should not change during the deployment process. After initiating deployment, do not:

- add or remove Managed Servers to the target cluster

- shut down Managed Servers in the target cluster

WebLogic Server 7.0 Deployment Restrictions

WebLogic Server 7.0 imposed restrictions on deployment to clusters, described in:

- WebLogic Server 7.0 Does Not Allow Deployment into a Partial Cluster, and

- WebLogic Server 7.0 Does Not Allow Deployment of Pinned Services to Multiple Managed Servers.

WebLogic Server 7.0 Does Not Allow Deployment into a Partial Cluster

WebLogic Server 7.0 does not allow deployment into a partial cluster. If one or more of the Managed Servers in the cluster are unavailable, the deployment process is terminated, and an error message is generated, indicating that unreachable Managed Servers should be either restarted or removed from the cluster before attempting deployment.

WebLogic Server 7.0 Does Not Allow Deployment of Pinned Services to Multiple Managed Servers

WebLogic Server 7.0 does not allow you to deploy a pinned service to multiple individual Managed Servers in a cluster. In WebLogic Server 7.0, if an application is not deployed to the cluster, you can deploy it to one and only one Managed Server in the cluster.

WebLogic Server 7.0 SP1 and Later Support "Relaxed Deployment" Rules

WebLogic Server 7.0 SP01 relaxed the deployment rules described in WebLogic Server 7.0 Deployment Restrictions and allows user discretion in deployment practices. For details, see:

- WebLogic Server 7.0 SP01 and Later Allows Deployment to a Partial Cluster.

- Deploying to Complete Clusters in WebLogic Server 7.0 SP1 and Later.

- Pinned Deployment in WebLogic Server 7.0 SP01 and Later.

WebLogic Server 7.0 SP01 and Later Allows Deployment to a Partial Cluster

By default, WebLogic Server 7.0 SP01and later allow deployment to a partial cluster. If one or more of the Managed Servers in the cluster are unavailable, the following message may be displayed:

>     Cannot deploy to the following server(s) because they are
>     unreachable: "managed_server_n". Make sure that these servers are
>     currently shut down. Deployment will continue on the remaining
>     servers in the cluster "clustering". Once deployment has commenced,
>     do not attempt to start or shutdown any servers until the
>     application deployment completes.

When the unreachable Managed Server becomes available, deployment to that server instance will be initiated. Until the deployment process is completed, the Managed Server may experience failures related to missing or out-of-date classes.

Deploying to Complete Clusters in WebLogic Server 7.0 SP1 and Later

You can ensure that deployment is only performed if all Managed Servers in the cluster are reachable by setting the enforceClusterConstraints flag with weblogic.Deployer. When enforceClusterConstraints is set to "true", deployment will occur in accordance with the rules described in WebLogic Server 7.0 Deployment Restrictions

Pinned Deployment in WebLogic Server 7.0 SP01 and Later

In WebLogic Server 7.0 SP01 and later, it is possible to target a pinned service to multiple Managed Servers in a cluster. This practice is not recommended. The load-balancing capabilities and scalability of your cluster can be negatively affected by deploying a pinned service to multiple Managed Servers in a cluster. If you target a pined service to multiple Managed Servers, the following message is printed to the server logs:

>     Adding server servername of cluster clustername as a target for
>     module modulename. This module also includes server servername that
>     belongs to this cluster as one of its other targets. Having multiple
>     individual servers a cluster as targets instead of having the entire
>     cluster as the target can result in non-optimal load balancing and
>     scalability. Hence this is not usually recommended.

Methods of Configuring Clusters

There are several methods for modifying the configuration information in config.xml:

- Domain Configuration Wizard

  The Domain Configuration Wizard is the recommended tool for creating a new domain or cluster. For a list of the tasks you can perform with the wizard, see Domain Configuration Wizard Capabilities later in this section.

- WebLogic Server Administration Console

  The Administration Console is a graphical user interface (GUI) to the BEA Administration Service. It allows you to perform a variety of domain configuration and monitoring functions. For a list of the tasks you can perform with the console, see Administration Console Capabilities.

- WebLogic Server Application Programming Interface (API)

  You can write a program to modify the configuration attributes, based on the configuration application programming interface (API) provided with WebLogic Server. This method is not recommended for initial cluster implementation.

- WebLogic Server command-line utility.

  You can access the attributes of a domain with the WebLogic Server command-line utility. This utility allows you to create scripts to automate domain management. This method is not recommended for initial cluster implementation.

Domain Configuration Wizard Capabilities

The Domain Configuration Wizard uses pre-configured domain templates to ease the process of creating a domain and its server instances. Using the wizard, you can select a domain template, and then supply key information, such as machine addresses, names, and port numbers for the server instances you wish to created.

Note: The Domain Configuration Wizard can install the appropriate directory structure and scripts for a domain on a Managed Server that is running on a remote machine from the Administration Server. This is helpful if you need to use a Managed Server as a backup Administration Server for a domain.

The wizard prompts you to select one of four typical domain configurations:

- Single Server—domain with a single WebLogic Server instance.

- Administration Server with Managed Servers—domain with an Administration Server, and one or more Managed Servers that are not clustered.

- Administration Server with clustered Managed Servers—domain with an Administration Server, and one or more Managed Servers that are clustered.

- Managed Server (Owning Administrative Configuration)

After you select the desired configuration type, the wizard prompts you to provide relevant details about the domain and its server instances.

For information on how to use the Domain Configuration Wizard, see "Creating New Domains Using the Configuration Wizard" in Creating and Configuring WebLogic Server Domains.

Administration Console Capabilities

This section summarizes the tasks you can perform using the WebLogic Server Administration Console. See "Administration Console Online Help" for information on how to perform these tasks using the console.

WebLogic Server Configuration Tasks

- Configure a server

- Clone a server

- Delete a server

- Force garbage collection on a server

- Assign XML registries to a server

- Assign mail sessions to a server

- Assign File T3s to a server

- Assign JDBC connection pools to a server

- Assign WLEC connection pools to a server

WebLogic Cluster Configuration Tasks

- Configure a cluster of server instances

- Clone a cluster of server instances

- Assign server instances to a cluster

- Delete a cluster

Deployment Tasks

- Deploy EJBs on a server instance

- Deploy Web Application components on a server instance

- Deploy startup and shutdown classes on a server instance

Viewing and Monitoring Tasks

- View log for a server instance

- View JNDI tree for a server instance

- View execute queues for a server instance

- View execute threads for a server instance

- View sockets for a server instance

- View connections for a server instance

- View version of a server instance

- Monitor security for a server instance

- Monitor clusters

- Monitor all EJB deployments on a server instance

- Monitor all Web Application components on a server instance

- Monitor all WLEC connection pools assigned to a server instance

- Monitor server instances assigned to a cluster