Configuring a Clustered Deployment

This section describes the tasks that you must perform to configure WebLogic Integration for deployment in a clustered environment.

For information about deploying WebLogic Integration on a single server, see "Creating and Customizing a New Domain" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration.

Plan the architecture of your clustered domain, as described in Designing a Clustered Deployment; then set up WebLogic Integration in a clustered environment. To do this, you must configure a router (hardware or software), an administration server, and managed servers and deploy WebLogic Integration resources to the servers. The persistent configuration for a domain of WebLogic Server instances and clusters is stored in an XML configuration file (config.xml) on the administration server.

To set up and deploy WebLogic Integration in a clustered domain, complete the following steps:

• Step 1. Comply with Configuration Prerequisites

• Step 2. Create a WebLogic Integration Domain

• Step 3. Configure the Database for Your Domain

• Step 4. Configure BPM Resources for One Managed Server

• Step 5. Configure Event Router WAR File for Adapters

• Step 6. Configure an RDBMS Realm

• Step 7. Configure a Router

• Step 8. Edit the startWeblogic Command File

• Step 9. Set Up Managed Servers for Your Domain

• Step 10. Configure WebLogic Integration for Automatic Restart

• Step 11. Configure WebLogic Integration for Migration from Failed to Healthy Node

• Step 12. Configure WebLogic Integration Security

• Step 13. Start the Servers in the Domain

 

---

Step 1. Comply with Configuration Prerequisites

This section describes prerequisites for configuring WebLogic Integration to run in a clustered environment:

• Obtain a WebLogic Server cluster license for each required installation.

  To use WebLogic Server in a clustered configuration, you must have a special cluster license. Contact your BEA representative for information about obtaining one.

• Obtain an IP address for the administration server you will use for the cluster.

  All WebLogic Server instances in a cluster use the same administration server for configuration and monitoring. When you add servers to a cluster, you must specify the administration server that each will use.

• Define a multicast address for each cluster

  Note: You are prompted to provide a multicast address when you create a WebLogic Integration domain using the Configuration Wizard. (See Step 2. Create a WebLogic Integration Domain.)

  The multicast address is used by cluster members to communicate with each other. Clustered servers must share a single, exclusive multicast address. For each cluster on a network, the combination of multicast address and port must be unique. If two clusters on a network use the same multicast address, they should use different ports. If the clusters use different multicast addresses, they can use the same port or accept the default port, 7001. To support multicast messages, the administration server and the managed servers in a cluster must be located on the same subnet.

• Define IP addresses for the servers in your cluster. You can do this in a number of ways:

  Note: You are prompted to provide a listen addresses for servers when you create a WebLogic Integration domain using the Configuration Wizard. (See Step 2. Create a WebLogic Integration Domain.)

  • Assign a single IP address and different listen port numbers to the servers in the cluster.

    By assigning a single IP address for your clustered servers with a different port number for each server, you can set up a clustered environment on a single machine without the need to make your machine a multihomed server.

    To access such an IP address from a client, structure the IP address and port number in your URL in one of the following ways:

    ipAddress:portNumber-portNumber	When the port numbers are sequential, for example: 127.0.0.1:7003-7005
    ipAddress:portNumber+...+portNumber	When the port numbers are not sequential, for example: 127.0.0.1:7003+7006+7008
    ipAddress:portNumber,ipAddress:portNumber,...	Verbose, explicit specification, for example: 127.0.0.1:7003,127.0.0.1:7004,127.0.0.1:7005

    
     

  • Assign a static IP address for each WebLogic Server instance to be started on each machine in the cluster.

    In this case, when multiple servers are run on a single machine, that machine must be configured as a multihomed server, that is, multiple IP addresses are assigned to a single computer.

    In this case, structure the cluster address as a comma-separated list of IP addresses. For example, the following listing is an example of a cluster address specified in a config.xml file. It specifies a static IP address for each of the four servers in a cluster named MyCluster:

    <Cluster ClusterAddress="127.0.0.1:7001,127.0.0.2:7001,127.0.0.3,127.0.0.4:7001" Name="MyCluster"/>

    Note: For development and testing, you can use a comma-separated list. However, for production, it is recommended that you specify the cluster address only as a DNS name or a single IP address. If you do not use a DNS name for the ClusterAddress, you should set the wlai.clusterFrontEndHostAndPort property to support load balancing and high availability for event router callback communication (application integration functionality). For information about setting this property, see Setting the wlai.clusterFrontEndHostAndPort Property (Optional).

• Configure an Oracle, Microsoft SQL, Sybase, or DB2 database for your clustered domain.

• Include a shared file system. A shared file system is strongly recommended for any cluster in which B2B integration functionality is used. A shared file system is required for any cluster you want to be highly available. We recommend either a Storage Area Network (SAN) or a multiported disk system.

• Configure a hardware or software router for your system. Load balancing of servlets and JSPs can be accomplished using either the built-in load balancing capabilities of a WebLogic proxy plug-in, or separate load balancing hardware.

  For information about configuring a software router for your WebLogic Integration domain, see Step 7. Configure a Router.

  For information about hardware and software routers, see Using WebLogic Server Clusters, which is available at the following URL:

  http://download.oracle.com/docs/cd/E13222_01/wls/docs70/cluster/index.html

For more information about setting up clustered WebLogic Server instances, see Setting Up WebLogic Clusters in Using WebLogic Server Clusters, which is available at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/cluster/index.html

Note: Additional requirements apply when you design your domain to include one or more firewalls. For details, see Communications in a Cluster in Using WebLogic Server Clusters, which is available at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/cluster/index.html

Setting the wlai.clusterFrontEndHostAndPort Property (Optional)

Application integration adapters generate events that are consumed by the BPM engine. For information about events and event processing in WebLogic Integration, see Events.

When you do not use a DNS name for your cluster address, you should set the wlai.clusterFrontEndHostAndPort property to achieve load balancing and high availability for event router callback communication.

Why Set the wlai.clusterFrontEndHostAndPort Property?

The following table describes the cluster configuration in a sample cluster, for which the cluster address is:

<Cluster ClusterAddress="127.0.0.1:7001,127.0.0.1:7002" Name="MyCluster"/> 

Server Name	Server Type	Listen Address:Port
MyAdmin	Administration Server	127.0.0.5:7005
MyServer1	Managed Server	127.0.0.1:7001
MyServer2	Managed Server	127.0.0.1:7002
MyRouter	Router	127.0.0.1:7003

 

An event router uses obtains metadata about events by communicating with an instance of WebLogic Integration through HTTP. Exactly how such communication occurs is determined by whether or not the wlai.clusterFrontEndHostAndPort property is set:

• If the wlai.clusterFrontEndHostAndPort property is not set . . .

  As a result, upon establishment of communication with the event router, WebLogic Integration passes the first address listed in ClusterAddress as the callback address. In our example, the callback address is 127.0.0.1:7001. In this scenario, if MyServer-1 fails, then event routers cannot contact the WebLogic Integration application, even though MyServer-2 is still running.

• If the wlai.clusterFrontEndHostAndPort property is set . . .

  The wlai.clusterFrontEndHostAndPort property is set to the address of the cluster front-end, in this case, the MyRouter server, which hosts the HttpClusterServlet.

  As a result, upon establishment of communication with the event router, WebLogic Integration passes the following address to the event router: 127.0.0.1:7003. Even if a managed server in the cluster fails, event routers can still contact the WebLogic Integration application in this scenario.

How to Set the wlai.clusterFrontEndHostAndPort Property

You must create a wlai.clusterFrontEndHostAndPort property in the WLAIStartup EJB environment properties for each managed server. For example, to set wlai.clusterFrontEndHostAndPort=127.0.0.1:7003, complete the following procedure:

1. In the Administration Console navigation tree, choose Domain_Name—>Deployments—>EJB—>WLI-AI Server.

2. Click Edit EJB Descriptor to display a new window, in which you can edit the EJB descriptor.

3. In the left navigation pane of the new window, choose EJB Jar—>Enterprise Beans—>Sessions—>WLAIStartup—>Env Entries to display a configuration window.

4. Click Configure a New Environment Entry.

5. Enter the following information:

   • Env Entry Name: wlai.clusterFrontEndHostAndPort

   • Env Entry Value: 127.0.0.1:7003

     127.0.0.1:7003 represents the listen address and port for the cluster front-end (in this case, the router) that hosts the HttpClusterServlet.

 

---

Step 2. Create a WebLogic Integration Domain

To complete this step, you must add a definition for each managed server to the domain configuration file (config.xml), assign all managed servers to a cluster, specify the WebLogic Integration components on the servers in your domain, and so on.

You begin the definition of a clustered WebLogic Integration deployment by creating a domain using the BEA Configuration Wizard.

Note: The procedure described in this section for setting up your domain is based on the assumption that you are running the Configuration Wizard in GUI mode from the Windows Start menu.

For information about using the Configuration Wizard in different modes, see Using the Configuration Wizard, which is available at the following URL:

http://download.oracle.com/docs/cd/E13196_01/platform/docs70/confgwiz/index.html

To create a WebLogic Integration domain using the Configuration Wizard, complete the following steps:

1. From the Start Menu, choose Programs—>BEA WebLogic Platform 7.0—>Domain Configuration Wizard.

   The Configuration Wizard is launched. It prompts you for data with which to configure your domain.

2. Respond to the Configuration Wizard prompts by providing the information described in the following table.

In this window . . .	Perform the following action . . .
Choose a Domain Type and Name	Select a template on which to base your domain and assign a name to your domain. Select one of the following domain templates, depending on the requirements for your domain: WLI Domain—Use this template when you want your domain to support all WebLogic Integration functionality: BPM, B2B integration, application integration, and data integration. WLI BPM—Use this template when you want your domain to support BPM and data integration functionality. WLI EAI—Use this template when you want your domain to support application integration, BPM, and data integration functionality.
Choose Server Type	Select the following option when you are prompted for the server type: Admin Server with Clustered Managed Server(s)
Choose Domain Location	Specify a directory in which to install your domain. Accept the default directory or browse to select a different one. Any valid directory on your machine can be used as the domain directory.
Configure Clustered Servers	Specify the server name, listen address, and listen port for each managed server in your cluster.1
Configure Cluster	Specify the cluster name, cluster multicast address, cluster multicast port, and cluster address.1
Configure Standalone/Administrative Server	Specify the server name, server listen address, server listen port, and server SSL listen port for the administration server, from which all administrative functions for your clustered domain will be performed.1 Note: When you configure the administration server, we recommend that you accept the default Server Name (myserver), as prompted by the Configuration Wizard. If you specify a server name other than the default, you must change the name of the following directory in your domain, by replacing myserver with the new name you specified: DOMAIN_HOME/applications/DefaultWebApp_myserver In the preceding path, DOMAIN_HOME represents the root directory of the custom domain you created using the Configuration Wizard.
Create Administrative User	Specify a user name and password.
Create Start Menu Entry for Server	Specify whether you want to install the administration server in the Windows Start menu.
Configuration Summary	Do one of the following: Review the configuration summary information and click Create to create the defined domain. Review the configuration summary information and click Previous to return to windows you have already viewed, so you have an opportunity to change information that you supplied earlier, before creating the domain.

1. For information about setting up addresses and port numbers, see Step 1. Comply with Configuration Prerequisites.

 

When you complete the domain configuration using the Configuration Wizard, your new domain is created in the location you specified earlier. A configuration file (config.xml) is created in the domain. It contains a definition for the administration server and each managed server in the cluster, and it assigns the managed servers to the cluster.

Note: In the steps that follow in this procedure, you will edit the config.xml file to configure your clustered domain. Therefore, we recommend that before proceeding to the next step, you save a backup copy of the config.xml file created in this step.

 

---

Step 3. Configure the Database for Your Domain

The Database Wizard is a WebLogic Integration configuration utility that facilitates the task of setting up a database for the domain you created in the preceding step.

To run the Database Wzard:

1. Run the wliconfig script in the domain you created in step 2.

   If, for example, you created a domain named mydomain in the default location, run one of the following command sequences (depending on your operating system):

   • Windows:

     cd %BEA_HOME%\user_projects\mydomain
     wliconfig

   • UNIX:

     cd $BEA_HOME/user_projects/mydomain
     wliconfig

2. The Database Wizard provides the following options:

   • Switch Database
     Select this option to designate a different database to be used for the domain. The environment variables used by commands that are invoked to initialize the database (commands such as CreateDB and RunSamples) are updated, and the config.xml file is modified to reflect the new settings. This option does not initialize the database; rather, it configures the environment in preparation for database initialization.

   • Create Database
     Select this option to initialize the database currently specified, or to switch to a new database and initialize it.

3. The Database Wizard prompts you to provide the values required to connect to the database you are configuring.

For information about running the Database Wizard, see "Using the Database Wizard" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration.

 

---

Step 4. Configure BPM Resources for One Managed Server

As described in JMS Servers and JMS Destinations, and in Deploying WebLogic Integration Resources, the following BPM resources must be deployed to a single node in your cluster:

• The WLI-BPM Plugin Manager, for which the URI is wlpi-master-ejb.jar.

• The EventTopic JMS topic, for which the JNDI name is com.bea.wlpi.EventTopic.

You must modify your domain configuration to meet this requirement. You can do this in one of two ways:

• Edit the Configuration File

• Use the WebLogic Server Administration Console

Edit the Configuration File

The config.xml file in your domain contains comments to help you quickly identify and edit the elements that must be changed. Complete the following steps to make the required changes to the domain's configuration file:

1. In the root directory of the domain you created, open the config.xml file in a text editor.

2. Search for comments labeled with the word MODIFY.

   The following table shows the elements in the configuration file labeled with a MODIFY comment, and describes the modifications you are required to make.

Table 3-1 Configuring BPM Resources for One Managed Server

Locate the element . . .	To modify the element . . .
<!-- MODIFY: In a cluster, the BPM Plugin Manager Targets attribute must specify only ONE cluster server --> <EJBComponent Name="WLI-BPM Plugin Manager" Targets="mycluster" URI="wlpi-master-ejb.jar"/>	Change the Targets attribute to deploy the WLI-BPM Plugin Manager EJB component to a managed server, represented, in this case, by managedserver-1: <EJBComponent Name="WLI-BPM Plugin Manager" Targets="managedserver-1" URI="wlpi-master-ejb.jar"/>
<!-- MODIFY: This JMS Topic must be deployed to only one node in the cluster. Uncomment this section for one node. <JMSTopic Name="wlpiEvent" JNDIName="com.bea.wlpi.EventTopic"/> -->	Uncomment this JMSTopic element for one, and only one, managed server in the cluster configuration: <JMSTopic Name="wlpiEvent" JNDIName="com.bea.wlpi.EventTopic"/>

 

3. Proceed to Step 5. Configure Event Router WAR File for Adapters.

Use the WebLogic Server Administration Console

If you start the administration server in your domain before making the changes described in the preceding table, comments that were written in the config.xml file are lost. However, if the comments are lost, you can still configure your system appropriately, by following the procedures described in the following sections:

• Configure BPM Master EJB for One Managed Server

• Configure BPM Event Topic for One Managed Server

Configure BPM Master EJB for One Managed Server

The simplest method to configure the BPM master EJB for one managed server is to modify the domain configuration file, as described in Table  3-1.

Note: The following procedure is provided for reference only. Use it, for example, if the comments in your config.xml file are lost before you complete the configuration.

To configure the BPM Master EJB for a single managed server:

1. In the Administration Console navigation tree, select the WLI-BPM Plugin Manager EJB in the domain you created:

   Domain_Name—>Deployments—>EJB—>WLI-BPM Plugin Manager

2. Select the Targets tab and follow the instructions in the Administration Console to change the deployment settings in such a way that the WLI-BPM Plugin Manager EJB is deployed to only one managed server in your cluster.

   For more information about using the Administration Console to configure the deployment of EJBs, see the WebLogic Server Adminstration Console Online Help, which is available at the following URL:

   http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ConsoleHelp/index.html 

After you create your domain, following the procedures in Step 2. Create a WebLogic Integration Domain, the WLI-BPM Plugin Manager is targeted to the cluster. In other words, the Targets attribute contains the cluster name.

After you complete the required modification, the WLI-BPM Plugin Manager EJB should be targeted to a single managed server in your cluster. The following excerpt shows the edited config.xml file, which illustrates the configuration change in the Targets attribute. In this example, the EJB is targeted to a managed server named manageserver-1.

Listing 3-1 Targeting WLI-BPM Plugin Manager to a Managed Server

<Application Name="WebLogic Integration" Deployed="false"
Path="C:/bea/weblogic700/integration/lib" TwoPhase="true">

...
<EJBComponent Name="WLI-BPM Plugin Manager" Targets="manageserver-1"
URI="wlpi-master-ejb.jar"/>

...
</Application>

Configure BPM Event Topic for One Managed Server

The simplest method to complete your domain configuration is to modify the domain configuration file, as described in Step 4. Configure BPM Resources for One Managed Server.

Note: The following procedure is provided for reference only. Use it, for example, if the comments in your config.xml file are lost before you complete the configuration.

To configure a BPM Event Topic for a single managed server:

1. In the Administration Console navigation tree, select Destinations for a JMS server. For example, choose:

   Services—>JMS—>Servers—>WLIJMSServer_manageserver-1—>Destinations

   WLIJMSServer_manageserver-1 represents the name of the JMS server that is specific to one managed server in your domain.

   Note: You can assign any name you choose to the JMS server. However, we recommend that you follow the naming convention used in this example: WLIJMSServer_node. When this convention is used, node represents the name of the server on which the JMS server is deployed.

2. Click Configure a New JMS Topic to display the Configuration tab.

3. Enter the following information in the appropriate fields:

   • Name: wlpiEvent

   • JNDI Name: com.bea.wlpi.EventTopic

4. Accept the defaults for the remainder of the fields, and click Apply.

For more information about creating new JMS queues and topics, see the WebLogic Server Adminstration Console Online Help, which is available at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ConsoleHelp/index.html 

The following listing is an excerpt from a config.xml file to which the BPM Event Topic is added to the JMSServer element for a managed JMS server. (In this case, the managed server is named WLIJMSServer_manageserver1.) The section of code being highlighted in this listing is shown in bold.

Listing 3-2 Configuration for com.bea.wlpi.EventTopic

<JMSServer Name="WLIJMSServer_manageserver1"
            Targets="manageserver1 (migratable)"
            TemporaryTemplate="TemporaryTemplate"
            Store="JMSWLIStore_manageserver1">

            <JMSTopic Name="wlpiEvent" JNDIName="com.bea.wlpi.EventTopic"/>

...
</JMSServer>

 

---

Step 5. Configure Event Router WAR File for Adapters

Note: This step is required only for domains that are based on the WebLogic Integration or the EAI domain templates. If your clustered domain is based on the BPM domain template, proceed to Step 6. Configure an RDBMS Realm.

As described in Deploying WebLogic Integration Resources, the event router WAR files for sample adapters must be deployed on a single node in a cluster. To meet this requirement, you must edit your domain configuration for the adapters that are configured as part of your WebLogic Integration domain or your EAI domain: BEA_WLS_DBMS_ADK and BEA_POWERENTERPRISE_3_0 adapters.

To change your configuration, you can use the WebLogic Server Administration Console, or you can edit the config.xml file in your domain.

Using the Administration Console

1. In the Administration Console navigation tree, select the following event router WAR files in the domain you created:

   • Domain_Name—>Deployments—>WebApplications—>DbmsEventRouter

   • Domain_Name—>Deployments—>WebApplications—>BEA_POWERENTERPRISE_3_0_EventRouter

2. Change the deployment settings for each event router by selecting the appropriate Targets tab and following the instructions in the Administration Console. Specify that each event router will be deployed to only one managed server in your cluster.

   For more information about using the Administration Console to configure the deployment of Web applications, see the WebLogic Server Adminstration Console Online Help, which is available at the following URL:

   http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ConsoleHelp/index.html

Using the config.xml File

The following listing is an excerpt from a sample config.xml file for a domain containing an administration server with clustered managed servers. It shows the event router WAR files for two adapters, configured such that they are deployed on a single managed server in the cluster. The WebAppComponent elements are shown in bold.

Listing 3-3 Configuring BEA_WLS_DBMS_ADK and BEA_POWERENTERPRISE_3_0 Adapters

<Application Deployed="true" Name="BEA_WLS_DBMS_ADK"
Path="<WLI_HOME>/adapters/dbms/lib/BEA_WLS_DBMS_ADK.ear" TwoPhase="true">

      <ConnectorComponent Name="BEA_WLS_DBMS_ADK"
                Targets="MyCluster" URI="BEA_WLS_DBMS_ADK.rar"/>

      <WebAppComponent Name="DbmsEventRouter" Targets="MyServer-1"
                URI="BEA_WLS_DBMS_ADK_EventRouter.war"/>

      <WebAppComponent Name="BEA_WLS_DBMS_ADK_Web"
                Targets="MyCluster" URI="BEA_WLS_DBMS_ADK_Web.war"/>

</Application>

 :

<Application Deployed="true" Name="BEA_POWERENTERPRISE_3_0"
Path="<WLI_HOME>/adapters/powerenterprise/lib/
BEA_POWERENTERPRISE_3_0_EAR.ear" TwoPhase="true">

      <ConnectorComponent Description="J2EE CA adapter for
                PowerEnterprise!" Name="BEA_POWERENTERPRISE_3_0"
                Targets="MyCluster" URI="BEA_POWERENTERPRISE_3_0.rar"/>

                <WebAppComponent Name="BEA_POWERENTERPRISE_3_0_EventRouter"
                Targets="MyServer-1"
                URI="BEA_POWERENTERPRISE_3_0_EventRouter.war"/>

                <WebAppComponent Name="BEA_POWERENTERPRISE_3_0_Web"
                Targets="MyCluster" URI="BEA_POWERENTERPRISE_3_0_Web.war"/>

</Application>

 

---

Step 6. Configure an RDBMS Realm

If your domain uses an RDBMS Realm from a previous release of WebLogic Integration, you must include an RDBMSRealm element in the config.xml file for your domain. The element is configured, but it is disabled in the config.xml file generated when you create your domain using the procedures in Step 2. Create a WebLogic Integration Domain. To enable the RDBMSRealm element:

1. Open the config.xml file in the root directory of your WebLogic Integration domain.

2. Search for the RDBMSRealm element and uncomment the RDBMS Realm element.

3. The RDBMSRealm element provided for you in the config.xml file is configured for the Pointbase database, as shown in the following listing. If you are using another database, reconfigure the DatabaseDriver, DatabasePassword, DatabaseURL, and DatabaseUserNameattributes in the RDBMSRealm element.

Listing 3-4 RDBMSRealm Element

<RDBMSRealm Name="wlpiRDBMSRealm"
            DatabaseDriver="com.pointbase.jdbc.jdbcUniversalDriver"
                      DatabasePassword="none"
                      DatabaseURL="jdbc:pointbase://localhost:9094/WLIDB"
                      DatabaseUserName="none" 

                      :
                      :

For more information about migrating security realm data, see "Step 8. Migrate Your Security Realm Data" in Migrating WebLogic Integration 2.1 to WebLogic Integration 7.0 in the BEA WebLogic Integration Migration Guide.

 

---

Step 7. Configure a Router

If you want to configure a software router based on the built-in WebLogic HttpClusterServlet, you can do so by uncommenting a predefined section in the config.xml file in your domain.

The config.xml file in your domain contains comments to help you quickly identify and edit the elements that must be changed. Complete the following steps to make the required changes to the domain's configuration file:

1. Open the config.xml file in the root directory of your WebLogic Integration domain.

2. Search for comments labeled with the words ROUTER-OPTION, and follow the instructions included in those comments to configure a router for your domain.

   You must provide appropriate values for the router server name, listen address, listen port, and so on.

3. Configuration for a Web server is included in the router configuration, as shown in the following code from the config.xml file:

   <WebServer Name="ROUTER_NAME"
   DefaultWebApp="DefaultWebApp_ROUTER_NAME"
   . . . />

   Note that the Web server element references the default Web application through the DefaultWebApp attribute. (ROUTER_NAME represents the name you assign to the router.)

   1. Make sure that a directory matching the specified DefaultWebApp value (in this case, DefaultWebApp_ROUTER_NAME) resides in the following location:

      DOMAIN_HOME/applications/

      In the preceding path, DOMAIN_HOME represents the root directory for your domain.

   2. Create a web.xml deployment descriptor in the DefaultWebApp directory specified in the preceding step. The web.xml deployment descriptor should include the registration of the HttpClusterServlet.

      For information about creating a web.xml deployment descriptor, see "Configure Proxy Plug-Ins" in Setting up WebLogic Clusters in Using WebLogic Server Clusters, which is available at the following URL:

       http://download.oracle.com/docs/cd/E13222_01/wls/docs70/cluster/index.html

Note: When you configure a hardware or software router for your cluster, messages coming from outside the cluster should be sent to the URL of the router.

For information about hardware and software routers, see Using WebLogic Server Clusters, which is available at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/cluster/index.html

 

---

Step 8. Edit the startWeblogic Command File

You must edit the startWeblogic.cmd or startWeblogic.sh file in your domain to set the -Dweblogic.management.discover parameter to true:

1. Open the startWeblogic command file in the root directory of your WebLogic Integration domain.

2. Locate the -Dweblogic.management.discover argument to the start WebLogic command.

3. Change the value specified from false to true.

   The following code listing shows an example of a start server command and includes the modification to the -Dweblogic.management.discover argument. This code listing represents a single command. It is shown here as multiple lines for the sake of readability. In your command file, however, it is entered as one physical line.

Listing 3-5 Start Server Command for a WebLogic Integration Clustered Domain

REM Start weblogic

%JAVA_HOME%\bin\java %JAVA_VM% %JAVA_OPTIONS% -Xmx256m 
-classpath %SVRCP% 
-Dweblogic.servlet.ClasspathServlet.disableStrictCheck=true
-Dwli.bpm.server.evaluator.supportsNull=false
-Dweblogic.management.username= -Dweblogic.management.password=
-Dweblogic.Name=adminserver
-Dweblogic.RootDirectory=%WLI_DOMAIN_HOME%
-Djava.security.policy=%WL_HOME%\lib\weblogic.policy
-Dweblogic.management.discover=true 
-Dweblogic.ProductionModeEnabled=%STARTMODE%  weblogic.Server

For a scenario in which the administration server is restarted while managed servers are running in your domain, the administration server can discover running managed servers when -Dweblogic.management.discover is set to true.

 

---

Step 9. Set Up Managed Servers for Your Domain

This step provides instructions for extending the domain you created by adding managed servers. To add a managed server to a domain, you must create the managed server and configure WebLogic Integration components on the server.

A WebLogic Integration domain can be set up in one of the following ways:

• The administration server and the clustered managed servers can be set up on the same machine.

• The administration server and the clustered managed servers can be set up on different machines.

• Any combination of the preceding two configurations. For example, a cluster might comprise one machine that hosts an administration server and a number of managed servers, and one or more other machines that host additional managed servers.

This section provides instructions for setting up managed servers in your cluster:

• Add a Managed Server to an Existing Installation

• Add a Managed Server in a New Location

Both procedures explain how to add a managed server to a domain created with one of the templates provided with the Configuration Wizard.

Add a Managed Server to an Existing Installation

Complete the following steps to add a managed server to a WebLogic Integration domain:

• Step 1. Create a New Managed Server

• Step 2. Update the Domain Configuration for the New Managed Server (Optional)

Note: The procedures in this section are based on the assumption that your domain is named mydomain, and that it resides in the default location: BEA_HOME\user_projects.

Step 1. Create a New Managed Server

1. Start the administration server and the WebLogic Server Administration Console:

   1. To start the administration server, see "Starting WebLogic Integration" in Getting Started in Starting, Stopping, and Customizing BEA WebLogic Integration.

   2. To start the console, see "Starting the WebLogic Server Administration Console" in WebLogic Integration Administration and Design Tools in Starting, Stopping, and Customizing BEA WebLogic Integration.

2. In the Administration Console navigation tree, select Servers.

3. Click Configure a New Server.

4. Enter values in the Name, Listen Address (server instance IP address) fields and, if applicable, in the external DNS name field.

   The value you specify for the external DNS name can be a host name, or a virtual host name for a multihomed machine. (A multihomed machine is one for which multiple IP addresses are assigned.)

5. Select the machine name from the Machine drop-down list.

6. Click Create.

7. Select the Cluster tab.

8. Select the appropriate cluster from the Cluster drop-down list.

Note: For more information about creating and configuring servers, clusters, machines, and domains using the WebLogic Server Administration Console, see the WebLogic Server Adminstration Console Online Help, which is available at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ConsoleHelp/index.html

Step 2. Update the Domain Configuration for the New Managed Server (Optional)

You must add a managed server to the configuration for a domain before you can start that server. You may add a managed server to the domain configuration when you are creating the domain, or you may add it after a domain has been created. Therefore, this step is optional. Use the following guidelines to determine whether you need to complete it:

• You must update your domain configuration if the managed server you created in the previous step (Step 1. Create a New Managed Server) was not added to your configuration when you initially created your domain. (In other words, updating is required if you did not define the managed server in the Configuration Wizard when you performed Step 2. Create a WebLogic Integration Domain.)

• You do not need to update your domain configuration if the managed server you created in Step 1. Create a New Managed Server is already configured for your domain. (In other words, updating is not required if you defined the managed server in the Configuration Wizard when you created your domain, as described in Step 2. Create a WebLogic Integration Domain.)

To update your domain configuration for a new managed server, complete the following procedure:

1. Configure a JMS JDBC Store, and associate it with a connection pool:

   1. In the Administration Console navigation tree, choose Domain_Name—>Services—>JMS—>Stores

   2. Click Configure a New JMSJDBCStore to display the Configuration tab.

   3. Enter the following information in the appropriate fields:

      Name: JMSWLIStore_newmanageserver

      Connection Pool: wliPool

      Prefix Name: newmanageserver

   4. Click Create to create a new JMSJDBCStore for the new managed server.

2. Configure a JMS Server and associate it with the JMS JDBC Store:

   1. In the Administration Console navigation tree, choose Domain_Name—>Services—>JMS—>Servers

   2. Click Configure a New JMS Server to display the Configuration tab.

   3. Enter the following information in the appropriate fields:

      Name: WLIJMSServer_newmanageserver

      Store: JMSWLIStore_newmanageserver

      Temporary Template: TemporaryTemplate

      WLIJMSServer_newmanageserver represents the name of the new JMS server. JMSWLIStore_newmanageserver is the name you gave the JMSJDBC Store when you created it.

      You can give the JMS server any name you choose. However, we recommend using the naming convention in this example: WLIJMSServer_node. In this format, node represents the name of the server (WebLogic Server instance) on which the JMS server is deployed.

   4. Accept the defaults for the remainder of the fields, and click Create to create a new JMS server for your new managed server.

3. Configure destinations for the newly defined JMS server:

   1. Access your new JMS server configuration in the Administration Console navigation tree:

      Domain_Name—>Services—>JMS—>Servers—>Server_Name—>Destinations

   2. Click Configure Destinations.

   3. Click Configure a new JMS Topic or Configure a new JMS Queue.

      Configure the WLI_FailedEvent-node destination first. By doing so, a WLI_JMSTemplate-node can be configured for redelivery. (For information about how to configure redelivery attributes for physical destinations, see Error Destination.) The WLI_JMSTemplate-node is used by several of the other queue destinations.

      For information about using the Administration Console to complete this task, see "JMS Destination Tasks" in JMS in the WebLogic Server Adminstration Console Online Help, which is available at the following URL:

      http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ConsoleHelp/index.html

   Note: You should refer to an existing node in the cluster to see the destinations that need to be configured, and which destinations use the WLI_JMSTemplate-node. The destinations required vary depending on the domain template you used when you created your domain.
   
   For a list of all JMS queues and topics configured for a JMS server in a domain based on the WLI Domain template, see JMS Servers and JMS Destinations.

4. Configure WebLogic Integration distributed destinations.

   Multiple physical JMS destinations are configured for every distributed destination. One physical destination is configured for each managed server in your cluster.

   To configure JMS destinations for a newly created managed server, complete the following steps:

   1. Access the distributed destinations for your WebLogic Integration domain by selecting the following nodes in the Administration Console navigation tree:

      Domain_Name—>Services—>JMS—>Distributed Destinations

      Note: Distributed destinations for your WebLogic Integration deployment are listed in JMS Servers and JMS Destinations.

   2. Create a JMS distributed queue member for each distributed destination.

      For information about creating a distributed queue member, see "JMS Distributed Destination Tasks" in JMS the WebLogic Server Adminstration Console Online Help, which is available at the following URL:

      http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ConsoleHelp/index.html

Note: For an example of WebLogic Integration distributed destination configuration, see JMS Servers and JMS Destinations. You can also view the JMSDistributedQueue and JMSDistributedTopic elements in the config.xml file that was created when you created a domain.

Add a Managed Server in a New Location

To add a managed server to a domain in which the administration server and the clustered managed servers reside on different machines, complete the following steps:

• Step 1. Copy the Contents of Your Preconfigured Domain to the New Location

• Step 2. Modify the Contents of the Directory You Copied

• Step 3. Create a Managed Server

• Step 4. Update the Domain Configuration for the New Managed Server (Optional)

Step 1. Copy the Contents of Your Preconfigured Domain to the New Location

To set up a managed server in a new location, copy the contents of the domain directory you created to the new location, and modify them.

Complete the following procedure:

1. Install WebLogic Integration in the new location.

2. Copy the contents of the domain directory you created (see Step 2. Create a WebLogic Integration Domain) to the remote machine. The directory you copy serves as the start location for the managed server.

Note: If you set up a mixed cluster environment (that is, a cluster in which some instances of WebLogic Integration run on Windows systems and others run on UNIX systems), you may encounter a particular problem with carriage return characters. The carriage return character used in scripts run on Windows systems is ^M. Sometimes these characters remain in a file that is copied from a Windows system to a UNIX system. If the Windows carriage returns persist on a UNIX system, simply open the file and delete the ^M characters before running your script. You can do this using any text editor, or you can use the dos2unix command on Solaris systems. The dos2unix utility converts characters in the DOS extended character set to the corresponding ISO standard characters.

If you use FTP to transfer your ASCII files from a Windows system to a UNIX system, you can avoid this problem with carriage return characters by choosing the default ASCII mode.

Step 2. Modify the Contents of the Directory You Copied

Note: The following instructions are based on the assumption that you copied a domain directory named mydomain to the following location: BEA_HOME/user_projects.

To modify the contents of the directory you copied to the new location, delete all files and directories from BEA_HOME/user_projects, except those listed in the following table.

Files	startWeblogic.cmd or startWebLogic.sh
	startManagedWeblogic.cmd or startManagedWebLogic.sh
	caKeyStore.pks
	privateKeyStore.pks
Directories	applications
	cacerts
	certs
	keys
	wlai1

1. The wlai directory is available in the domain directory if you are adding a managed server to a domain in which adapters, application views, and the application integration plug-in are deployed.

 

Step 3. Create a Managed Server

1. Start the administration server and the Administration Console:

   1. To start the administration server, see "Starting WebLogic Integration" in Getting Started in Starting, Stopping, and Customizing BEA WebLogic Integration.

   2. To start the console, see "Starting the WebLogic Server Administration Console" in WebLogic Integration Administration and Design Tools in Starting, Stopping, and Customizing BEA WebLogic Integration.

2. In the Administration Console navigation tree, select Servers.

3. Click Configure a New Server.

4. Enter values in the Name, Listen Address (server instance IP address) fields and, if applicable, in the external DNS name field.

   The value you specify for the external DNS name can be a host name or a virtual host name for a multihomed machine.

5. Select the machine name from the Machine drop-down list.

6. Click Create.

7. Select the Cluster tab.

8. Select the appropriate cluster from the Cluster drop-down list.

Note: For more information about creating and configuring servers, clusters, machines, and domains using the WebLogic Server Administration Console, see the WebLogic Server Adminstration Console Online Help, which is available at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ConsoleHelp/index.html

Step 4. Update the Domain Configuration for the New Managed Server (Optional)

You must add a managed server to the configuration for a domain before you can start that server. You may add a managed server to the domain configuration when you are creating the domain, or you may add it after a domain has been created. Therefore this step is optional.

To determine whether you need to complete it and, if so, how to do so, use the same guidelines and procedures described in Step 2. Update the Domain Configuration for the New Managed Server (Optional).

 

---

Step 10. Configure WebLogic Integration for Automatic Restart

Whether WebLogic Integration is deployed in a clustered environment or a nonclustered environment, you can configure your system to automatically restart servers that have shut down because of a system crash, hardware reboot, server failure, and so on. You can do this by configuring the Node Manager in one of two ways:

• Edit the configuration file created when you used the Configuration Wizard to create your domain.

  The config.xml file in your domain contains comments to help you quickly identify and edit the elements that must be changed. To configure the Node Manager and modify the configuration file for your domain, complete the following procedure:

  1. In the root directory of the domain you created, open the config.xml file in a text editor.

  2. Search for comments labeled with the string NM-OPTION, and follow the instructions included in those comments to configure the Node Manager and SSL.

  3. To configure self-health monitoring (that is, to specify the frequency with which the Node Manager checks a managed server's health), see Step 4. Configure Self-Health Monitoring.

  4. To start the Node Manager, see Step 5. Start the Node Manager.

• Configure the required components through the WebLogic Server Administration Console, following the procedure described in Configuring WebLogic Integration for Automatic Restart.

 

---

Step 11. Configure WebLogic Integration for Migration from Failed to Healthy Node

To configure your WebLogic Integration deployment such that it can support migration of resources from a failed node to a healthy node, follow the procedure outlined in Configuring WebLogic Integration for Migration from Failed to Healthy Node.

 

---

Step 12. Configure WebLogic Integration Security

If you want to configure SSL for your cluster, you can do so by uncommenting predefined sections (one section in each Server element) in the config.xml file in your domain.

The config.xml file contains comments to help you quickly identify and edit the elements that must be changed. To configure SSL and modify the configuration file for your domain, complete the following procedure:

1. Open the config.xml file in the root directory of your WebLogic Integration domain.

2. Search for comments labeled with the string SSL-OPTION, and uncomment the appropriate sections to configure SSL for your domain.

For a domain in which B2B integration functionality is deployed in a multinode cluster, you also need to configure keystores, server certificates, startWeblogic scripts, and so on, for every machine in a cluster.

For information about the tasks you must complete, see:

• "Using the Keystore in a Multinode Cluster" in Configuring the Keystore in Implementing Security with B2B Integration

• Using WebLogic Integration Security.

Warning: If your domain is based on the WLI Domain or EAI Domain template, and if you want to configure keystores for your domain, you must set the Deployed attribute in the WebLogic Integration Application element to false before you can configure keystores.

The following listing is an excerpt from a config.xml file for a WebLogic Integration domain, which shows the Deployed attribute set to false.

Listing 3-6 Setting the Deployed Attribute Before Configuring Keystores

<Application Name="WebLogic Integration" Deployed="false"
Path="C:/bea/weblogic700/integration/lib" TwoPhase="true">

 

---

Step 13. Start the Servers in the Domain

This section describes how to start the servers in your clustered domain:

• Before You Start the Servers

• Starting Servers in a Domain for Which the Node Manager Is Not Configured

• Starting Servers in a Domain for Which the Node Manager Is Configured

• Monitoring and Shutting Down Your Servers

Before You Start the Servers

Complete the following procedure before you start the servers in your domain:

1. Make sure that the Deployed attribute is set to true for the WebLogic Integration Application element in the domain configuration file.

   If you configured keystores for your domain, you should have set this Deployed attribute to false, as described in Step 12. Configure WebLogic Integration Security.

   The following listing is an excerpt from a config.xml file for a WebLogic Integration domain, which shows the Deployed attribute set to true.

   <Application Name="WebLogic Integration" Deployed="true"
   Path="C:/bea/weblogic700/integration/lib" TwoPhase="true">

2. If you specified a server name other than the default when you created your domain (described in Step 2. Create a WebLogic Integration Domain), make sure that you now change the name of the following directory in your domain:

   DOMAIN_HOME/applications/DefaultWebApp_myserver

   In the preceding path, DOMAIN_HOME represents the root directory for your domain. Replace the myserver string with the name you specified for your administration server.

Starting Servers in a Domain for Which the Node Manager Is Not Configured

To start servers in a domain for which the Node Manager is not configured, complete the following procedure:

1. Start the administration server by executing the startWebLogic command:

   cd DOMAIN_HOME
   startWeblogic

   In the preceding line, DOMAIN_HOME represents the root directory for your domain.

2. After the administration server is started, start the managed servers in your domain by executing the startManagedWebLogic command for each managed server, in turn. In other words, go to the root directory in which you installed each managed server instance, and run the startManagedWeblogic command:

   cd DOMAIN_HOME
   startManagedWeblogic managedserver

   In the preceding line, managedserver represents the name of a managed server in your domain.

   As each managed server starts, status messages are displayed in the command window.

Starting Servers in a Domain for Which the Node Manager Is Configured

To start servers in a domain for which the Node Manager is configured, complete the following procedure:

1. Start the administration server by executing the startWebLogic command:

   cd DOMAIN_HOME
   startWeblogic

   In the preceding line, DOMAIN_HOME represents the root directory for your domain.

2. Start the managed servers in your domain:

   1. If you have not done so already, start the Node Manager on each machine that hosts managed servers. (See Step 5. Start the Node Manager.)

   2. In the Administration Console navigation tree, select the name of each managed server, in turn.

   3. In the main console window, select the Control tab.

   4. Click Start this Server.

   For information about how the Start Server command is affected by other settings made via the WebLogic Server Administration Console, see the WebLogic Server Adminstration Console Online Help, which is available from the software and at the following URL:

   http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ConsoleHelp/index.html

Monitoring and Shutting Down Your Servers

When startup is complete, you can use the WebLogic Server Administration Console to verify deployments and status.

Then use the WebLogic Server Administration Console to shut down your WebLogic Integration application. It is recommended that you do not close the command window or press Ctrl+c to stop WebLogic Integration. To shut down your application gracefully, run the stopWebLogic command, as described in "Stopping WebLogic Integration" in Getting Started in Starting, Stopping, and Customizing BEA WebLogic Integration.