Sun Microsystems Inc

•Obtain the home interface for the entity object.

•Remove the entity object.

•Obtain the entity object’s handle.

•Obtain the entity object’s primary key.

The container provides the implementation of the methods defined in the javax.ejb.EJBObject interface. Only the business methods are delegated to the instances of the enterprise bean class.

Note that the entity object does not expose the methods of the javax.ejb.EnterpriseBean interface to the client. These methods are not intended for the client—they are used by the container to manage the enterprise bean instances.

8.7 Entity bean’s handle

An entity object’s handle is an object that identifies the entity object on a network. A client that has a reference to an entity object’s remote interface can obtain the entity object’s handle by invoking the getHandle() method on the remote interface.

Since a handle class extends java.io.Serializable, a client may serialize the handle. The client may use the serialized handle later, possibly in a different process or even system, to re-obtain a reference to the entity object identified by the handle.

The client code must use the javax.rmi.PortableRemoteObject.narrow(...)method to convert the result of the getEJBObject() method invoked on a handle to the entity bean’s remote 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 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.

Sun Microsystems Inc.

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 an 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 name of the home interface.

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

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.

Sun Microsystems Inc

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.

Sun Microsystems Inc.