Handles

In some cases, an EJB client may wish to save its EJBObject reference to persistent storage for retrieval at a later date or more likely by another program. The EJB specification defined the concept of Handles as a serializable object that encapsulates sufficient information to reconstitute an EJBObject reference. Handles might be used to pass EJB references between two cooperating processes. The receiving process gets the EJBObject reference back again from the Handle. To get a Handle, the programmer calls the getHandle() method on the EJBObject interface. This returns the programmer an instance of javax.ejb.Handle. To re-create the EJBObject reference, the Handle interface contains a getEJBObject() method.

For instance:

// convert EJBObject into a Handle reference
HelloWorld hw = home.create();
javax.ejb.Handle handle = hw.getHandle();

// get the EJBObject reference back
HelloWorld backAgain = (HelloWorld)
  PortableRemoteObject.narrow(handle.getEJBObject(), HelloWorld.class);

HomeHandles

The EJB specification also defines the javax.ejb.HomeHandle interface. HomeHandles are similar to Handles but instead of applying to EJBObject references, they contain enough information to rebuild EJBHome references. To get a HomeHandle reference, the programmer calls the getHomeHandle method on the EJBHome reference. This method returns an instance of the javax.ejb.HomeHandle interface. The programmer can then regain the Home reference by calling HomeHandle's getEJBHome method.

For instance:

// save to a HomeHandle reference
Context ctx = new InitialContext();
Object h = ctx.lookup("HelloWorldEJB");
HelloWorldHome home = (HelloWorldHome);
  PortableRemoteObject.narrow(h, HelloWorldHome.class);

HomeHandle homeHandle = home.getHomeHandle();

// rebuild the Home reference

Object nh = homeHandle.getEJBHome();

HelloWorldHome newHomeReference = (HelloWorldHome)
  PortableRemoteObject.narrow(nh, HelloWorldHome.class);

Advantages of Handles

The main advantage of HomeHandles and Handles is that they automatically store the information needed to rebuild the reference. For instance, a HomeHandle encapsulates the information necessary to create an InitialContext to the WebLogic Server and then looks up the correct Home object. A client that receives a HomeHandle can get the EJBHome reference without having to know the server's URL or the JNDI name of the EJBHome.

A common misconception is that HomeHandles are more efficient than explicitly building an InitialContext and performing a lookup on the JNDI name. In general, both cases perform identical steps. The HomeHandle merely stores the information that the programmer would have to provide.

It is also important to note that Handles do not store the current identity, and they may not be used as a security credential. For instance, consider a password EJB where only principals in the role of administrator may access the bean. An administrator may access the bean and store a Handle. Now, if another user receives the Handle and calls getEJBObject, the new user has a password reference. To call any restricted method on the password reference, the new user still needs to be authenticated as an administrator. The Handle does not automatically grant any permissions.