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 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,” 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. The acronym MDB is frequently used in place of the term “message-driven bean.”

We also use suffixes to distinguish between local, remote, and endpoint 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. The local interface of the Cabin EJB would be the CabinLocal interface. The endpoint interface for the Cabin EJB-based web service would be CabinWS (WS stands for Web Service). The home interfaces add the word Home to the mix. The remote and local home interfaces for the Cabin EJB would be CabinHomeRemote and CabinHomeLocal, respectively.^[8] 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.

These naming conventions are used for clarity; they are not prescriptive or even recommended for use in production. Once you understand the differences between the component interfaces and the different types of beans, you can use any naming strategy you wish.

Having introduced the machinery, let’s look at how to build an entity bean with remote component interfaces. In this section, we 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 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. 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 pk) 
        throws CreateException, RemoteException;
    public CabinRemote findByPrimaryKey(Integer id)
        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. For example, you could provide a create( ) method that initializes the cabin’s deck and name.

The findByPrimaryKey( ) method, with a single argument, is required, and allows you to look up a particular Cabin given its primary key. 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 or 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 shows how the pieces fit together:

import javax.ejb.EntityContext;

public abstract class CabinBean implements javax.ejb.EntityBean {

    public Integer ejbCreate(Integer pk){
        setId(id);
        return null;
    }
    public void ejbPostCreate(Integer pk){
        // 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 pk);

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

Notice that the CabinBean class is abstract, as are several of the methods that access or update the bean’s persistent state. Also notice that there are no instance fields to hold the state information these methods access. The abstract methods (and the missing fields) are implemented by the container system automatically. 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 in session or message-driven beans.

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 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( )and 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 ready 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( ) enables the EJB container to give the bean 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 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 lifecycle, when it is about to be loaded, removed, deactivated, and so on. 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 10.

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. It’s 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 10.

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 ejbLoad( ) or ejbStore( ) methods, because session beans are not persistent. While session beans have a setSessionContext( ) method, they do not have an unsetSessionContext( ) method. Session beans have ejbActivate( ) and ejbPassivate( ) methods, which are used by stateful session beans to manage conversational state. Finally, session beans provide an ejbRemove( ) method, which notifies the bean that the client no longer needs it. However, this method doesn’t tell the bean that its data is about to be removed from the database, because a session bean doesn’t represent data.

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 11.

Message-driven beans (MDBs) implement a message interface; they don’t implement remote, local, endpoint, or home interfaces. The message-driven bean defines a few callback methods and one or more message delivery 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); and the setMessageDrivenContext( ) method. The kind of message delivery methods implemented by the MDB depend on the type of messaging service it supports. For example, a JMS-based MDB, which all EJB containers must support, must implement the onMessage( ) method, which is called every time a new asynchronous JMS message is delivered. The message-driven bean doesn’t define the ejbPassivate( ), ejbActivate( ), ejbLoad( ), or 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 12.

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

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                             http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"
         version="2.1">

    <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 first element in an EJB 2.1 deployment descriptor declares the document to be an XML document conformant with XML Version 1.0, and the character encoding, normally UTF-8.

The root element is the ejb-jar element. It declares the namespace of the EJB 2.1 XML Schema as well as the schema’s location. In addition, the ejb-jar element declares the version of EJB supported, which in the case of EJB 2.1 is version “2.1”.

The following 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>
            <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 first element in an EJB 2.0 deployment descriptor is <!DOCTYPE>. This element describes the organization that defined the DTD for the XML document, supplies the DTD’s version, and provides a URL for the DTD. The DTD describes how a particular XML document is structured.

Now, let’s look more closely at the information in the deployment descriptor. Note that 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 a deployment descriptor. Here’s what the individual elements mean:

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 that have not been covered yet, so don’t worry about knowing all of the elements you might find in a deployment descriptor.

This chapter has said a lot about a bean’s remote and local interfaces, which extend the EJBObject and 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 interfaces of the enterprise bean. The EJB object is generated by your EJB container and 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. This object works with the container to apply transactions, security, and other system-level operations to the bean at runtime.

We’re forced to use “and/or” a lot when talking about which interface the EJB object implements. That’s because enterprise beans in EJB can declare the local interface, the remote interface, or both! In EJB 2.1, stateless session beans can also implement an endpoint interface, which turns it into a Web service. (The endpoint interface and Web services are addressed separately in Chapter 14.) 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 how the vendor chooses to implement it. But that distinction, while it matters to EJB vendors, isn’t visible to EJB developers.

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

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

In Figure 2-1(a), the EJB object class actually extends the bean class, adding functionality specific to the EJB container. In Figure 2-1(b), 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. But 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. But everything 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. The EJB home is responsible for locating, creating, and removing enterprise beans. These tasks may involve working with the EJB server’s resource managers, 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 work with the EJB object by invoking business methods. The stub relays the methods to the EJB object; in turn, the EJB object delegates those method calls to the bean instance.

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 returns a remote interface reference. If the client is working with a local home interface, the EJB home returns a reference implementing the local interface. EJB 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 pk) 
        throws CreateException, RemoteException;
    public CabinRemote findByPrimaryKey(Integer id)
        throws FinderException, RemoteException;
}

// The Cabin EJB's local home interface
public interface CabinHomeLocal extends javax.ejb.EJBLocalHome {
    public CabinLocal create(Integer pk) 
        throws CreateException;
    public CabinLocal findByPrimaryKey(Integer id)
        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. The bean class is wrapped by the EJB object. Remember, though, that this is only an illustration. “EJB object” and “EJB home” are simply terms to describe the EJB container’s responsibilities for supporting the 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.

Figure 2-2. EJB architecture

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.