Chapter 9   Rich Client


This chapter explains the role of the Rich Client infrastructure within the iAS environment. Also described are the programming considerations that need addressing when implementing a Rich Client.

The following topics are presented in this chapter:

• "Overview of Rich Client"

• "Rich Client Architecture and Use Cases"

• "Value-added Features"

• "Developing for a Rich Client"

• "Sample code"

Overview of Rich Client

---

What is a Rich Client

The Rich Client is a stand-alone Java program that can directly access EJBs deployed on iAS. Traditionally, clients communicated with iAS through the web-path, i.e. by speaking HTTP to server components such as JSPs and Servlets which in turn had access to EJBs within the context of the server. The J2EE v1.2 specification, however, requires that stand-alone clients be able to talk to iAS using the RMI-IIOP standard. Chapter 9 of the J2EE v1.2 specification also requires that these stand-alone clients operate within the context of an Application Client Container (ACC) that isolates server-specific issues, leaving the clients completely portable. Through its Rich Client infrastructure, iAS allows Java clients to directly access EJBs on iAS. These clients could operate within an ACC that ships with iAS as required by the J2EE ACC specification or more straight forward direct access (non ACC path) the way Java programmers are used to writing them.

The diagram below is a schematic representation of the iAS architecture and illustrates the difference between the Rich Client and web paths. While browser clients communicate with iAS using HTTP through a Web Server, Rich Clients circumvent the Web Server and directly access EJBs as RMI-IIOP clients.

The Rich Client is a first-tier program that executes in its own Java Virtual Machine (JVM), possibly in an ACC. Deploying the Rich Client (through the ACC) requires the specification of deployment descriptors using XML. Refer to the J2EE Specification, v1.2 for more information about application clients and their deployment descriptors.

Rich Client Architecture and Use Cases

---

Architecture

iAS 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 the EJBs on iAS' Java engine(s). For every EJB on iAS, the CXS instantiates two objects, one each for the EJB home and remote interfaces, that act as bridges between IIOP and iAS' internal communication protocol.

The following diagram illustrates the various components of the Rich Client architecture.

Use Cases

Rich Client connectivity to iAS is primarily expected to be used in any of the following three scenarios:

• From a stand-alone Java (and possibly C++) client that directly communicates with iAS. This is the scenario we have talked about up until now.

• A business-to-business scenario wherein applications in other applications servers can work with EJBs hosted on iAS. These components would use RMI-IIOP (or possibly) IIOP from C++) and obtain references to iAS EJBs.

• From a Web-Server hosted component such as Servlets and JSPs, Microsoft ASP etc., Beans on iAS can be accessed from any Web-Server (like Apache, IIS, NES etc.).

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 start-up 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 will go to the same target engine. In the current release it's possible to configure multiple CXS but the client will need to manually load balance across them. The next release of iAS will support a client-initiated load balancing scheme.

Failover

When connecting to iAS through the Rich Client path, there are two levels of failover that are available to the client. The first of these is the failover support that iAS provides for stateful session beans hosted on iAS' Java engines. In case a Java engine crashes and the Administrative Server restarts the engine, the state of session beans is restored to that before the crash. The second level of failover support happens in the CXS for both session and entity bean handles/object references. In case of a CXS crash, the states of bridge objects for all EJBs are restored to that before the crash. The handle/object reference failover allows the client to get 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 "Packaging for Deployment.

Security

Security on the Rich Client path is integrated with iAS' security infrastructure. The CXS uses iAS' 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 type of the object 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 number of retries is currently hard-coded to three.

Developing for 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 that the Rich Client needs to access are developed and deployed in exactly the same way (see Section "EJB XML DTD," in Chapter 10 "Packaging for Deployment"). There are however two key additional steps that are required when using the Rich Client path.

1. The CXS needs to be started up and configured using the iAS Administrator Tool (iASAT). The CXS is not setup during iAS installation. Instead, it is configured using iASAT 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 iAS Deployment Tool (iASDT) should be used to obtain a single JAR file corresponding to the application that needs Rich Client connectivity. This JAR file contains RMI/IIOP stubs that are generated from the EJB home and remote interfaces. The iASDT ensures that all the server-side ties and stubs for the application are made available to the CXS.

Client Side

The client-side of the Rich Client system requires the following pieces, at a minimum, in order to be completely up and running. All the classes in the following pieces need to be in the client-side CLASSPATH.

1. The following iAS-specific components that come bundled in one tar file called iasclient.tar (zip file iasclient.zip on NT) on the iAS 6.0 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 has to necessarily use this JDK. The reason for this is that this JDK has the Javasoft ORB packaged inside it as an extension unlike the pristine JDK.

   2. iAS-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 needs to be logged in. (See "java com.netscape.ejb.client.AppContainer <client ear file> -iasXml <ias xml file> [-resourceXml <resource xml file>]" section.)

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. Look at the "Sample code" section for an example.

Application Client Container

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

1. One additional jar, namely iasacc.jar, contained in iasclient.tar/iasclient.zip (mentioned in (1) above) needs to get into the client's CLASSPATH.

2. A J2EE v1.2-compliant EAR file will need to be created. This EAR file should contain
   1. The RMI/IIOP client mentioned in (4) above.

   2. A J2EE v1.2 XML descriptor file (application-client.xml). Refer to the J2EE 1.2 specifications for an explanation.

   See Chapter 11, "Packaging for Deployment".

3. An iAS-specific XML descriptor file (typically ias-application-client.xml). Refer to Appendix C section for an example.

4. An optional resource XML descriptor file (typically resource-application-client.xml) required only if the client needs to access resources such as JDBC drivers. Refer to Appendix C section for an example with explanations.

The command to invoke the client through the Application Client Container looks like this:

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

Sample code

---

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 JNDI name of the bean needs to be 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");

The rich client requires client to set few properties. The above property specifies that the client code would use CORBA CosNaming SPI from Sun's JNDI implementation to communicate with the CosNaming server running inside the CXS.

// Client security principal

env.put("com.netscape.ejb.client.PrincipalClass",

<my principal class name>);

If the client code wants to support secure invocations as mentioned earlier IUserPrincipal interface needs to 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 host and port of the CXS the client wants to connect to needs to be specified here. The iiop port number for CXS was probably configured when the CXS was created using iASAT.

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 would be to pop up 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 would be used to set the security context that is propagated by the client.

The CXS will try to authenticate the user/password with the iAS security manager, if an authentication exception occurs in CXS the client-side orb would be notified and would then re-trigger the setPrincipal callback to give another chance to capture the correct user/password information. The orb would re-try the request automatically 3 times after which the Authentication exception is propagated up to the client code.

Another valid implementation of IUserPrincipal could support multiple user identities in the same client JVM. This can be done by using ThreadLocal variables to store username and password. The methods in the IUserPrincipal implementation would then need 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;

}

}