Sun Microsystem Inc

The lifetime and scope of a handle is specific to the handle implementation. At the minimum, a program running in one JVM must be able to obtain and serialize the handle, and another program running in a different JVM must be able to deserialize it and re-create an object reference. An entity handle is typically implemented to be usable over a long period of time—it must be usable at least across a server restart.

Containers that store long-lived entities will typically provide handle implementations that allow clients to store a handle for a long time (possibly many years). Such a handle will be usable even if parts of the technology used by the container (e.g. ORB, DBMS, server) have been upgraded or replaced while the client has stored the handle. Support for this “quality of service” is not required by the EJB specification.

An EJB Container is not required to accept a handle that was generated by another vendor’s EJB Container.

The use of a handle is illustrated by the following example:

// A client obtains a handle of an account entity object and

//stores the handle in stable storage.

ObjectOutputStream stream = ...; Account account = ...;

Handle handle = account.getHandle(); stream.writeObject(handle);

//A client can read the handle from stable storage, and use the

//handle to resurrect an object reference to the

//account entity object.

//

ObjectInputStream stream = ...;

Handle handle = (Handle) stream.readObject(handle);

Account account = (Account)javax.rmi.PortableRemoteObject.narrow( handle.getEJBObject(), Account.class);

account.debit(100.00);

A handle is not a capability, in the security sense, that would automatically grant its holder the right to invoke methods on the object. When a reference to a object is obtained from a handle, and then a method on the object is invoked, the container performs the usual access checks based on the caller’s principal.

8.8 Entity home handles

The EJB specification allows the client to obtain a handle for the home interface. The client can use the home handle to store a reference to an entity bean’s home interface in stable storage, and re-create the reference later. This handle functionality may be useful to a client that needs to use the home interface in the future, but does not know the JNDI API name of the home interface.

A handle to a home interface must implement the javax.ejb.HomeHandle interface.

Sun Microsystems Inc.

The client code must use the javax.rmi.PortableRemoteObject.narrow(...)method to convert the result of the getEJBHome() method invoked on a handle to the home interface type.

The lifetime and scope of a handle is specific to the handle implementation. At the minimum, a program running in one JVM must be able to serialize the handle, and another program running in a different JVM must be able to deserialize it and re-create an object reference. An entity handle is typically implemented to be usable over a long period of time—it must be usable at least across a server restart.

8.9 Type narrowing of object references

A client program that is intended to be interoperable with all compliant EJB Container implementations must use the javax.rmi.PortableRemoteObject.narrow(...) method to perform type-narrowing of the client-side representations of the home and remote interface.

Note: Programs that use the cast operator to narrow the remote and home interfaces are likely to fail if the Container implementation uses RMI-IIOP as the underlying communication transport.