2.3 Structure of Enterprise Beans

A main goal of the EJB architecture is to free the enterprise application developer from having to deal with the system-level aspects of an application. That allows the bean developer to focus solely on the business aspects of an application.

The bean developer produces the application as a set of enterprise beans. Each enterprise bean consists of the enterprise bean class, the enterprise bean client-view API, and the deployment descriptor.

• The enterprise bean class is a Java class that implements the business methods and the enterprise bean object life-cycle methods. The enterprise bean class may use other helper classes or entire class libraries to implement the business methods.

• The enterprise bean client-view API consists of the enterprise bean home interface, the enterprise bean component interface, and the enterprise bean Web service endpoint interface. The enterprise bean home interface defines the create and remove methods that control the life cycle of the enterprise bean objects, as well as find methods and home methods that perform aggregate operations that are not specific to an individual bean object. The enterprise bean component interface and the Web service interface define the business methods that a client can invoke on the individual enterprise bean objects. The methods in the component and Web service interfaces and the create, find, and home methods in the home interface reflect the needs of each particular bean and thus vary from bean to bean.

  Enterprise beans can now have three types of client views: local, remote, and Web service. The EJB 2.1 specification introduces a local client view for session and entity beans. A session or entity bean not distributed across multiple platforms can benefit from the performance advantages of using a local client view. Such a bean must be located on the same Java virtual machine as its clients. For a local view, the bean defines a local component interface and a local home interface. Colocated enterprise beans can use these local interfaces to make direct, local method calls on the methods of other beans and avoid the remote invocation overhead. It's possible to implement fine-grained access between beans using a local client view. A bean uses a local interface to provide tight coupling with its clients and to use pass-by-reference semantics for parameters of method invocations.

  The EJB architecture retains its support for a remote client view for beans intended for use in a distributed environment. For a remote view, the session or entity bean defines a remote component interface and a remote home interface. An enterprise bean defines a remote client view when its clients may reside in a JVM different from the bean. Each method call on a bean's remote home or component interface results in a remote method invocation, which, although necessary for distributed systems, adds a certain amount of network overhead and performance limitations. The overhead of a remote invocation occurs even if the client and the bean are located on the same JVM. See Section 2.3.1, Local and Remote Client Views, on page 31 for more information.

  EJB 2.1 architects a third type of client view for enterprise beans that are exposed as Web services. This Web service client view consists of a Web service endpoint interface, which is an interface similar to a remote interface. There is no home interface in this Web service client view. Chapter 9 describes the Web service client view in more detail.

  Note that an enterprise bean can have one or more local, remote, or Web service client views. Typically, however, a bean has only one of these views.

• The deployment descriptor is an XML document that contains the declarative information about the enterprise bean. (XML is the Extensible Markup Language, a markup language that lets you define tags to identify data and text in documents.) This information is intended for the enterprise bean consumer: the application assembler and deployer. The deployment descriptor also contains the declaration of the enterprise bean's environment entries. These entries are used for customizing the enterprise bean to the operational environment. The XML deployment descriptor is usually generated by the same tool you use to develop your enterprise beans. The XML document conforms to a schema or grammar that defines the structure of the document and the data types of its elements.

The method names declared in the enterprise bean class correspond to the method names declared in the home, component, and Web service interfaces. A naming convention correlates the method names in the enterprise bean class with the corresponding names in the home, component, and Web service interfaces. See Section 2.3.4, Enterprise Bean Class, on page 38 for more details on this naming convention.

A naming convention is also recommended for the enterprise bean class, Web service interface, component interface, and home interface, although you are not required to adhere to this convention.

• The enterprise bean class name is typically a descriptive name of the business entity or process with the word Bean appended.

• The Web service interface or component interface name, whether remote or local, is simply the business entity name.

• The home interface is the same business entity name with the word Home appended. Because most enterprise beans will not simultaneously have both a remote and a local view, it is sufficient to append Home to the entity name for the home interface. However, if a bean does have a remote and local view, ambiguities can be resolved in two ways.

  • With the EJB 2.0 and 2.1 architectures, most code is developed using local interfaces, and remote interfaces are used less frequently. To keep the code of these tightly coupled beans concise, leave the names of the local interfaces as is, and prepend Remote to the remote home and component interfaces.

  • When migrating from earlier versions of the EJB architecture, particularly if retaining the use of remote interfaces, to resolve ambiguities, the local home interface is the business entity name with LocalHome appended. (The local component interface is the business entity name with Local added to it.) The remote home interface remains the entity name with Home appended.

• The name of the enterprise bean as a whole is the same business entity name with EJB appended.

For example, if you have an Account business entity, you might name the enterprise bean class AccountBean. Following the convention, you would name its home interface AccountHome and the component interface Account. You would refer to the entire enterprise bean as AccountEJB (see Figure 2.3).

Figure 2.3. Enterprise Bean Parts

If the bean implements both a local view and a remote view and if most of your beans use local interfaces, you might name its remote home interface RemoteAccountHome to differentiate it from the local home interface, AccountHome. Similarly, you might name the remote component interface RemoteAccount. Conversely, if you are migrating your beans from earlier EJB architectures, for the same bean you might name its local home interface AccountLocalHome to differentiate it from the remote home interface, AccountHome, and you might name the local interface AccountLocal. Because the client works mostly with the component interface, this convention provides the most natural name for the component interface type.

The AccountHome interface, the enterprise bean home interface, defines the create, find, and remove methods that control the life cycle of the Account objects. The client of an enterprise bean uses these home interface methods to create, find, and remove Account objects.

The Account interface, the enterprise bean component interface, defines the business methods that the client of an enterprise bean can invoke on the individual Account objects.

The AccountBean class, the enterprise bean class, defines the implementation of the life-cycle methods defined in the home interface and the implementation of the business methods defined in the component interface. As noted previously, the bean developer follows a naming convention that ensures a match between the names of the methods of the home and component interfaces and the names of the methods of the enterprise bean class.

The deployment descriptor for the enterprise bean is an XML document. The deployment descriptor specifies the following:

• The enterprise bean name

• The names of the home and component interfaces

• The name of the enterprise bean class

• The enterprise bean type

• Information describing the services, such as transactions, that the enterprise bean expects from its container

• The enterprise bean environment entries, which provide, for example, information about dependencies on other enterprise beans and resource managers

A single deployment descriptor typically provides information about multiple enterprise beans. For enterprise beans that have been assembled into an application, the deployment descriptor also captures the application assembly information.

2.3.1 Local and Remote Client Views

Both session and entity beans can implement local and remote client views. The choice of whether to implement an enterprise bean with a local or a remote client view depends on a number of considerations, most of which apply to both session and entity beans. However, when developing entity beans, you should also consider persistence and relationship handling. Entity beans that are targets of container-managed relationships must use a local client view. Chapter 7 addresses issues specific to entity beans.

Generally, session and entity beans use local interfaces when they are located in the same container as their clients. The EJB 2.1 specification requires that a session or entity bean using a local interface be deployed in the same JVM as the client. When the bean and its clients are guaranteed to be located on the same JVM, there is no need to use a remote interface and incur a remote invocation overhead. (As noted previously, this remote invocation overhead occurs even if the components are located on the same JVM.) However, enterprise beans whose distribution must ensure location independence should continue to use remote interfaces.

Local interfaces also allow a client and a bean to be tightly coupled. Entity beans using local interfaces can, in addition, use fine-grained access to underlying data objects and not suffer performance consequences. An entity bean with a remote interface should be restricted to providing coarse-grained access to underlying data objects.

Parameter-passing mechanisms differ for beans using local or remote interfaces. Use of local interfaces makes it possible to pass parameters between clients and beans by using pass-by-reference semantics. With remote interfaces, on the other hand, parameters are passed between a bean and a client by using pass-by-value semantics. Passing parameters by value prevents the bean from inadvertently modifying the client data, as the bean gets its own copy of the data separate from the client's copy.

Pass-by-reference parameter passing achieves higher performance because it avoids the overhead of object copying. At the same time, because clients and beans share a reference to the same copy of data, care must be taken because variable values may change in unintended ways. Both the client and the bean view and act on the same single copy of the data. Any actions the bean performs on the data affect the client's view of the data. Developers migrating an enterprise bean from a remote interface to a local interface should pay particular attention to the effect that these parameter-passing semantics may have on their application.

Local interfaces provide the EJB and client developers with an easier programming model that is identical to the normal Java class invocation model. Programming with remote interfaces, on the other hand, requires that the developers carefully design their interfaces to take into account the higher performance overheads of remote calls. The remote-client developer also needs to be more careful about handling RemoteExceptions that may occur during the remote call, owing to network problems. Thus remote interfaces result in a more heavyweight programming model based on Java RMI semantics, whereas local interfaces provide a lighter-weight programming model akin to normal Java classes. Table 2.2 summarizes the differences between local and remote client views.

Table 2.2. Comparison of Local and Remote Client Views

Functional Area	Local Client View	Remote Client View
Parameter passing	By reference	By copy
Client colocation requirements	Must be colocated	Can be in different JVM
Invocation overhead	Small	Large
Relationship support	Via entity container-managed relationships	None

2.3.2 Enterprise Bean Home Interfaces

An enterprise bean defines a home interface that corresponds to its client view. As explained earlier, a bean can define a remote client view, a local client view, a Web service client view, or all three. (However, a Web service client view does not define a home interface.)

A bean that implements a remote client view implements a home interface that extends the EJBHome interface. Similarly, a bean that implements a local client view implements a home interface that extends the EJBLocalHome interface. The enterprise bean home interface, whether local or remote, controls the life cycle of the enterprise bean objects, defining the methods that create, find, and remove enterprise bean objects, as well as home methods that perform aggregate operations not specific to a bean instance.

The create, find, and home methods are implemented in the enterprise bean class. The remove methods are inherited from the EJBHome interface if the home interface is for a remote client view or from the EJBLocalHome interface if the home interface is for a local client view.

Code Example 2.1 shows the code for the remote client view AccountHome home interface:

Code Example 2.1 AccountHome Interface

 import java.rmi.RemoteException; import javax.ejb.CreateException; import javax.ejb.FinderException; import java.util.Collection; public interface AccountHome extends javax.ejb.EJBHome {     // create methods     Account create(String lastName, String firstName)        throws RemoteException, CreateException, BadNameException;     Account createBusinessAcct(String businessName)        throws RemoteException, CreateException;     ...     // find methods     Account findByPrimaryKey(AccountKey primaryKey)         throws RemoteException, FinderException;     Collection findInactive(Date sinceWhen)         throws RemoteException, FinderException, BadDateException;     ...     // home methods     public void debitAcctFee(float fee_amt)         throws RemoteException, OutofRangeException;     ... } 

The home interface local or remote may define multiple create and find methods. In the previous example, the AccountHome interface defines two create methods and two find methods. Although the bean developer must name all create methods by beginning with the word create, the name can be followed by a descriptive word. The AccountHome interface defines a create method and a createBusinessAcct method.

In addition, the bean developer can arbitrarily define the type and the number of arguments for the create methods. For example, the AccountHome create method takes two arguments lastName and firstName. The createBusinessAcct method takes only one argument: businessName. These arguments are all String types. Another developer could just as easily have defined a create method to take three arguments: a String type, a Date type, and a Double type. Note that the remote home interface create methods all return the enterprise bean remote interface, which in our example is Account, and throw javax.ejb.CreateException. The local home interface create methods, in contrast, return the enterprise bean local interface.

The names of the find methods always begin with find followed by a descriptive word. The AccountHome interface defines two find methods: findByPrimarykey and findInactive. As with the create methods, the bean developer arbitrarily defines the arguments for the find methods. The find methods return either the enterprise bean remote interface or a collection of such interfaces, and they throw javax.ejb.FinderException. For example, the findInactive method has one argument sinceWhen and returns a Collection of Account remote interfaces. The findByPrimaryKey method has one argument primaryKey and returns one Account remote interface.

Note that the bean developer may define the create and find methods to throw additional application-specific exceptions. In our example, the create method throws BadNameException, and the findInactive method throws BadDateException.

Keep in mind that not all enterprise beans have create and find methods. Session beans do not have find methods. Some entity beans may choose not to define a create method. See Chapter 7, Understanding Entity Beans, for more information on these exceptions.

Both the local and the remote home interfaces may define business methods that work across all bean instances. These methods, called home methods, contain logic that is not specific to a particular bean instance. A bean developer is free to give a home method any name as long as it does not start with create, find, or remove. When it is part of a remote home interface, a home method's arguments and return types must be valid RMI types, and the method must throw RemoteException.

The method can also throw additional application exceptions. For example, AccountHome includes a home method, debitAcctFee, that is run once per month to subtract a monthly maintenance fee from every account. Home methods are applicable only to entity beans; they do not apply to session beans.

Home methods on a local home interface are not constrained by RMI limitations for arguments and return types. Although they do not throw RemoteException, these methods may throw application-specific exceptions.

Remote Home Interface

The remote and local home interfaces share many commonalities but also have some key differences. The remote home interface is a valid remote interface for the Java RMI-IIOP. (RMI-IIOP, a version of RMI implemented to use the CORBA IIOP protocol, provides interoperability with CORBA objects, regardless of their implementation language if all remote interfaces are originally defined as RMI interfaces.) By valid for RMI-IIOP, we mean that the remote home interface methods throw the exception java.rmi.RemoteException and that the arguments and return values for all remote home interface methods are legal types for RMI-IIOP.

Finally, note that every enterprise bean remote home interface extends the javax.ejb.EJBHome interface. The EJBHome interface defines the methods supported by all enterprise bean home interfaces (see Code Example 2.2):

Code Example 2.2 EJBHome Interface

 import java.rmi.RemoteException; public interface EJBHome extends java.rmi.Remote {     void remove(Handle handle)             throws RemoteException, RemoveException;     void remove(Object primaryKey)             throws RemoteException, RemoveException;     EJBMetaData getEJBMetaData() throws RemoteException;     HomeHandle getHomeHandle() throws RemoteException; } 

The EJBHome interface defines two remove methods. The first method removes an enterprise bean object identified by a handle, an object that provides a reference to an enterprise bean object and that can be stored in persistent storage. The second method, which pertains only to entity beans, removes an enterprise bean object identified by a primary key.

The method getEJBMetaData returns the metadata interface for the enterprise bean. Clients that use dynamic invocation that is, clients written using a scripting language use the EJBMetaData interface; its use is not discussed in this book. The getHomeHandle method is used to obtain a handle for the enterprise bean home object. See the section Use of Object Handles on page 118 in Chapter 4 for more information on using session object handles.

Local Home Interface

Every enterprise bean local home interface extends the javax.ejb.EJBLocalHome interface, which defines the one local home interface method: the remove method. A local home interface is not valid for RMI-IIOP; nor do any local home interface methods throw the exception java.rmi.RemoteException. Otherwise, the local home interface follows the same rules as the remote home interface. See Code Example 2.3:

Code Example 2.3 EJBLocalHome Interface

 public interface EJBLocalHome {     void remove(Object primaryKey)        throws RemoveException; } 

2.3.3 Enterprise Bean Component Interface

The enterprise bean component interface defines the business methods that a client can invoke on the individual enterprise bean objects. An enterprise bean may have a local interface and/or a remote interface. For both component interfaces, the bean developer defines the types of the method arguments, the return value type, and the exceptions thrown by the methods.

Enterprise Bean Remote Interface

An enterprise bean may have a remote interface. A remote interface is an RMI interface that can be invoked by clients residing on any machine on the network. Code Example 2.4 shows the Account remote interface:

Code Example 2.4 Account Interface

 import java.rmi.RemoteException; public interface Account extends javax.ejb.EJBObject {     BigDecimal getBalance() throws RemoteException;     void credit(BigDecimal amount) throws RemoteException;     void debit(BigDecimal amount)         throws RemoteException, InsufficientFundsException;     ... } 

Like the remote home interface, the enterprise bean remote interface is a valid remote interface for RMI-IIOP. The bean developer must declare the remote interface methods to throw the exception java.rmi.RemoteException, along with the other exceptions that the methods throw. In addition, the arguments and return values for all remote interface methods must be legal types for RMI-IIOP.

Every enterprise bean remote interface extends the javax.ejb.EJBObject interface, which defines the methods supported by all enterprise bean remote interfaces. Code Example 2.5 shows the code for this interface:

Code Example 2.5 EJBObject Interface

 import java.rmi.RemoteException; public interface EJBObject extends java.rmi.Remote {   public EJBHome getEJBHome() throws RemoteException;   public Object getPrimaryKey() throws RemoteException;   public void remove() throws RemoteException, RemoveException;   public Handle getHandle() throws RemoteException;   boolean isIdentical (EJBObject obj2) throws RemoteException; } 

The method getEJBHome allows the client to get the enterprise bean object's home interface. The getPrimaryKey method pertains only to entity bean remote interfaces and enables a client to get the primary key of the entity object. The remove method deletes the enterprise bean object. The getHandle method returns a handle to the enterprise bean object, whereas the isIdentical method allows the client to determine whether two enterprise bean object references refer to the same enterprise bean object.

Enterprise Bean Local Interface

A bean's local interface defines the business methods that a local client, which is a client residing in the same JVM as the bean instance, may invoke on the individual bean objects. Every enterprise bean local interface extends the javax.ejb.EJBLocalObject interface, which defines the methods supported by all local interfaces. Although it does not throw java.rmi.RemoteException, a local interface may throw an arbitrary number of application-defined exceptions. See Code Example 2.6:

Code Example 2.6 EJBLocalObject Interface

 public interface EJBLocalObject {     public EJBLocalHome getEJBLocalHome();     public Object getPrimaryKey();     public void remove() throws RemoveException;     boolean isIdentical(EJBLocalObject obj); } 

2.3.4 Enterprise Bean Class

The enterprise bean class provides both the implementation of the life-cycle methods defined in the home interface and the implementation of the business methods defined in the component interface. The enterprise bean class also defines the implementation of the container callback methods defined in the javax.ejb.SessionBean, javax.ejb.EntityBean, and javax.ejb.MessageDrivenBean interfaces. Furthermore, an enterprise bean class for an entity bean must provide the implementation for any home methods in its home interface.

A client does not directly invoke methods on the enterprise bean class instances. Rather, the client invokes the methods of the home and component interfaces. The implementation classes of these interfaces delegate to the enterprise bean class instances. Code Example 2.7 shows the AccountBean enterprise bean class:

Code Example 2.7 AccountBean Class

 import java.rmi.RemoteException; public class AccountBean implements javax.ejb.EntityBean {     // life cycle methods from home interface     public AccountKey ejbCreate(String lastName, String firstName)         throws CreateException, BadNameException { ... }     public AccountKey ejbCreateBusinessAcct(String businessName)         throws CreateException { ... }     public void ejbPostCreate(String lastName, firstName)         throws CreateException, BadNameException { ... };     public void ejbPostCreateBusinessAcct(String businessName)         throws CreateException { ... }     public AccountKey ejbFindByPrimaryKey(AccountKey primaryKey)         throws FinderException { ... }     public Collection ejbFindInActive(Date sinceWhen)         throws FinderException, BadDateException { ... }     // business methods from remote interface     public BigDecimal getBalance() { ... }     public void credit(BigDecimal amount) { ... }     public void debit(BigDecimal amount)         throws InsufficientFundsException { ... }     ...     // container callbacks from EntityBean interface     public ejbRemove() throws RemoveException { ... }     public void setEntityContext(EntityContext ec) { ... }     public void unsetEntityContext(EntityContext ec) { ... }     public void ejbActivate() { ... }     public void ejbPassivate() { ... }     public void ejbLoad() { ... }     public void ejbStore() { ... } } 

The enterprise bean class begins by implementing the ejbCreate, ejbPostCreate, and ejbFind methods. These methods correspond to the create and find methods defined in the home interface. In the enterprise bean class, these method names are prefixed with ejb. This naming convention prevents name collisions with the names of the business methods. Chapter 4, Working with Session Beans, and Chapter 7, Understanding Entity Beans, explain how the method arguments, return values, and exceptions of the ejbCreate, ejbPostCreate, and ejbFind methods correspond to the method arguments, return values, and exceptions for the create and find methods defined in the home interface.

Next, the enterprise bean class implements the business methods defined in the component and Web service endpoint interfaces. The business methods implement the business rules for the business entity or process that the enterprise bean represents. Entity beans also provide the implementation for any home methods defined in the home interface. The home method signatures match those in the home interface but include the prefix ejbHome. For example, if an entity bean's home interface included a home method called debitAcctFee, the entity bean's class would implement the corresponding method ejbHomeDebitAcctFee.

Finally, the enterprise bean class implements certain container callback methods. An entity bean class implements the container callbacks defined in the javax.ejb.EntityBean interface. A session bean class implements the callbacks defined in the javax.ejb.SessionBean interface. A message-driven bean implements the callbacks defined in the javax.ejb.MessageDrivenBean interface. The container invokes these callback methods as part of its life-cycle management of an instance.

Note that the javax.ejb.EntityBean interface defines the ejbRemove method. The ejbRemove method corresponds to the remove methods defined in the enterprise bean home and component interfaces.

Why do the parent interfaces define the signatures for the remove and ejbRemove methods, whereas the bean developer defines the create, ejbCreate, ejbPostCreate, find, and ejbFind methods? The reason for this asymmetry is that the signatures of the remove and ejbRemove methods are the same for all enterprise beans. However, the bean developer defines the signatures of the create, ejbCreate, ejbPostCreate, find, and ejbFind methods, and thus they can vary from one bean to another.

Furthermore, you implement an enterprise bean class differently when it is for an entity bean that uses container-managed persistence. The section Container-Managed Persistence on page 178 in Chapter 7 explains these differences.

Implementation of Select Methods

The select methods apply only to entity beans with container-managed persistence. Although select methods are not defined in the bean's component or home interfaces, entity beans provide implementations for these methods in the bean class. These methods are implemented as public, abstract methods whose names have the prefix ejbSelect. The select methods, which must also throw javax.ejb.FinderException, are closely associated to EJB QL queries, in that each select method is associated with a query defined in the deployment descriptor. The select methods can return local objects, and they can return the value of a container-managed persistent field.

Implementing Component Interfaces within the Bean Class

Developers should be careful if implementing a component interface within the enterprise bean class. Note that the AccountBean class in our example does not implement, in the sense of the Java language, the Account interface. The EJB architecture allows the enterprise bean class to implement the enterprise bean's component interface but does not require the enterprise bean class to do so.

If the enterprise bean class implements the component interface, the bean developer must be careful not to pass this inadvertently as a method argument or result. Instead, the bean developer must call the getEJBObject or getEJBLocalObject method on the instance's EntityContext or SessionContext interface. The getEJBObject or getEJBLocalObject method returns an object reference to the associated enterprise bean object. (For more information, see the section Session Object Creation on page 93 in Chapter 4.) This is illustrated in Code Example 2.8:

Code Example 2.8 Obtaining an Object Reference to an Associated Bean Object

 public class AccountBean implements javax.ejb.EntityBean, Account {     ...     public Account returnSelfWrong() {         ...         return this;  // THIS WOULD CAUSE A RUNTIME ERROR     }     public Account returnSelfCorrect() {         ...         return (Account)entityContext.getEJBObject(); // CORRECT     } } 

What could happen with the preceding code? If the AccountBean class implements the Account interface, as Code Example 2.8 illustrates, the programming error is detected at runtime, not at compile time. To put it another way, the application has a programming error that is detected only at runtime, not before.

If the AccountBean class does not implement the Account interface, the Java compiler detects the programming error when compiling the returnSelfWrong method. It is always better to catch errors at compile time rather than at runtime. Therefore, it is recommended that the enterprise bean class not implement the component interface.

The EJB architecture allows the enterprise bean class to implement the component interface so that the EJB architecture can support higher-level business-object frameworks layered on top of itself. The use of such business object frameworks may lead to a situation in which the component interface and the enterprise bean class implement a common application-specific interface. For this reason, the EJB specification does not prohibit the enterprise bean from inheriting the component interface or a superinterface of the component interface.

2.3.5 Deployment Descriptor

The deployment descriptor is an XML document that contains the declarative information about one or more enterprise beans. The deployment descriptor ships with the enterprise beans in an ejb-jar file, a Java archive (JAR) file that contains enterprise beans with their deployment descriptors.

The main role of the deployment descriptor is to define certain bean behavior declaratively rather than programmatically in the bean class. This allows the application assembler or deployer to change how the enterprise bean works, such as its transaction demarcation behavior or its database schema, without modifying the bean's code. The bean developer typically uses application development tools to produce the deployment descriptor. As noted previously, the deployment descriptor describes

• The enterprise bean parts: the home and component interfaces, the enterprise bean class, the Web service interface, and the Web service deployment descriptor

• The services that the enterprise bean expects from its container; for example, transaction demarcation instructions for the enterprise bean methods

• The dependencies that the enterprise bean has on other enterprise beans and resource managers

The deployment descriptor is used by the application assembler and deployer. When assemblying multiple enterprise beans into an application, an application assembler uses tools to read the deployment descriptors of multiple enterprise beans. Using these tools, the application assembler adds information explaining how to assemble the enterprise beans in an application. The application assembler may also describe in the deployment descriptor additional information intended for the deployer, such as the intended security model for the application.

Finally, the deployment tools process the deployment descriptor. For example, the deployment tools tell the deployer about the dependencies on other enterprise beans and resource managers. This serves as a prompt to the deployer to resolve the dependencies. Code Example 2.9 is a fragment of a deployment descriptor:

Code Example 2.9 Deployment Descriptor Fragment

 ... <entity-bean>     <ejb-name>AccountEJB</ejb-name>     <home>com.wombat.AccountHome</home>     <remote>com.wombat.Account</remote>     <ejb-class>com.wombat.AccountBean</ejb-class>     <persistence-type>Bean</persistence-type>     <prim-key-class>com.wombat.AccountKey</prim-key-class>     ... </entity-bean> ... <container-transaction>     <method>         <ejb-name>AccountEJB</ejb-name>         <method-name>*</method-name>     </method>     <trans-attribute>Required</trans-attribute> </container-transaction> ... 

Code Example 2.9 shows only a portion of a typical deployment descriptor and is not meant to be a complete list of all deployment descriptor elements. Rather, it is intended to give you an idea of the information contained in the descriptor. For example, the ejb-name element specifies the name that the bean developer gives to the enterprise bean. The home and remote elements specify the fully qualified names of the enterprise bean home and remote interfaces. (If the bean implemented a local client view, the local element would specify the fully qualified name of the bean's local interface.) The ejb-class element specifies the fully qualified name of the enterprise bean class. The persistence-type element specifies that the enterprise bean uses bean-managed persistence. The prim-key-class element specifies the Java class of the entity bean's primary key. (See Chapter 7, Understanding Entity Beans, for more information on persistence management and entity bean primary keys.) The container-transaction element specifies that the container must invoke the enterprise bean methods in a transaction context.

The deployment descriptor is an XML file and is usually produced by application development tools, although one could create a deployment descriptor by hand, using a text editor. Note that the deployment descriptor is intended to be processed by application assembly and deployment tools, not by humans.