Handles

Handles in EJB provide a mechanism to store a reference to a remote home or a remote interface to a long- term persistent store and later re-acquire that reference back to the same home or remote object. Because handles only relate to remote objects, local clients are not exposed to handles and have no need for them.

Two types of handles are defined in the EJB 2.0 Specification. One is the javax.ejb.Handle interface and the other is javax.ejb.HomeHandle interface. You might wonder if the HomeHandle interface extends the Handle interface, but it doesn't. In the same way that there is no direct relationship between a home and remote interface, a HomeHandle and a Handle are not directly related . Here is the single method signature for the Handle interface:

 public EJBObject getEJBObject() throws java.rmi.RemoteException; 

and here is the method signature for the HomeHandle interface:

 public EJBHome getEJBHome() throws java.rmi.RemoteException; 

Although you might be tempted to share a handle for one client with another client, you must be careful. If for example, you shared a handle to a session bean between two clients and the clients attempted to invoke operations on the same instance at the same time, an exception will occur. The safest thing to do is to only use handles to save access for a specific client so that the same client can access the instance at a later time. Handle and HomeHandle references can be serialized and deserialized, and therefore are valid RMI types.

Handles really will work this way only if the object that they are referencing in the container is still available when a client attempts to use the reference later. A server crash or timeout might have removed the object and made it unavailable.

The following code fragment illustrates how you can use a Handle to obtain a remote reference:

 public void loadShoppingCart( Handle handle ) {     // The handle is a javax.ejb.Handle that has been created      // by another client and passed in.      ShoppingCart otherCart = null;      // Get a remote interface reference to the shopping cart      otherCart = (ShoppingCart)javax.rmi.PortableRemoteObject.narrow(                                                         handle.getEJBObject(),                                                          ShoppingCart.class );      // Invoke a method call on the remote reference      List shoppingCartContents = cart.getContents();      // Call a method to load this clients shopping cart from      // the contents of the other shopping cart      loadMyShoppingCart( shoppingCartContents );  } 

When another client invokes a method call on a remote interface obtained from a Handle as above, the normal security checks are performed to ensure that the client can invoke the methods on the bean.