Before going on, let’s establish some conventions. When we speak about an enterprise bean as a whole—its component interfaces, bean class, and so forth—we will call it by its common business name, followed by the acronym " EJB.” For example, an enterprise bean that is developed to model a cabin on a ship will be called the “Cabin EJB.” Notice that we don’t use a constant-width font for “Cabin.” This is because we are referring to all the parts of the bean (the component interfaces, bean class, etc.) as a whole, not just to one particular part, such as the remote interface or bean class. The term enterprise bean or bean denotes any kind of bean, including entity, session, and message-driven beans. Entity bean denotes an entity-type enterprise bean; session bean denotes a session-type enterprise bean; and message-driven bean denotes a message driven-type enterprise bean. It’s popular to use the acronym EJB for enterprise bean, a style adopted in this book.

We will also use suffixes to distinguish between local component interfaces and remote component interfaces. When we are talking about the remote interface of the Cabin EJB we will combine the common business name with the word Remote. For example, the remote interface for the Cabin EJB is called the CabinRemote interface. In EJB 2.0, the local component interface of the Cabin EJB would be the CabinLocal interface. The home interfaces follow the convention by adding the word Home to the mix. The remote and local home interfaces for the Cabin EJB would be CabinHomeRemote and CabinHomeLocal, respectively. The bean class is always the common business name followed by the word Bean. For example, the Cabin EJB’s bean class would be named CabinBean.

Having introduced the machinery, let’s look at how to build an entity or stateful enterprise bean with remote component interfaces. In this section, we will examine the Cabin EJB, an entity bean that models a cabin on a cruise ship. Let’s start with its remote interface.

We’ll define the remote interface for a Cabin bean using the CabinRemote interface, which defines business methods for working with cabins. All remote-interface types extend the javax.ejb.EJBObject interface:

import java.rmi.RemoteException;

public interface CabinRemote extends javax.ejb.EJBObject {
    public String getName() throws RemoteException;
    public void setName(String str) throws RemoteException;
    public int getDeckLevel() throws RemoteException;
    public void setDeckLevel(int level) throws RemoteException;
}

These are methods for naming the cabin and methods for setting the cabin’s deck level; you can probably imagine lots of other methods that you’d need, but this is enough to get started. All of these methods declare that they throw RemoteException, which is required of all methods on remote component interfaces, but not EJB 2.0’s local component interfaces. EJB requires the use of Java RMI-IIOP conventions with remote component interfaces, although the underlying protocol can be CORBA IIOP, Java Remote Method Protocol ( JRMP), or some other protocol. Java RMI-IIOP will be discussed in more detail in the next chapter.

The remote home interface defines life-cycle methods used by clients of entity and session beans for locating enterprise beans. The remote home interface extends javax.ejb.EJBHome . We’ll call the home interface for the Cabin bean CabinHomeRemote and define it like this:

import java.rmi.RemoteException;
import javax.ejb.CreateException;
import javax.ejb.FinderException;

public interface CabinHomeRemote extends javax.ejb.EJBHome {
    public CabinRemote create(Integer id) 
        throws CreateException, RemoteException;
    public CabinRemote findByPrimaryKey(Integer pk)
        throws FinderException, RemoteException;
}

The create() method is responsible for initializing an instance of our bean. If your application needs them, you can provide other create() methods with different arguments.

In addition to findByPrimaryKey(), you are free to define other methods that provide convenient ways to look up Cabin beans—for example, you might want to define a method called findByShip() that returns all the cabins on a particular ship. Find methods like these are used in entity beans but not in session beans and obviously not in message-driven beans.

Now let’s look at an actual entity bean. Here’s the code for the CabinBean; it’s a sparse implementation, but it will show you how the pieces fit together:

import javax.ejb.EntityContext;

public abstract class CabinBean implements javax.ejb.EntityBean {

    public Integer ejbCreate(Integer id){
        setId(id);
        return null;
    }
    public void ejbPostCreate(Integer id){
        // do nothing
    }

    public abstract String getName();
    public abstract void setName(String str);

    public abstract int getDeckLevel();
    public abstract void setDeckLevel(int level);

    public abstract Integer getId();
    public abstract void setId(Integer id);

    public void setEntityContext(EntityContext ctx){
        // not implemented
    }
    public void unsetEntityContext(){
        // not implemented
    }
    public void ejbActivate(){
        // not implemented
    }
    public void ejbPassivate(){
        // not implemented
    }
    public void ejbLoad(){
        // not implemented
    }
    public void ejbStore(){
        // not implemented
    }
    public void ejbRemove(){
        // not implemented
    }
}

Notice that the CabinBean class is declared as abstract, as are several of its methods that access or update the EJB’s persistent state. Also notice that there are no instance fields to hold the state information these methods access. This is because we are working with a container-managed entity bean, which has its abstract methods implemented by the container system automatically—this will be explained in detail later in the book. EJB 2.0 container-managed entity beans are the only beans that are declared as abstract with abstract accessor methods. You won’t see abstract classes and methods with other types of entity beans, session beans, or message-driven beans.

Here’s the code for the CabinBean in EJB 1.1:

import javax.ejb.EntityContext;

public class CabinBean implements javax.ejb.EntityBean {

    public Integer id;
    public String name;
    public int deckLevel;
 
    public Integer ejbCreate(Integer id){
        setId(id);
        return null;
    }
    public void ejbPostCreate(Integer id){
        // do nothing
    }

    public String getName(){
        return name;
    }    
    public void setName(String str){
        name = str;
    }

    public int getDeckLevel(){
        return deckLevel;
    }
    public void setDeckLevel(int level){
        deckLevel = level;
    }
    public Integer getId(){
        return id;
    }
    public void setId(Integer id){
        this.id = id;
    }
    public void setEntityContext(EntityContext ctx){
        // not implemented
    }
    public void unsetEntityContext(){
        // not implemented
    }
    public void ejbActivate(){
        // not implemented
    }
    public void ejbPassivate(){
        // not implemented
    }
    public void ejbLoad(){
        // not implemented
    }
    public void ejbStore(){
        // not implemented
    }
    public void ejbRemove(){
        // not implemented
    }
}

The set and get methods for the cabin’s name and deck level are the CabinBean’s business methods; they match the business methods defined by the EJB’s remote interface, CabinRemote. The CabinBean class has state and business behavior that models the concept of a cabin. The business methods are the only methods visible to the client application; the other methods are visible only to the EJB container or the bean class itself. For example, the setId()/ getId() methods are defined in the bean class but not in the remote interface, which means they cannot be called by the entity bean’s client. The other methods are required by the EJB component model and are not part of the bean class’s public business definition.

The ejbCreate() and ejbPostCreate() methods initialize the instance of the bean class when a new cabin record is to be added to the database. The last seven methods in the CabinBean are defined in the javax.ejb.EntityBean interface. These methods are life-cycle callback methods. The EJB container invokes these callback methods on the bean class when important life-cycle events occur. The ejbRemove() method, for example, notifies an entity bean that its data is about to be deleted from the database. The ejbLoad() and ejbStore() methods notify the bean instance that its state is being read or written to the database. The ejbActivate() and ejbPassivate() methods notify the bean instance that it is about to be activated or deactivated, a process that conserves memory and other resources. setEntityContext() provides the bean with an interface to the EJB container that allows the bean class to get information about itself and its surroundings. unsetEntityContext() is called by the EJB container to notify the bean instance that it is about to be dereferenced for garbage collection.

All these callback methods provide the bean class with notifications of when an action is about to be taken, or was just taken, on the bean’s behalf by the EJB server. These notifications simply inform the bean of an event; the bean doesn’t have to do anything about it. The callback notifications tell the bean where it is during its life cycle, when it is about to be loaded, removed, deactivated, and so on. Most of the callback methods pertain to persistence, which can be done automatically for the bean class by the EJB container. Because the callback methods are defined in the javax.ejb.EntityBean interface, the entity bean class must implement them, but it isn’t required to do anything meaningful with the methods if it doesn’t need to. Our bean, the CabinBean, won’t need to do anything when these callback methods are invoked, so these methods are empty implementations. Details about these callback methods, when they are called, and how a bean should react to them are covered in Chapter 11.

The primary key is a pointer that helps locate data that describes a unique record or entity in the database; it is used in the findByPrimaryKey() method of the home interface to locate a specific entity. Primary keys are defined by the bean developer and must be some type of serializable object. The Cabin EJB uses a simple java.lang.Integer type as its primary key. Its also possible to define custom primary keys, called compound primary keys , which represent complex primary keys consisting of several different fields. Primary keys are covered in detail in Chapter 11.

CabinBean is an entity bean, but a session bean wouldn’t be all that different. It would extend SessionBean instead of EntityBean and would have an ejbCreate() method that would initialize the bean’s state, but no ejbPostCreate(). Session beans do not have an ejbLoad() or ejbStore() method, because session beans are not persistent. While session beans have a setSessionContext() method, they do not have an unsetSessionContext() method. Session beans do have ejbActivate() and ejbPassivate() methods, which are used by stateful session beans to manage conversational state. Finally, session beans would provide an ejbRemove() method, which would be called to notify the bean that the client no longer needs it. However, this method wouldn’t tell the bean that its data was about to be removed from the database, because a session bean doesn’t represent data in the database.

Session beans don’t have a primary key. That’s because session beans are not persistent themselves, so there is no need for a key that maps to the database. Session beans are covered in detail in Chapter 12.

Remote, local, and home interfaces would not be defined for a message-driven bean, because message-driven beans do not have component interfaces. Instead, the message-driven bean would define only a few callback methods and no business methods. The callback methods include the ejbCreate() method, which is called when the bean class is first created; the ejbRemove() method, called when the bean instance is about to be discarded from the system (usually when the container doesn’t need it any longer); the setMessageDrivenBeanContext(); and the onMessage() method. The onMessage() method is called every time a new asynchronous message is delivered to the message-driven bean. The message-driven bean doesn’t define the ejbPassivate()/ejbActivate() or ejbLoad()/ejbStore() methods because it doesn’t need them.

Message-driven beans don’t have a primary key, for the same reason that session beans don’t. They are not persistent, so there is no need for a key to the database. Message-driven beans are covered in detail in Chapter 13.

The following deployment descriptor might be used to describe the Cabin bean in EJB 2.0:

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD EnterpriseJavaBeans 2.0//EN" 
"http://java.sun.com/dtd/ejb-jar_2_0.dtd">

<ejb-jar>
    <enterprise-beans>
        <entity>
            <ejb-name>CabinEJB</ejb-name>
            <home>com.titan.CabinHomeRemote</home>
            <remote>com.titan.CabinRemote</remote>
            <local-home>com.titan.CabinHomeLocal</local-home>
            <local>com.titan.CabinLocal</local>
            <ejb-class>com.titan.CabinBean </ejb-class>
            <persistence-type>Container</persistence-type>
            <prim-key-class>java.lang.Integer</prim-key-class>
            <reentrant>False</reentrant>
        </entity>
    </enterprise-beans>
</ejb-jar>

The following deployment descriptor might be used to describe the Cabin bean in EJB 1.1:

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD EnterpriseJavaBeans 1.1//EN" 
"http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">

<ejb-jar>
    <enterprise-beans>
        <entity>
            <ejb-name>CabinEJB</ejb-name>
            <home>com.titan.CabinHomeRemote</home>
            <remote>com.titan.CabinRemote</remote>         
            <ejb-class>com.titan.CabinBean</ejb-class>            
            <persistence-type>Container</persistence-type>
            <prim-key-class>java.lang.Integer</prim-key-class>
            <reentrant>False</reentrant>
        </entity>
    </enterprise-beans>
</ejb-jar>

The deployment descriptor for a real bean would have a lot more information. This example simply illustrates the type of information you’ll find in an XML deployment descriptor.

The first element in any XML document is <!DOCTYPE> . This element describes the organization that defined the DTD for the XML document, the DTD’s version, and a URL location of the DTD. The DTD describes how a particular XML document is structured.

All the other elements in the XML document are specific to EJB. They do not represent all the elements used in deployment descriptors, but they illustrate the types of elements that are used. Here’s what the elements mean:

The last two elements in the deployment descriptor, the <persistence-type> and <reentrant> elements, express the persistence strategy and concurrency policies of the entity bean. These elements are explained in more detail later in the book.

As you progress through this book, you will be introduced to the elements that describe concepts we have not covered yet, so don’t worry about knowing all of the elements you might find in a deployment descriptor at this time.

This chapter has said a lot about a bean’s remote and local interfaces, which extend the EJBObject and, for EJB 2.0, the EJBLocalObject interfaces, respectively. Who implements these interfaces? Clearly, the stub does: we understand that much. But what about the server side?

On the server side, an EJB object is an object that implements the remote and/or local (EJB 2.0) interfaces of the enterprise bean. The EJB object wraps the enterprise bean instance—that is, an instance of the enterprise bean class you’ve created (in our example, the CabinBean)—on the server and expands its functionality to include javax.ejb.EJBObject and/or javax.ejb.EJBLocalObject behavior.

You will have noticed that “and/or” is used a lot when talking about which interface the EJB object implements. That’s because enterprise beans in EJB 2.0 can declare either the local interface, remote interface, or both! Local interfaces don’t apply to EJB 1.1, so if you are working with that version, ignore references to them; they are relevant only to EJB 2.0 container systems.

In EJB 2.0, regardless of which interfaces the bean implements, we can think of the EJB object as implementing both. In reality, there may be a special EJB object for the remote interface and another special EJB object for the local interface of each enterprise bean; that depends on the how the vendor chooses to implement it. For our purposes, the term EJB object will be used to talk about the implementation of either the local or remote interfaces, or both. The functionality of these interfaces is so similar from the EJB object’s perspective that discussing separate EJB object implementations isn’t necessary.

The EJB object is generated by the utilities provided by the vendor of your EJB container and is based on the bean classes and the information provided by the deployment descriptor. The EJB object wraps the bean instance and works with the container to apply transactions, security, and other system-level operations to the bean at runtime. Chapter 3 talks more about the EJB object’s role with regard to system-level operations.

A vendor can use a number of strategies to implement the EJB object. Figure 2-1 illustrates three possibilities using the CabinRemote interface. The same implementation strategies apply to the CabinLocal and javax.ejb.EJBLocalObject interfaces.

Figure 2-1. Three ways to implement the EJB object

In Figure 2-1(a), the EJB object is a classic wrapper because it holds a reference to the bean class and delegates the requests to the bean. Figure 2-1(b) shows that the EJB object class actually extends the bean class, adding functionality specific to the EJB container. In Figure 2-1(c), the bean class is no longer included in the model. In this case, the EJB object has both the proprietary implementation required by the EJB container and bean class method implementations that were copied from the bean class’s definition.

The EJB object design shown in Figure 2-1(a) is perhaps the most common. Throughout this book, particularly in the next chapter, we will explain how EJB works with the assumption that the EJB object wraps the bean class instance as depicted in Figure 2-1(a). But the other implementations are used; it shouldn’t make a difference which one your vendor has chosen. The bottom line is that you never really know much about the EJB object: its implementation is up to the vendor. Knowing that the EJB object exists answers a lot of questions about how enterprise beans are structured. The information that a client (including other enterprise beans) needs to know about an enterprise bean is described by the remote and home interfaces.

The EJB home is a lot like the EJB object. It’s another class that’s generated automatically when you install an enterprise bean in a container. It implements all the methods defined by the home interfaces (local and/or remote) and is responsible for helping the container manage the bean’s life cycle. Working closely with the EJB container, the EJB home is responsible for locating, creating, and removing enterprise beans. This may involve working with the EJB server’s resource managers and instance pooling and persistence mechanisms, the details of which are hidden from the developer.

For example, when a create method is invoked on a home interface, the EJB home creates an instance of the EJB object that references a bean instance of the appropriate type. Once the bean instance is associated with the EJB object, the instance’s matching ejbCreate() method is called. In the case of an entity bean, a new record is inserted into the database. With session beans, the instance is simply initialized. Once the ejbCreate() method has completed, the EJB home returns a remote or local reference (i.e., a stub) for the EJB object to the client. The client can then begin to work with the EJB object by invoking business methods using the stub. The stub relays the methods to the EJB object; in turn, the EJB object delegates those method calls to the bean instance.

In EJB 2.0, how does the EJB home know which type of EJB object reference (local or remote) to return? It depends on which home interface is being used. If the client invokes a create() method on the remote home interface, the EJB home will return a remote interface reference. If the client is working with a local home interface, the EJB home will return a reference implementing the local interface. EJB 2.0 requires that the return type of remote home interface methods be remote interfaces and that the return type of local home interface methods be local interfaces:

// The Cabin EJB's remote home interface
public interface CabinHomeRemote extends javax.ejb.EJBHome {
    public CabinRemote create(Integer id) 
        throws CreateException, RemoteException;
    public CabinRemote findByPrimaryKey(Integer pk)
        throws FinderException, RemoteException;
}


// The Cabin EJB's local home interface
public interface CabinHomeLocal extends javax.ejb.EJBLocalHome {
    public CabinLocal create(Integer id) 
        throws CreateException;
    public CabinLocal findByPrimaryKey(Integer pk)
        throws FinderException;
}

Figure 2-2 illustrates the architecture of EJB with the EJB home and EJB object implementing the home interface and remote or local interface, respectively. The bean class is also shown as being wrapped by the EJB object.

Throughout this book, we will consider the EJB object and EJB home as constructs that support both the remote and local component interfaces. In reality, we have no idea how the vendor chose to implement the EJB object and EJB home, since they are only logical constructs and may not have equivalent software counterparts. It’s important to remember that “EJB object” and “EJB home” are simply terms to describe the EJB container’s responsibilities for supporting the component interfaces. We have chosen to give them a more concrete description in this book purely for instructional purposes; the EJB object and EJB home implementations discussed throughout this book are to be considered illustrative and not a true representation of how these terms may be implemented.

The EJB objects and EJB homes are automatically generated during the deployment process. After the files that define the bean (the component interfaces and the bean classes) have been packaged into a JAR file, the bean is ready to be deployed; that is, it can be added to an EJB container so it can be accessed as a distributed component. During the deployment process, tools provided by the EJB container vendor generate the EJB object and EJB home classes by examining the deployment descriptor and the other interfaces and classes in the JAR file.

Figure 2-2. EJB architecture