This chapter describes using high-availability features for remote EJB references and JNDI objects over RMI-IIOP.
With RMI-IIOP load balancing, IIOP client requests are distributed to different server instances or name servers. The goal is to spread the load evenly across the cluster, thus providing scalability. IIOP load balancing combined with EJB clustering and availability also provides EJB failover.
When a client performs a JNDI lookup for an object, the Naming Service creates a InitialContext (IC) object associated with a particular server instance. From then on, all lookup requests made using that IC object are sent to the same server instance. All EJBHome objects looked up with that InitialContext are hosted on the same target server. Any bean references obtained henceforth are also created on the same target host. This effectively provides load balancing, since all clients randomize the list of live target servers when creating InitialContext objects. If the target server instance goes down, the lookup or EJB method invocation will failover to another server instance.
IIOP load balancing and failover happens transparently. No special steps are needed during application deployment. IIOP load balancing and failover for the Enterprise Server supports dynamically reconfigured clusters. If the Enterprise Server instance on which the application client is deployed participates in a cluster, the Enterprise Server finds all currently active IIOP endpoints in the cluster automatically. Therefore, you are not required to manually update the list of endpoints if a new instance is added to the cluster or deleted from the cluster. However, a client should have at least two endpoints specified for bootstrapping purposes, in case one of the endpoints has failed.
Your deployment has a cluster of at least two instances.
Java EE applications are deployed to all instances and clusters that participate in load balancing.
RMI-IIOP client applications are enabled for load balancing.
Enterprise Server supports load balancing for Java applications executing in the Application Client Container (ACC). See Setting up RMI-IIOP Load Balancing and Failover.
Enterprise Server does not support RMI-IIOP load balancing and failover over secure sockets layer (SSL).
When an RMI-IIOP client first creates a new InitialContext object, the list of available Enterprise Server IIOP endpoints is randomized for that client. For that InitialContext object, the load balancer directs lookup requests and other InitialContext operations to the first endpoint on the randomized list. If the first endpoint is not available then the second endpoint in the list is used, and so on.
Each time the client subsequently creates a new InitialContext object, the endpoint list is rotated so that a different IIOP endpoint is used for InitialContext operations.
When you obtain or create beans from references obtained by an InitialContext object, those beans are created on the Enterprise Server instance serving the IIOP endpoint assigned to the InitialContext object. The references to those beans contain the IIOP endpoint addresses of all Enterprise Server instances in the cluster.
The primary endpoint is the bean endpoint corresponding to the InitialContext endpoint used to look up or create the bean. The other IIOP endpoints in the cluster are designated as alternate endpoints. If the bean's primary endpoint becomes unavailable, further requests on that bean fail over to one of the alternate endpoints.
You can configure RMI-IIOP load balancing and failover to work with applications running in the ACC.
You can set up RMI-IIOP load balancing and failover for applications running in the application client container (ACC). Weighted round-robin load balancing is also supported.
This procedure gives an overview of the steps necessary to use 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 Sun GlassFish Enterprise Server 2.1 Developer’s Guide.
Go to the install_dir /bin directory.
This utility produces an appclient.jar file. For more information on package-appclient, see package-appclient(1M).
Copy the appclient.jar file to the machine where you want your client and extract it.
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).
If required, make the appclient script executable.
For example, on UNIX use chmod 700.
Find the IIOP listener port number of at least two instances in the cluster.
You specify the IIOP listeners as endpoints in Step 7.
For each instance, obtain the IIOP listener port as follows:
Add at least two target-server elements in the sun-acc.xml file.
Clustering features are not available in the developer profile. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server 2.1 Administration Guide.
Use the endpoints that you obtained in Step 6.
If the Enterprise 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 Sun GlassFish Enterprise Server 2.1 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,..."
If you require weighted round-robin load balancing, perform the following steps:
Set the load-balancing weight of each server instance.
asadmin set instance-name.lb-weight=weight
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"/> …
Deploy your client application with the --retrieve option to get the client jar file.
Keep the client jar file on the client machine.
asadmin deploy --user admin --passwordfile pw.txt --retrieve /my_dir myapp
Run the application client as follows:
appclient -client clientjar -name appname
In this example, the load-balancing weights in a cluster of three instances are to be set as shown in the following table.
The sequence of commands to set these load balancing weights is as follows:
asadmin set i1.lb-weight=100 asadmin set i2.lb-weight=200 asadmin set i3.lb-weight=300
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.