JavaEETutorial.

book Page 743 Thursday, February 1, 2007 4:36 PM

20
Enterprise Beans

ENTERPRISE beans are Java EE components that implement Enterprise

JavaBeans (EJB) technology. Enterprise beans run in the EJB container, a run-
time environment within the Application Server (see Container Types, page 10).
Although transparent to the application developer, the EJB container provides
system-level services such as transactions and security to its enterprise beans.
These services enable you to quickly build and deploy enterprise beans, which
form the core of transactional Java EE applications.

What Is an Enterprise Bean?

Written in the Java programming language, an enterprise bean is a server-side
component that encapsulates the business logic of an application. The business
logic is the code that fulfills the purpose of the application. In an inventory con-
trol application, for example, the enterprise beans might implement the business
logic in methods called checkInventoryLevel and orderProduct. By invoking
these methods, clients can access the inventory services provided by the applica-
tion.

Benefits of Enterprise Beans

For several reasons, enterprise beans simplify the development of large, distrib-
uted applications. First, because the EJB container provides system-level ser-
vices to enterprise beans, the bean developer can concentrate on solving business

743
JavaEETutorial.book Page 744 Thursday, February 1, 2007 4:36 PM

744 ENTERPRISE BEANS

problems. The EJB container—and not the bean developer—is responsible for
system-level services such as transaction management and security authoriza-
tion.
Second, because the beans—and not the clients—contain the application’s busi-
ness logic, the client developer can focus on the presentation of the client. The
client developer does not have to code the routines that implement business rules
or access databases. As a result, the clients are thinner, a benefit that is particu-
larly important for clients that run on small devices.
Third, because enterprise beans are portable components, the application assem-
bler can build new applications from existing beans. These applications can run
on any compliant Java EE server provided that they use the standard APIs.

When to Use Enterprise Beans

You should consider using enterprise beans if your application has any of the fol-
lowing requirements:
• The application must be scalable. To accommodate a growing number of
users, you may need to distribute an application’s components across mul-
tiple machines. Not only can the enterprise beans of an application run on
different machines, but also their location will remain transparent to the
clients.
• Transactions must ensure data integrity. Enterprise beans support transac-
tions, the mechanisms that manage the concurrent access of shared objects.
• The application will have a variety of clients. With only a few lines of code,
remote clients can easily locate enterprise beans. These clients can be thin,
various, and numerous.
JavaEETutorial.book Page 745 Thursday, February 1, 2007 4:36 PM

WHAT IS A SESSION BEAN? 745

Types of Enterprise Beans

Table 20–1 summarizes the two types of enterprise beans. The following sec-
tions discuss each type in more detail.

Table 20–1 Enterprise Bean Types

Enterprise Bean Type Purpose

Performs a task for a client; optionally may implement a web ser-

Session
vice

Acts as a listener for a particular messaging type, such as the Java

Message-Driven
Message Service API

Note: Entity beans have been replaced by Java Persistence API entities. For infor-
mation about entities, see Chapter 24, Introduction to the Java Persistence API.

What Is a Session Bean?

A session bean represents a single client inside the Application Server. To access
an application that is deployed on the server, the client invokes the session bean’s
methods. The session bean performs work for its client, shielding the client from
complexity by executing business tasks inside the server.
As its name suggests, a session bean is similar to an interactive session. A ses-
sion bean is not shared; it can have only one client, in the same way that an inter-
active session can have only one user. Like an interactive session, a session bean
is not persistent. (That is, its data is not saved to a database.) When the client ter-
minates, its session bean appears to terminate and is no longer associated with
the client.
For code samples, see Chapter 22.

State Management Modes

There are two types of session beans: stateful and stateless.
JavaEETutorial.book Page 746 Thursday, February 1, 2007 4:36 PM

746 ENTERPRISE BEANS

Stateful Session Beans

The state of an object consists of the values of its instance variables. In a stateful
session bean, the instance variables represent the state of a unique client-bean
session. Because the client interacts (“talks”) with its bean, this state is often
called the conversational state.
The state is retained for the duration of the client-bean session. If the client
removes the bean or terminates, the session ends and the state disappears. This
transient nature of the state is not a problem, however, because when the conver-
sation between the client and the bean ends there is no need to retain the state.

Stateless Session Beans

A stateless session bean does not maintain a conversational state with the client.
When a client invokes the methods of a stateless bean, the bean’s instance vari-
ables may contain a state specific to that client, but only for the duration of the
invocation. When the method is finished, the client-specific state should not be
retained. Clients may, however, change the state of instance variables in pooled
stateless beans, and this state is held over to the next invocation of the pooled
stateless bean. Except during method invocation, all instances of a stateless bean
are equivalent, allowing the EJB container to assign an instance to any client.
That is, the state of a stateless session bean should apply accross all clients.
Because stateless session beans can support multiple clients, they can offer better
scalability for applications that require large numbers of clients. Typically, an
application requires fewer stateless session beans than stateful session beans to
support the same number of clients.
A stateless session bean can implement a web service, but other types of enter-
prise beans cannot.

When to Use Session Beans

In general, you should use a session bean if the following circumstances hold:
• At any given time, only one client has access to the bean instance.
• The state of the bean is not persistent, existing only for a short period (per-
haps a few hours).
• The bean implements a web service.
JavaEETutorial.book Page 747 Thursday, February 1, 2007 4:36 PM

WHAT IS A MESSAGE-DRIVEN BEAN? 747

Stateful session beans are appropriate if any of the following conditions are true:
• The bean’s state represents the interaction between the bean and a specific
client.
• The bean needs to hold information about the client across method invoca-
tions.
• The bean mediates between the client and the other components of the
application, presenting a simplified view to the client.
• Behind the scenes, the bean manages the work flow of several enterprise
beans. For an example, see the AccountControllerBean session bean in
Chapter 37.
To improve performance, you might choose a stateless session bean if it has any
of these traits:
• The bean’s state has no data for a specific client.
• In a single method invocation, the bean performs a generic task for all cli-
ents. For example, you might use a stateless session bean to send an email
that confirms an online order.

What Is a Message-Driven Bean?

A message-driven bean is an enterprise bean that allows Java EE applications to
process messages asynchronously. It normally acts as a JMS message listener,
which is similar to an event listener except that it receives JMS messages instead
of events. The messages can be sent by any Java EE component—an application
client, another enterprise bean, or a web component—or by a JMS application or
system that does not use Java EE technology. Message-driven beans can process
JMS messages or other kinds of messages.
For a simple code sample, see Chapter 23. For more information about using
message-driven beans, see Using the JMS API in a Java EE Application
(page 1119) and Chapter 32.

What Makes Message-Driven Beans

Different from Session Beans?
The most visible difference between message-driven beans and session beans is
that clients do not access message-driven beans through interfaces. Interfaces are
JavaEETutorial.book Page 748 Thursday, February 1, 2007 4:36 PM

748 ENTERPRISE BEANS

described in the section Defining Client Access with Interfaces (page 749).
Unlike a session bean, a message-driven bean has only a bean class.
In several respects, a message-driven bean resembles a stateless session bean.
• A message-driven bean’s instances retain no data or conversational state
for a specific client.
• All instances of a message-driven bean are equivalent, allowing the EJB
container to assign a message to any message-driven bean instance. The
container can pool these instances to allow streams of messages to be pro-
cessed concurrently.
• A single message-driven bean can process messages from multiple clients.
The instance variables of the message-driven bean instance can contain some
state across the handling of client messages—for example, a JMS API connec-
tion, an open database connection, or an object reference to an enterprise bean
object.
Client components do not locate message-driven beans and invoke methods
directly on them. Instead, a client accesses a message-driven bean through, for
example, JMS by sending messages to the message destination for which the
message-driven bean class is the MessageListener. You assign a message-
driven bean’s destination during deployment by using Application Server
resources.
Message-driven beans have the following characteristics:
• They execute upon receipt of a single client message.
• They are invoked asynchronously.
• They are relatively short-lived.
• They do not represent directly shared data in the database, but they can
access and update this data.
• They can be transaction-aware.
• They are stateless.
When a message arrives, the container calls the message-driven bean’s
onMessage method to process the message. The onMessage method normally
casts the message to one of the five JMS message types and handles it in accor-
dance with the application’s business logic. The onMessage method can call
helper methods, or it can invoke a session bean to process the information in the
message or to store it in a database.
JavaEETutorial.book Page 749 Thursday, February 1, 2007 4:36 PM

DEFINING CLIENT ACCESS WITH INTERFACES 749

A message can be delivered to a message-driven bean within a transaction con-

text, so all operations within the onMessage method are part of a single transac-
tion. If message processing is rolled back, the message will be redelivered. For
more information, see Chapter 23.

When to Use Message-Driven Beans

Session beans allow you to send JMS messages and to receive them synchro-
nously, but not asynchronously. To avoid tying up server resources, do not to use
blocking synchronous receives in a server-side component, and in general JMS
messages should not be sent or received synchronously. To receive messages
asynchronously, use a message-driven bean.

Defining Client Access with Interfaces

The material in this section applies only to session beans and not to message-
driven beans. Because they have a different programming model, message-
driven beans do not have interfaces that define client access.
A client can access a session bean only through the methods defined in the
bean’s business interface. The business interface defines the client’s view of a
bean. All other aspects of the bean—method implementations and deployment
settings—are hidden from the client.
Well-designed interfaces simplify the development and maintenance of Java EE
applications. Not only do clean interfaces shield the clients from any complexi-
ties in the EJB tier, but they also allow the beans to change internally without
affecting the clients. For example, if you change a session bean from a stateless
to a stateful session bean, you won’t have to alter the client code. But if you were
to change the method definitions in the interfaces, then you might have to mod-
ify the client code as well. Therefore, it is important that you design the inter-
faces carefully to isolate your clients from possible changes in the beans.
Session beans can have more than one business interface. Session beans should,
but are not required to, implement their business interface or interfaces.
When you design a Java EE application, one of the first decisions you make is
the type of client access allowed by the enterprise beans: remote, local, or web
service.
JavaEETutorial.book Page 750 Thursday, February 1, 2007 4:36 PM

750 ENTERPRISE BEANS

Remote Clients
A remote client of an enterprise bean has the following traits:
• It can run on a different machine and a different Java virtual machine
(JVM) than the enterprise bean it accesses. (It is not required to run on a
different JVM.)
• It can be a web component, an application client, or another enterprise
bean.
• To a remote client, the location of the enterprise bean is transparent.
To create an enterprise bean that allows remote access, you must do one of the
following:
• Decorate the business interface of the enterprise bean with the @Remote
annotation:
@Remote
public interface InterfaceName {
...
}
• Decorate the bean class with @Remote, specifying the business interface(s):
@Remote(InterfaceName.class)
public class BeanName implements InterfaceName {
...
}
The remote interface defines the business and life cycle methods that are specific
to the bean. For example, the remote interface of a bean named BankAccount-
Bean might have business methods named deposit and credit. Figure 20–1
shows how the interface controls the client’s view of an enterprise bean.

BankAccountBean
Remote Client Remote
Interface

deposit()
credit()

Figure 20–1 Interfaces for an Enterprise Bean with Remote Access

JavaEETutorial.book Page 751 Thursday, February 1, 2007 4:36 PM

DEFINING CLIENT ACCESS WITH INTERFACES 751

Local Clients
A local client has these characteristics:
• It must run in the same JVM as the enterprise bean it accesses.
• It can be a web component or another enterprise bean.
• To the local client, the location of the enterprise bean it accesses is not
transparent.
The local business interface defines the bean’s business and life cycle methods.
If the bean’s business interface is not decorated with @Local or @Remote, and the
bean class does not specify the interface using @Local or @Remote, the business
interface is by default a local interface. To build an enterprise bean that allows
only local access, you may, but are not required to do one of the following:
• Annotate the business interface of the enterprise bean as a @Local inter-
face. For example:
@Local
public interface InterfaceName {
...
}
• Specify the interface by decorating the bean class with @Local and specify
the interface name. For example:
@Local(InterfaceName.class)
public class BeanName implements InterfaceName {
...
}

Deciding on Remote or Local Access

Whether to allow local or remote access depends on the following factors.
• Tight or loose coupling of related beans: Tightly coupled beans depend on
one another. For example, if a session bean that processes sales orders calls
a session bean that emails a confirmation message to the customer, these
beans are tightly coupled. Tightly coupled beans are good candidates for
local access. Because they fit together as a logical unit, they typically call
each other often and would benefit from the increased performance that is
possible with local access.
• Type of client: If an enterprise bean is accessed by application clients, then
it should allow remote access. In a production environment, these clients
JavaEETutorial.book Page 752 Thursday, February 1, 2007 4:36 PM

752 ENTERPRISE BEANS

almost always run on different machines than the Application Server. If an

enterprise bean’s clients are web components or other enterprise beans,
then the type of access depends on how you want to distribute your com-
ponents.
• Component distribution: Java EE applications are scalable because their
server-side components can be distributed across multiple machines. In a
distributed application, for example, the web components may run on a
different server than do the enterprise beans they access. In this distributed
scenario, the enterprise beans should allow remote access.
• Performance: Due to factors such as network latency, remote calls may be
slower than local calls. On the other hand, if you distribute components
among different servers, you may improve the application’s overall perfor-
mance. Both of these statements are generalizations; actual performance
can vary in different operational environments. Nevertheless, you should
keep in mind how your application design might affect performance.
If you aren’t sure which type of access an enterprise bean should have, choose
remote access. This decision gives you more flexibility. In the future you can dis-
tribute your components to accommodate the growing demands on your applica-
tion.
Although it is uncommon, it is possible for an enterprise bean to allow both
remote and local access. If this is the case, either the business interface of the
bean must be explicitly designated as a business interface by being decorated
with the @Remote or @Local annotations, or the bean class must explicitly desig-
nate the business interfaces by using the @Remote and @Local annotations. The
same business interface cannot be both a local and remote business interface.

Web Service Clients

A web service client can access a Java EE application in two ways. First, the cli-
ent can access a web service created with JAX-WS. (For more information on
JAX-WS, see Chapter 15, Building Web Services with JAX-WS, page 507.) Sec-
ond, a web service client can invoke the business methods of a stateless session
bean. Message beans cannot be accessed by web service clients.
Provided that it uses the correct protocols (SOAP, HTTP, WSDL), any web ser-
vice client can access a stateless session bean, whether or not the client is written
in the Java programming language. The client doesn’t even “know” what tech-
nology implements the service—stateless session bean, JAX-WS, or some other
technology. In addition, enterprise beans and web components can be clients of
JavaEETutorial.book Page 753 Thursday, February 1, 2007 4:36 PM

DEFINING CLIENT ACCESS WITH INTERFACES 753

web services. This flexibility enables you to integrate Java EE applications with
web services.
A web service client accesses a stateless session bean through the bean’s web
service endpoint implementation class. By default, all public methods in the
bean class are accessible to web service clients. The @WebMethod annotation may
be used to customize the behavior of web service methods. If the @WebMethod
annotation is used to decorate the bean class’s methods, only those methods dec-
orated with @WebMethod are exposed to web service clients.
For a code sample, see A Web Service Example: helloservice (page 780).

Method Parameters and Access

The type of access affects the parameters of the bean methods that are called by
clients. The following topics apply not only to method parameters but also to
method return values.

Isolation
The parameters of remote calls are more isolated than those of local calls. With
remote calls, the client and bean operate on different copies of a parameter
object. If the client changes the value of the object, the value of the copy in the
bean does not change. This layer of isolation can help protect the bean if the cli-
ent accidentally modifies the data.
In a local call, both the client and the bean can modify the same parameter
object. In general, you should not rely on this side effect of local calls. Perhaps
someday you will want to distribute your components, replacing the local calls
with remote ones.
As with remote clients, web service clients operate on different copies of param-
eters than does the bean that implements the web service.

Granularity of Accessed Data

Because remote calls are likely to be slower than local calls, the parameters in
remote methods should be relatively coarse-grained. A coarse-grained object
contains more data than a fine-grained one, so fewer access calls are required.
For the same reason, the parameters of the methods called by web service clients
should also be coarse-grained.
JavaEETutorial.book Page 754 Thursday, February 1, 2007 4:36 PM

754 ENTERPRISE BEANS

The Contents of an Enterprise Bean

To develop an enterprise bean, you must provide the following files:
• Enterprise bean class: Implements the methods defined in the business
interface and any life cycle callback methods.
• Business Interfaces: The business interface defines the methods imple-
mented by the enterprise bean class.
• Helper classes: Other classes needed by the enterprise bean class, such as
exception and utility classes.
You package the files in the preceding list into an EJB JAR file, the module that
stores the enterprise bean. An EJB JAR file is portable and can be used for differ-
ent applications. To assemble a Java EE application, you package one or more
modules—such as EJB JAR files—into an EAR file, the archive file that holds
the application. When you deploy the EAR file that contains the bean’s EJB JAR
file, you also deploy the enterprise bean to the Application Server. You can also
deploy an EJB JAR that is not contained in an EAR file. Figure 20–2 shows the
contents of an EJB JAR file.

Assembly
Root

META-INF

All .class files

for this module

ejb-jar.xml
sun-ejb-jar.xml MANIFEST.MF

Figure 20–2 Structure of an Enterprise Bean JAR

JavaEETutorial.book Page 755 Thursday, February 1, 2007 4:36 PM

THE LIFE CYCLES OF ENTERPRISE BEANS 755

Naming Conventions for Enterprise

Beans
Because enterprise beans are composed of multiple parts, it’s useful to follow a
naming convention for your applications. Table 20–2 summarizes the conven-
tions for the example beans in this tutorial.

Table 20–2 Naming Conventions for Enterprise Beans

Item Syntax Example

Enterprise bean name <name>Bean AccountBean

Enterprise bean class <name>Bean AccountBean

Business interface <name> Account

The Life Cycles of Enterprise Beans

An enterprise bean goes through various stages during its lifetime, or life cycle.
Each type of enterprise bean—stateful session, stateless session, or message-
driven—has a different life cycle.
The descriptions that follow refer to methods that are explained along with the
code examples in the next two chapters. If you are new to enterprise beans, you
should skip this section and run the code examples first.

The Life Cycle of a Stateful Session Bean

Figure 20–3 illustrates the stages that a session bean passes through during its
lifetime. The client initiates the life cycle by obtaining a reference to a stateful
session bean. The container performs any dependency injection and then invokes
the method annotated with @PostConstruct, if any. The bean is now ready to
have its business methods invoked by the client.
JavaEETutorial.book Page 756 Thursday, February 1, 2007 4:36 PM

756 ENTERPRISE BEANS

Does Not
Exist
Timeout
1. Remove method
or Timeout
1. Dependency injection, 2. PreDestroy callbacks,
if any if any
2. PostConstruct callbacks,
if any PrePassivate
callbacks, if any

Ready Passive
PostActivate
callbacks, if any

Figure 20–3 Life Cycle of a Stateful Session Bean

While in the ready stage, the EJB container may decide to deactivate, or passi-
vate, the bean by moving it from memory to secondary storage. (Typically, the
EJB container uses a least-recently-used algorithm to select a bean for passiva-
tion.) The EJB container invokes the method annotated @PrePassivate, if any,
immediately before passivating it. If a client invokes a business method on the
bean while it is in the passive stage, the EJB container activates the bean, calls
the method annotated @PostActivate, if any, and then moves it to the ready
stage.
At the end of the life cycle, the client invokes a method annotated @Remove, and
the EJB container calls the method annotated @PreDestroy, if any. The bean’s
instance is then ready for garbage collection.
Your code controls the invocation of only one life-cycle method: the method
annotated @Remove. All other methods in Figure 20–3 are invoked by the EJB
container. See Chapter 34 for more information.

The Life Cycle of a Stateless

Session Bean
Because a stateless session bean is never passivated, its life cycle has only two
stages: nonexistent and ready for the invocation of business methods. Figure 20–
4 illustrates the stages of a stateless session bean.
JavaEETutorial.book Page 757 Thursday, February 1, 2007 4:36 PM

THE LIFE CYCLES OF ENTERPRISE BEANS 757

1. Dependency injection, if any

2. PostConstruct callbacks, if any

Does Not
Exist Ready

PreDestroy callbacks, if any

Figure 20–4 Life Cycle of a Stateless Session Bean

The client initiates the life cycle by obtaining a reference to a stateless session
bean. The container performs any dependency injection and then invokes the
method annotated @PostConstruct, if any. The bean is now ready to have its
business methods invoked by the client.
At the end of the life cycle, the EJB container calls the method annotated @Pre-
Destroy, if any. The bean’s instance is then ready for garbage collection.

The Life Cycle of a

Message-Driven Bean
Figure 20–5 illustrates the stages in the life cycle of a message-driven bean.
The EJB container usually creates a pool of message-driven bean instances. For
each instance, the EJB container performs these tasks:
1. If the message-driven bean uses dependency injection, the container
injects these references before instantiating the instance.
2. The container calls the method annotated @PostConstruct, if any.

1. Dependency injection, if any

2. PostConstruct callback, if any

Does Not onMessage Ready

Exist

PreDestroy callback, if any

Figure 20–5 Life Cycle of a Message-Driven Bean

JavaEETutorial.book Page 758 Thursday, February 1, 2007 4:36 PM

758 ENTERPRISE BEANS

Like a stateless session bean, a message-driven bean is never passivated, and it

has only two states: nonexistent and ready to receive messages.
At the end of the life cycle, the container calls the method annotated
@PreDestroy, if any. The bean’s instance is then ready for garbage collection.

Further Information
For further information on Enterprise JavaBeans technology, see the following:
• Enterprise JavaBeans 3.0 specification:
http://java.sun.com/products/ejb/docs.html

• The Enterprise JavaBeans web site:

http://java.sun.com/products/ejb