# Using an EJB Control

After you have created an EJB Control, you can invoke an target EJB method via the EJB control. Specifically, the EJB control exposes all and only the EJB methods defined in the EJB interfaces that the control extends. You can invoke these methods simply by invoking the method with the same signature on your EJB control.

The EJB control automatically manages locating and referencing the EJB instance, and directs method invocations to the correct instance of the target EJB. Whether or not you must first create an instance of the target EJB using the EJB's create method depends on whether the EJB control references a session or an entity bean. This is discussed next.

## Selecting Instances for Session EJBs

A session EJB is used to execute business tasks for a client on the application server. The session EJB might execute only a single method for a client, in the case of stateless session beans, or it might execute several methods for that same client, in the case of stateful session beans. A session bean never serves multiple clients at the same time. The lifetime of a stateful session bean is tied to the duration of the conversation with the client. In contrast, a small number of pooled stateless session bean instances is used to serve large number of client requests. For more information on the lifetime of stateless and stateful session beans, see The Life Cycle of a Session Bean.

### Creating a Session EJB

If the target EJB is a stateless session bean, you do not need to invoke the create method of the EJB via the EJB control. Instead, the EJB control automatically creates a reference to an appropriate instance of the EJB whenever one of the EJB's business methods is invoked, as is shown in this code fragment:

       /**
        * @common:control
        */
       private EJBControls.MusicBeanControl library;
       ...
       // create method is not invoked first
       allBands = library.getBands();

If the target EJB is a stateful session bean you must first invoke (one of) its create method(s) to obtain a reference. For more information about the differences between stateful and stateless session beans, see Getting Started with Session Beans.

### Caching a Session EJB Reference

After a reference is obtained, it is cached in the EJB control and is used for any subsequent calls to the EJB within the method invocation in which the initial call was made. If for a stateless session bean you explicitly call the create method, or if for a stateful session bean you again call a create method, the EJB control replaces a previously cached reference with the newly created reference.

The lifetime of the cached EJB reference within the EJB control depends on the invoking application and the type of session bean. If a stateful session EJB is invoked by a conversational web service (that is, a web service method that takes part in a conversation), the EJB reference's lifetime is the lifetime of the conversation. If a stateful or stateless session EJB is invoked by a non-conversational web service, the lifetime of the EJB reference in the EJB control is the lifetime of the web service method invocation. For page flows and both stateful and stateless session EJBs, if the session EJB is defined in the controller class, the lifetime of the reference is the lifetime of the page flow.

### Removing a Session EJB

When you call the remove method on an EJB control that represents a session EJB, the currently cached instance of the bean is released. The server might destroy the bean at that time, but the actual behavior is up to the server. Either way, the bean no longer communicates with the EJB control.

## Selecting Instances for Entity Beans

Instances of entity EJBs are associated with a particular collection of data. Typically this collection of data is a row in a database table.

### Creating an Entity EJB

When you invoke the EJB's create method through the EJB control, you create a new persistent entity, that is, a new record in the underlying database table. In other words, creating a new entity bean with the create method amounts to inserting a new record in a table.

### Referencing an Entity EJB

You can reference an entity EJB instance by calling the findByPrimaryKey method, or another findXxx method provided by the EJB's designer that returns a reference to one entity bean. In other words, the entity bean instance represents an existing record in a database table.

### Caching an Entity EJB Reference

The EJB control caches a reference to the EJB instance being used, that is, the instance returned by the most recent call to the create, findByPrimaryKey or findXxx method, which returns one data record. When you invoke subsequent methods on the EJB control, it invokes that method on the EJB instance to which the cached reference refers. If there is no EJB reference currently cached, the EJB control attempts to invoke the findByPrimaryKey method with the last successful key used in a create or findByPrimaryKey call. If there is no previous key, the EJB control throws an exception.

The lifetime of the cached entity EJB reference within the EJB control depends on the invoking application. If the entity EJB is invoked by a conversational web service (that is, a web service method that takes part in a conversation), the EJB reference's lifetime is the lifetime of the conversation. For non-conversational web services, the lifetime of the EJB reference in the EJB control is the lifetime of the web service method invocation. For page flows, if the entity EJB is defined in the controller class, the lifetime of the reference is the lifetime of the page flow.

### Removing an Entity EJB

When you call the remove method on an EJB control that represents an entity EJB, the record represented by the cached EJB reference is removed from the underlying persistent storage. That is, the row is deleted from the database table.

### Returning Multiple Records

A findXxx method may return a Collection object, holding a set of references to entity beans. The EJB control does not cache this object. If you wish to cache the return value of a findXxx method, you should store the object in a member variable of the application invoking the EJB control.

Related Topics

Overview: Enterprise JavaBeans and EJB Controls

Creating a New EJB Control

Getting Started with Session Beans

Getting Started with Entity Beans