Chapter 9   Rich Client


This chapter explains a rich client's infrastructure role within an iPlanet Application Server environment. Also described are the programming considerations when implementing a rich client.

This chapter contains the following sections:

• Rich Client Overview

• Rich Client Architecture and Use Cases

• Value-added Features

• Developing for a Rich Client

• Sample Client Code

Rich Client Overview

---

A rich client is a standalone Java program that can directly access EJBs deployed on an iPlanet Application Server. Traditionally, clients communicated with the iPlanet Application Server through the web-path, for example, by speaking HTTP to server components such as JSPs and servlets which in turn, hands access to EJBs within the server context. The J2EE v1.2 specification, however, requires that standalone clients be able to talk to the iPlanet Application Server using the RMI-IIOP standard. Chapter 9 of the J2EE v1.2 specification also requires that these standalone clients operate within the Application Client Container (ACC) context that isolates server specific issues, leaving clients completely portable. Through its rich client infrastructure, the iPlanet Application Server allows Java clients to directly access EJBs on an iPlanet Application Server. These clients could operate within an ACC that ships with the iPlanet Application Server as required by the J2EE ACC specification or more straightforward direct access (non ACC path).

The diagram below is aa iPlanet Application Server architecture schematic and illustrates the differences between the rich client and web paths. While browser clients communicate with the iPlanet Application Server using HTTP through a web server, Rich clients circumvent the web server to directly access EJBs as RMI-IIOP clients.

A rich client is a first-tier program, executing in its own Java Virtual Machine (JVM), possibly in an ACC. Deploying a rich client (through the ACC) requires deployment descriptors using XML. For more information on application clients and their deployment descriptors, see the J2EE Specification, v1.2.

Rich Client Architecture and Use Cases

---

The iPlanet Application Server supports rich clients using a Java engine called the CORBA Executive Server (CXS). The CXS acts as a bridge between rich clients that use the Internet Inter-ORB Protocol (IIOP) and EJBs on the iPlanet Application Server Java engine(s). For every EJB on an iPlanet Application Server, the CXS instantiates two objects, one for the EJB home and remote interfaces, that act as bridges between IIOP and the iPlanet Application Server internal communication protocol.

The following diagram illustrates the various rich client architecture components.

Use Cases

Rich client connectivity to the iPlanet Application Server is primarily expected to be used in one of the following three scenarios:

• From a standalone Java (and possibly C++) client that directly communicates with the iPlanet Application Server. This is the scenario we have talked about up until now.

• A business-to-business scenario where applications in other application servers can work with EJBs hosted on an iPlanet Application Server. These components would use RMI-IIOP (or possibly IIOP from C++) and obtain references to the iPlanet Application Server EJBs.

• From a web server hosted component, such as servlets and JSPs, Microsoft ASP, and so on. Beans on an iPlanet Application Server can be accessed from any web server (like Apache, IIS, iPlanet Web Server, and so on).

Value-added Features

---

The following sections provide information on value-added features:

Load Balancing

The CXS currently uses a simple round robin scheme for load balancing. It obtains a static engine list at system startup and uses this static list to pick the target engine for an EJB home to be hosted on. Subsequent lookups for that EJB home, bean creations on that home and business method invocations on the created beans go to the same target engine. In the current release its possible to configure multiple CXS but the client needs to manually load balance across them. A future iPlanet Application Server release will support a client initiated load balancing scheme.

Failover

When connecting to the iPlanet Application Server through the rich client path, there are two failover levels available to the client. The first failover level supports provides for stateful session beans hosted on the iPlanet Application Server Java engines. In case a Java engine crashes and the administrative server restarts the engine, the session bean's state is restored. The second failover level support happens in the CXS for both session and entity bean handles and object references. In case of a CXS crash, the bridge object states for all EJBs are restored. The handle and object reference failover allows the client to obtain persistent references that survive client or CXS crashes. For failover to be available for an EJB, an XML deployment descriptor entry is required at deployment time. For more information on deployment descriptor settings, see Chapter 10 "Deployment Packaging."

Security

Rich client path security is integrated with the iPlanet Application Server security infrastructure. CXS uses the iPlanet Application Server security manager to authenticate clients with user information stored in LDAP. Client credentials are passed from the client, through the bridge to EJBs. A client side callback initiates client login (with username and password). The object type to be instantiated to obtain this information is specified through an environment setting on the client. In case of authentication failure, the client side is setup to retry the login process. The retry number is currently hardcoded to three (3).

Developing for a Rich Client

---

The following sections provide information on developing a rich client.

Server Side

The server side work involved in working with the rich client infrastructure is almost exactly the same as that for the web-path. EJBs the rich client needs to access are developed and deployed in exactly the same way (for more information, see "EJB XML DTD"). There are two key additional steps required when using the rich client path.

1. CXS needs to be started up and configured using the iPlanet Application Server Administrator Tool (iASAT). CXS is not setup during the iPlanet Application Server installation. Instead, it is configured using iASDT when required. The CXS is configured to listen on an IIOP port and an internal engine port. The IIOP port is used by the client to talk to CXS.

2. The iASDT is used to obtain a single JAR file corresponding to the application that needs the rich client connectivity. This JAR file contains RMI/IIOP stubs generated from the EJB home and remote interfaces. iASDT ensures all server side ties and stubs for the application are made available to CXS.

Client Side

The client side of the rich client system requires the following, as a minimum. All classes in the following sections must be in the client side CLASSPATH.

1. The following iPlanet Application Server specific components that come bundled in one TAR file called iasclient.tar (ZIP file iasclient.zip on NT) on the iPlanet Application Server CD:
   1. A J2SDK SE 1.2 with the Javasoft ORB packaged as an extension. In order to be able to use the rich client infrastructure, a client does not have to necessarily use this JDK. The reason is the JDK has the Javasoft ORB packaged inside it as an extension unlike the pristine JDK.

   2. The iPlanet Application Server specific client side classes packaged into iasclient.jar.

   3. J2EE APIs packaged into javax.jar, jms.jar, mail.jar and servlet.jar.

2. The client side JAR file generated on the server using the iASDT.

3. A security principal class that implements the com.netscape.ejb.client.IUserPrincipal interface. This class is instantiated once by the rich client system and the setPrincipal() method is invoked on this instance whenever a client logs in. For more inforation, see "java com.netscape.ejb.client.AppContainer <client ear file> -iasXml <ias xml file> [-resourceXml <resource xml file>]".

4. The RMI/IIOP client needs to be developed and inserted in the client's CLASSPATH.

The client is invoked through its main() method like any other standalone Java program. For an example, see "Sample Client Code".

Application Client Container

When using the Application Client Container, a client has a few additional things to take care of, as follows:

1. The iasacc.jar JAR file, contained in iasclient.tar/iasclient.zip (mentioned in Step 1 above) needs to be in the client's CLASSPATH.

2. A J2EE v1.2-compliant EAR file needs to be created. This EAR file should contain:
   1. The RMI/IIOP client mentioned in Step 4 above.

   2. A J2EE v1.2 XML descriptor file (application-client.xml). For more information, see the J2EE 1.2 specifications and see Chapter 11 "Creating and Managing User Sessions."

3. An iPlanet Application Server specific XML descriptor file (typically ias-application-client.xml). For an example, see Appendix C "Sample Deployment Files."

4. An optional resource XML descriptor file (typically resource-application-client.xml) is required only if the client needs to access resources such as JDBC drivers. For an example, see Appendix C "Sample Deployment Files."

To invoke the client through the Application Client Container, use the following command:

java com.netscape.ejb.client.AppContainer <client ear file> -iasXml <ias xml file> [-resourceXml <resource xml file>]

Sample Client Code

---

import java.rmi.*;
import javax.naming.*;
import javax.rmi.PortableRemoteObject;
import java.util.Properties;

public static void main(String [] argv) {
   Properties env = new Properties[];
   Context nctx;
   String beanName = "java:comp/env/bean";

The beanName string is used later to do a lookup. A name starting with java:comp may be used only if the application client container is used. If doing a lookup directly from a standalone client the absolute bean's JNDI name is used. The absolute name looks like: ejb/<module-name>/<bean-name>.

   BeanHome beanHome;
   BeanRemote beanRef;

// Environment entries when creating Initial Naming Context
   env.put("java.naming.factory.initial",
      "com.sun.jndi.cosnaming.CNCtxFactory");

Rich client's require clients to set few properties. The above property specifies the client program uses CORBA CosNaming SPI from Sun's JNDI implementation to communicate with the CosNaming server running inside CXS.

// Client security principal
   env.put("com.netscape.ejb.client.PrincipalClass",
      <my principal class name>);

If the client program wants to support secure invocations as mentioned earlier, the IUserPrincipal interface must be implemented and the class file name specified in the above property.

// Host and port number of CXS Naming Service
   env.put("java.naming.provider.url",
      "iiop://"+<host>+":"+<port>);

The CXS host and port the client connects to must be specified here. The iiop port number for CXS was (hopefully) configured when CXS was created using iASAT.

---

Note	Due to a bug in the interplay between the client classes and the ORB, it is necessary to set the target host and port in the client JVM system environment.

---

To get around this bug, invoke the client with:

-Dorg.omg.CORBA.ORBInitialHost=<host>
-Dorg.omg.CORBA.ORBInitialPort=<port>

Do this whether or not you set java.naming.provider.url in your application (as listed above).

try {
   nctx = new InitialContext(env);

The creation of initial context triggers the first invocation of the IUserPrincipal callback's setPrinicpal method if the PrincipalClass property is specified.

}
   catch (Exception e) {}
// Get EJB Home
   Object o1 = nctx.lookup(beanName);
   beanHome = (BeanHome)PortableRemoteObject.narrow(o1, BeanHome.class);

// Create EJB instance
   beanRef = (BeanRemote)beanHome.create();
   // Invoke business method on beanRef
   beanRef.doSomething();
   // Remove bean instance
beanRef.remove();
}

Sample Principal Class

---

The IUserPrinicpal interface can be implemented in several ways. The simplest is to popup a dialog in the setPrinciapl callback to capture a user/password pair and store them in the username and password private string fields. Then whenever an EJB invocation occurs from the client, the getUserId() and getPassword() methods are used to set the security context propagated by the client.

CXS tries to authenticate the user and password with the iPlanet Application Server security manager, if an authentication exception occurs in CXS the client side ORB is notified and re-triggers the setPrincipal callback to recapture the correct user/password information. The ORB re-trys the request automatically three (3) times after which the authentication exception is propagated to the client.

Another valid implementation of IUserPrinicpal supports multiple user identities in the same client JVM. This is done by using ThreadLocal variables to store username and password. The methods in the IUserPrinicpal implementation must to be ThreadLocal savvy.

import com.netscape.ejb.client.IUserPrincipal;
public class Principal implements IUserPrincipal {
   private String username;
   private String password;
   public void setPrincipal() {
      <Pop up GUI to take user name and password>
   }

public String getUserId() {
   return username;
   }

public String getPassword() {
   return password;
   }
}