Oracle8i Enterprise JavaBeans Developer's Guide and Reference Release 3 (8.1.7) Part Number A83725-01 |
Library | Service | Contents | Index

## Implementing Callback Methods

An entity bean is a remote object that manages its data persistently through callback methods, which are defined in the `javax.ejb.EntityBean` interface. When you implement the `EntityBean` interface in your bean class, you develop each of the callback functions as designated by the type of persistence that you choose: bean-managed persistence or container-managed persistence. The container invokes the callback functions at designated times, to manage the bean and its persistent data. That is, the contract between the container and the entity bean involves in what order the callback methods are invoked and who manages the bean's persistent data.

Your bean class implements the methods of the `EntityBean` interface. The `javax.ejb.EntityBean` interface has the following definition:

    public interface javax.ejb.EntityBean extends javax.ejb.EnterpriseBean {
          public abstract void ejbActivate();
       public abstract void ejbLoad();
          public abstract void ejbPassivate();
          public abstract void ejbRemove();
       public abstract void ejbStore();
          public abstract void setEntityContext(EntityContext ctx);
       public abstract voic unsetEntityContext();
    }

The container expects these methods to have the following functionality:

`ejbCreate` | You must implement an `ejbCreate` method corresponding to one `create` method declared in the home interface. When the client invokes the `create` method, the container first invokes the constructor to instantiate the object, then it invokes the corresponding `ejbCreate` method. The `ejbCreate` method performs the following: creates any persistent storage for its data, such as database rows intializes a unique primary key and returns it
`ejbPostCreate` | The container invokes this method after the environment is set. For each `ejbCreate` method, an `ejbPostCreate` method must exist with the same arguments. This method can be used to initialize parameters within or from the entity context.
`ejbRemove` | The container invokes this method before it ends the life of the session object. This method may perform any required clean-up, for example closing external resources such as file handles.
`ejbStore` | The container invokes this method right before a transaction commits. It saves the persistent data to an outside resource, such as a database.
`ejbLoad` | The container invokes this method within a transaction when the data should be reinitialized from the database. This normally occurs after the transaction begins.
`setEntityContext` | Associates the bean instance with context information. The container calls this method after the bean creation. The enterprise bean can store the reference to the context object in an instance variable, for use in transaction management. Beans that manage their own transactions can use the session context to get the transaction context. You can also allocate any resources that will exist for the lifetime of the bean within this method. You should release these resources in `unsetEntityContext`.
`unsetEntityContext` | Unset the associated entity context and release any resources allocated in `setEntityContext`.
`ejbActivate` | Implement this as a null method, because it is never called in this release of the server.
`ejbPassivate` | Implement this as a null method, because it is never called in this release of the server.

### Using ejbCreate and ejbPostCreate

An entity bean is similar to a session bean in that certain callback methods, such as `ejbCreate`, are invoked at specified times. Entity beans use callback functions for managing its persistent data, primary key, and context information. The following diagram shows what methods are called when an entity bean is created.

#### Figure 4-2 Creating the Entity Bean

### Using setEntityContext

This method is used by an entity bean instance to retain a reference to its context. Entity beans have contexts that the container maintains and makes available to the beans. The bean may use the methods in the entity context to retrieve information about the bean, such as security, and transactional role. Refer to the Enterprise JavaBeans 1.1 specification for the full range of information that you can retrieve about the bean from the context.

The container invokes `setEntityContext` method, after it first instantiates the bean, to enable the bean to retrieve the context. The container will never call this method from within a transaction context. If the bean does not save the context at this point, the bean will never gain access to the context.

Note: You can also use the `setEntityContext` and `unsetEntityContext` methods to allocate and destroy any resources that will exist for the lifetime of the instance.

When the container calls this method, it passes the reference of the `EntityContext` object to the bean. The bean can then store the reference for later use. The following example shows the bean saving the context in the `this.ctx` variable.

    public void setEntityContext(EntityContext ctx)
    {
      this.ctx = ctx;
      Properties props = ctx.getEnvironment();
    }

### Using ejbRemove

When the client invokes the remove method, the container invokes the following methods.

#### Figure 4-3 Removing the Entity Bean

### Using ejbStore and ejbLoad

In addition, the `ejbStore` and `ejbLoad` methods are called for managing your persistent data. These are the most important callback methods--for bean-managed persistent beans.

- The `ejbStore` method is called by the container whenever a transaction is about to end. Its purpose is to save the persistent data to an outside resource, such as a database.

- The `ejbLoad` method is called by the container whenever a transaction has begun or when an entity bean is instantiated. Its purpose is to restore any persistent data that exists for this particular bean instance.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index