Java 2 Platform, Enterprise Edition: Platform and Component Specifications

EJB.8.4 Entity Object's Life Cycle

This section describes the life cycle of an entity object from the perspective of a client.

Figure EJB.8-2 illustrates a client's point of view of an entity object life cycle. (The term referenced in the diagram means that the client program has a reference to the entity object's remote interface.)

An entity object does not exist until it is created. Until it is created, it has no identity. After it is created, it has identity. A client creates an entity object using the entity bean's home interface whose class is implemented by the container. When a client creates an entity object, the client obtains a reference to the newly created entity object.

In an environment with legacy data, entity objects may "exist" before the container and entity bean are deployed. In addition, an entity object may be "created" in the environment via a mechanism other than by invoking a create(...) method of the home interface (e.g., by inserting a database record), but still may be accessible by a container's clients via the finder methods . Also, an entity object may be deleted directly using other means than the remove() operation (e.g., by deletion of a database record). The "direct insert" and "direct delete" transitions in the diagram represent such direct database manipulation.

A client can get a reference to an existing entity object's remote interface in any of the following ways:

• Receive the reference as a parameter in a method call (input parameter or result).

• Find the entity object using a finder method defined in the entity bean's home interface.

• Obtain the reference from the entity object's handle (see Section EJB.8.7).

A client that has a reference to an entity object's remote interface can do any of the following:

• Invoke business methods on the entity object through the remote interface.

• Obtain a reference to the enterprise bean's home interface.

• Pass the reference as a parameter or return value of a remote method call.

• Obtain the entity object's primary key.

• Obtain the entity object's handle.

• Remove the entity object.

All references to an entity object that does not exist are invalid. All attempted invocations on an entity object that does not exist result in a java.rmi.NoSuchObjectException being thrown.

All entity objects are considered persistent objects . The lifetime of an entity object is not limited by the lifetime of the Java virtual machine process in which the entity bean instance executes. While a crash of the Java virtual machine may result in a rollback of current transactions, it does not destroy previously created entity objects nor invalidate the references to the remote and home interfaces held by clients.

Multiple clients can access the same entity object concurrently. Transactions are used to isolate the clients' work from each other.