Enterprise JavaBeans 3.1, 6th Edition

Chapter 4. Developing Your First EJBs

Now that we’ve covered the concepts behind the various component models and container services provided by the specification, it’s time to start putting these lessons into practice. In this chapter we’ll introduce the terminology and syntax necessary to code, package, deploy, and test some functional EJBs.

Step 1: Preparation

Let’s briefly lay out some definitions and conventions, and then we’ll get to hacking away.

Definitions

EJBs are composed from the following.

Bean implementation class (session and message-driven beans)

This class, written by the bean provider, contains the business logic for a session or message-driven bean. It is annotated with the appropriate bean type: @javax.ejb.Stateless, @javax.ejb.Stateful, or @javax.ejb.MessageDriven. For instance:

@javax.ejb.Stateless
public class MyFirstBean{...}

is all that’s needed to declare an SLSB.

Bean instance (session and message-driven beans)

The EJB Container internally contains one or more instances of the bean implementation class to service session or message-driven invocations. These are not exposed to the client, but are instead abstracted out by way of the client view. Entity bean instances are POJOs that may be created directly by the client using the new operator.

Client view (session and message-driven beans)

Because clients do not invoke upon bean instances directly, this is the contract with which a client will interact with the EJB. In the case of a session bean, the client view will take the form of a business, component, or endpoint interface—all to be implemented by the EJB Proxy. Message-driven beans have no client view, as they’re received as messaging events, and entity beans also have no explicit view because clients will interact with a managed object directly. At least one view must be defined (either explicitly or implicitly) for an EJB.

EJB Proxy (session beans)

Session bean clients invoke upon the EJB Proxy, which adheres to the contract defined by the client view. Upon EJB deployment, the Container binds all appropriate Proxy objects into a predefined destination in Global JNDI (EJB 3.1 Specification Section 4.4), where a client may look up the reference. From the client’s perspective, the proxy is the EJB, though in actuality the invocation mechanism is a bit more involved (Figure 4-1).

Figure 4-1. The role of the client, container, and bean instance in an EJB invocation

It’s because of the Proxy indirection that the container is able to perform its extensive services outside of the client’s concern.

Local versus remote (session beans)

The terms local and remote, when referring to business, home, or component interfaces, designate the relationship between the process running the client and the JVM running the EJB Container. This is often confused with distribution across physical boundaries. When the client is in-VM, invocations to the local interface are much more efficient than their remote counterpart; they may avoid the networking stack and pass object references instead of serializing values. For instance, EJBs within an application will often communicate with each other by means of a local business interface. The EJB 3.1 Specification details key differences between local, remote, and endpoint views in Section 3.2.

Business interface (session beans)

This is the simplified view, introduced in EJB 3.0, defining business methods that are to be supported by session beans. The business interface is marked as such via an @javax.ejb.Local or @javax.ejb.Remote annotation, depending upon how it’s to be used. However, any one interface may not be both local and remote. The EJB 3.1 Specification defines business interfaces in Section 4.9.7.

Component interface (session beans)

This is the legacy view defined by the EJB 2.x Specification. It has been left in place for backward compatibility with older clients, and it is detailed in EJB 3.1 Section 3.6. The Component interface (also known as the “local” or “remote” interface, contrasted with business interfaces, which are called “business local” or “business remote”) must implement javax.ejb.EJBObject or javax.ejb.EJBLocalObject and will additionally define business methods available to the client. It is obtained via the create<METHOD> methods of the home interface.

Home interface (session beans)

The home interface is used to create, find, and remove session bean references according to the EJB 2.x client contract. Home interfaces extend javax.ejb.EJBHome or javax.ejb.EJBLocalHome and may define methods named with a prefix of “create” to return component interface references. Just like component interfaces, these are legacy and in place to support backward compatibility.

Endpoint interface (session beans)

The endpoint interface defines business methods that can be accessed from applications outside the EJB container via SOAP. The endpoint interface is based on Java API for XML-RPC (JAX-RPC) and is designed to adhere to the SOAP and WSDL standards. The endpoint interface is a plain Java interface that is annotated with the @javax.jws.WebService annotation.

Message interface (MDBs)

Message-driven beans implement the message interface, which defines the methods by which messaging systems, such as the JMS, can deliver messages to the bean. An MDB that listens to JMS events would therefore be defined like this:

@javax.ejb.MessageDriven(activationConfig={...})
public class MyMessageDrivenBean implements javax.jms.MessageListener{...}

Naming Conventions

Before going on, let’s establish some conventions to be used throughout this book. These will be used for clarity; they are not prescriptive or even recommended for use in production. You may use any naming strategy you wish, but it’s suggested that you stick to some predefined standard. There is no law dictating that each of the constructs listed next must be used for your EJBs; in fact, in most cases you’ll use just one or two. The impositions of the EJB 2.x specifications are long gone.

Common business name

To describe an EJB’s function, we’ll assign it a common base from which we may derive other names. This should be descriptive of the business function; therefore, an EJB that handles ticket processing may contain the term TicketProcessor. All other classes that comprise an EJB may then be named according to the following table:

Construct	Suffix	Example
EJB (the sum of its parts)	EJB	TicketProcessorEJB
Bean Implementation Class	Bean	TicketProcessorBean
Remote Business Interface	RemoteBusiness	TicketProcessorRemoteBusiness
Local Business Interface	LocalBusiness	TicketProcessorLocalBusiness
Remote Home Interface	RemoteHome	TicketProcessorRemoteHome
Local Home Interface	LocalHome	TicketProcessorLocalHome
Remote Component Interface	Remote	TicketProcessorRemote
Local Component Interface	Local	TicketProcessorLocal
Endpoint Interface	WS (for WebService)	TicketProcessorWS

Conventions for the Examples

To maintain consistency, this text will adhere to the following conventions unless explicitly specified.

Vendor-agnostic

All examples covered in Parts I through IV of this book will address syntax and concepts dictated by the EJB Specification only. As the EJB deployment mechanism is not covered by spec, these examples will not run unless bolstered by some additional instructions or metadata. To this end, each example will have a deployable counterpart in Part V, which is written to work specifically with the open source JBoss Application Server. The focus of the code fragments in this text may be intentionally incomplete to promote brevity, and they are in place primarily to illustrate concepts. Part V will serve as the real practice grounds for getting your hands dirty. You may want to flip back and forth between the lessons and their corresponding examples as you progress.

No XML

Generally speaking, EJB metadata may be supplied either by a standard XML descriptor (ejb-jar.xml), Java annotations, or some combination of the two. In cases where there’s overlap, XML wins as an override. In order to cut down on the verbosity of our examples, we’ll opt for annotations wherever possible. The corresponding XML syntax is available for reference by consulting the appropriate Document Type Definition (DTD) or schema.

Annotations on the bean implementation class

Many class-level annotations may be applied in a variety of locations. For instance, a remote business interface may be marked on the interface itself:

@javax.ejb.Remote
public interface SomeBusinessRemote{...}

Instead, we’ll be declaring annotations upon the bean implementation class:

@javax.ejb.Stateless
@javax.ejb.Remote(SomeBusinessRemote.class)
public class SomeBean implements SomeBusinessRemote{...}

This means that a quick glance will reveal all metadata for the bean in question, and we’ll minimize poking through various files to get the full picture.