12 RMI-IIOP Load Balancing and Failover

To Enable RMI-IIOP Hardware Load Balancing for the Application Client Container

This procedure provides an overview of the steps necessary to enable RMI-IIOP load balancing and failover with the application client container (ACC). For additional information on the ACC, see "Developing Clients Using the ACC" in Oracle GlassFish Server Application Development Guide.

Before You Begin

The first five steps in this procedure are only necessary if you are enabling RMI-IIOP load balancing on a system other than the DAS. This is common in production environment, but less common in a development environment. For example, a developer who wants to experiment with a cluster and load balancing might create two instances on the same system on which the DAS is running. In such cases, these steps are unnecessary.

1. Go to the install_dir /bin directory.

2. Run package-appclient.

   This utility produces an appclient.jar file. For more information on package-appclient, see package-appclient(1M).

3. Copy the appclient.jar file to the machine where you want your client and extract it.

4. Edit the asenv.conf or asenv.bat path variables to refer to the correct directory values on that machine.

   The file is at appclient-install-dir /config/.

   For a list of the path variables to update, see package-appclient(1M).

5. If required, make the appclient script executable.

   For example, on UNIX use chmod 700.

6. Find the IIOP listener port number for at least two instances in the cluster.

   You specify the IIOP listeners as endpoints in Add at least two target-server elements in the sun-acc.xml file..

   For each instance, obtain the IIOP listener ports as follows:

   1. Verify that the instances for which you want to determine the IIOP listener port numbers are running.

      asadmin> list-instances
      

      A list of instances and their status (running, not running) is displayed.

      The instances for which you want to display the IIOP listener ports must be running.

   2. For each instance, enter the following command to list the various port numbers used by the instance.

      asadmin> get servers.server.instance-name.system-property.*.value
      

      For example, for an instance name in1, you would enter the following command:

      asadmin> get servers.server.in1.system-property.*.value
      

7. Add at least two target-server elements in the sun-acc.xml file.

   Use the endpoints that you obtained in Find the IIOP listener port number for at least two instances in the cluster..

   If the GlassFish Server instance on which the application client is deployed participates in a cluster, the ACC finds all currently active IIOP endpoints in the cluster automatically. However, a client should have at least two endpoints specified for bootstrapping purposes, in case one of the endpoints has failed.

   The target-server element specifies one or more IIOP endpoints used for load balancing. The address attribute is an IPv4 address or host name, and the port attribute specifies the port number. See "client-container" in Oracle GlassFish Server Application Deployment Guide.

   As an alternative to using target-server elements, you can use the endpoints property as follows:

   jvmarg value = "-Dcom.sun.appserv.iiop.endpoints=host1:port1,host2:port2,..."
   

8. If you require weighted round-robin load balancing, perform the following steps:

   1. Set the load-balancing weight of each server instance.

      asadmin set instance-name.lb-weight=weight
      

   2. In the sun-acc.xml, set the com.sun.appserv.iiop.loadbalancingpolicy property of the ACC to ic-based-weighted.

      …
      <client-container send-password="true">
        <property name="com.sun.appserv.iiop.loadbalancingpolicy" \
           value="ic-based-weighed"/>
      …
      

9. Deploy your client application with the --retrieve option to get the client jar file.

   Keep the client jar file on the client machine.

   For example:

   asadmin  --user admin --passwordfile pw.txt deploy --target cluster1 \
   --retrieve my_dir myapp.ear
   

10. Run the application client as follows:

    appclient --client my_dir/myapp.jar
    

asadmin set i1.lb-weight=100
asadmin set i2.lb-weight=200
asadmin set i3.lb-weight=300

Next Steps

To test failover, stop one instance in the cluster and see that the application functions normally. You can also have breakpoints (or sleeps) in your client application.

To test load balancing, use multiple clients and see how the load gets distributed among all endpoints.

See Also

See Enabling the High Availability Session Persistence Service for instructions on enabling the session availability service for a cluster or for a Web, EJB, or JMS container running in a cluster.

To Enable RMI-IIOP Per-Request Load Balancing for a Stateless EJB

This procedure describes how to enable PRLB for a stateless EJB that is deployed to clustered GlassFish Server instances. This procedure also provides an client-side example for accessing a stateless EJB that uses PRLB.

1. Choose or assemble the EJB that you want to deploy.

   In this example, an EJB named TheGreeter is used.

   For instructions on developing and assembling an EJB for deployment to GlassFish Server, refer to the following documentation:

   • "Using Enterprise JavaBeans Technology" in Oracle GlassFish Server Application Development Guide

   • "EJB Module Deployment Guidelines" in Oracle GlassFish Server Application Deployment Guide

   • "Assembling and Deploying an Application Client Module" in Oracle GlassFish Server Application Deployment Guide

2. Set the per-request-load-balancing property to true in the glassfish-ejb-jar.xml deployment descriptor file for the EJB.

   For more information about the glassfish-ejb-jar.xml deployment descriptor file, refer to "The glassfish-ejb-jar.xml File" in Oracle GlassFish Server Application Deployment Guide

   For example, the glassfish-ejb-jar.xml file for a sample EJB named TheGreeter is listed below.

   <glassfish-ejb-jar>
     <enterprise-beans>
       <unique-id>1</unique-id>
       <ejb>
         <ejb-name>TheGreeter</ejb-name>
       <jndi-name>greeter</jndi-name>
       <per-request-load-balancing>true</per-request-load-balancing>
       </ejb>
     </enterprise-beans>
   </glassfish-ejb-jar>
   

3. Deploy the EJB.

   If the EJB was previously deployed, it must be redployed.

   For instructions on deploying EJBs, refer to the following documentation:

   • "To Deploy an Application or Module" in Oracle GlassFish Server Application Deployment Guide

   • "To Redeploy an Application or Module" in Oracle GlassFish Server Application Deployment Guide

4. Verify the PRLB configuration by looking for the following FINE message in the CORBA log file:

   Setting per-request-load-balancing policyfor EJB EJB-name
   

5. Configure a client application to access the PRLB-enabled EJB.

   For example:

   public class EJBClient {
       public static void main(String args[]) {
       :
       :
       :
       try {
       // only one lookup
   
       Object objref = initContext.lookup("test.cluster.loadbalancing.ejb.\
         TestSessionBeanRemote");
           myGreeterRemote = (TestSessionBeanRemote)PortableRemoteObject.narrow\
             (objref,
                                               TestSessionBeanRemote.class);
   
       } catch (Exception e) {
       :
       }
   
       for (int i=0; i < 10; i++ ) {
       // method calls in a loop.
           String theMessage = myGreeterRemote.sayHello(Integer.toString(i));
           System.out.println("got"+": " + theMessage);
           }
       }
   }
   

See Also

See Enabling the High Availability Session Persistence Service for instructions on enabling the session availability service for a cluster or for a Web, EJB, or JMS container running in a cluster.