With these characteristics in mind, let’s start out by identifying entity beans in our application.

Our class diagram was created from the list of business entities in our functional analysis, which are essentially the things in our functional requirements. We know right away that the components in the diagram are all candidates for implementation as entity beans. However, not all of them should be implemented as entity beans. Entities that are read-only may be best implemented using one of the EJB alternatives, such as JDBC or JDO. Read-only entity beans can take advantage of caching and other vendor-specific optimizations that your container may offer, but they really don’t need the transaction enforcement that EJB provides.

Other factors to bear in mind when making this decision are your team’s skill set, the performance ramifications of the options, and the relative amount of functionality implemented in the options.

You should also avoid logical inheritance with entity beans, in which one entity bean, Customer, is a subclass of another entity bean, Person, and could be cast to the parent’s type. While inheritance works all right for sharing common EJB implementation code between different EJBs (see the “Base and Utility Classes” section below), never try to implement logical inheritance with entity beans. The most important reason to avoid logical inheritance derives from the fact that entity beans correspond to rows in a database table, and inheritance, as an object-oriented concept, is foreign to the database world. You can’t define tables CUSTOMER and TRAVEL_AGENT to inherit the attributes of a third PERSON table. Moving back to our entity beans, our best option is to remove the inheritance relationship and replace it with a composition relationship, which is functionally equivalent. Which brings us to the next guideline.

Figure 19-4. Updated class diagram

While entity beans are the things in our application, session beans implement taskflow. They are the processors and workhorses; they do stuff. We will identify them by considering the work that our application must do, and a good starting place is the responsibilities depicted in the class diagram.

Looking over the class diagram, we see TravelAgent has the following responsibilities:

In any application, functionality seems to clump around one or more entities. Such a grouping of responsibilities often indicates that a session bean is needed. And this gives us the next guideline.

As for the name for the session bean, a good way to think of it is to create a name that reflects a combination of the target of the action and the action itself. For example, the TravelAgent creates and updates or “manages” Reservations, so a good name for our session bean might be ReservationManager. The primary objective of the name is to communicate what the session bean does. As the session bean encapsulates the responsibilities, each responsibility corresponds to a method in the EJB. So, our ReservationManager session bean will initially have three methods: bookReservation, updateReservation, and cancelReservation. These names are also named intuitively, to suggest what they do.

If we follow this line of reasoning, we may think we need to have a separate session bean called a CruiseManager. However, the only interaction the TravelAgent has with a Cruise is to list it. Furthermore, it could be argued that in the overwhelming majority of the cases, the TravelAgent will only list Cruises when making a Reservation. For these reasons, it might make more sense to combine the Cruise functionality and simply add a new listCruises method to the ReservationManager.

The listCruises method stands apart from the other methods a bit, both in effect (it reads data while the other methods write data) and in direct object (it returns a collection of cruises while the other methods manipulate a single reservation).This suggests Guideline #4.

We have now accounted for all the responsibilities depicted in the class diagram, but we haven’t accounted for all the functionality specified in the functional requirements. Creating the initial class diagram from the business entities initially misses functionality that has no “source” entity. For example, we’ve focused only on the reservations and the actions and entities around them. However, a reservation involves a Cruise that has certain characteristics. Some part of our application must be available to administer these Cruises. Cruises are made up of Cabins and Ships. Our administration functionality should focus on the management of all three entities: Cruise, Ship, and Cabin.

Our application revolves around travel agency functionality, but without the configuration of the cruises themselves, the travel agency functionality (creation of reservations, and so on) would be meaningless. Let’s add a general session bean around this and other (to be determined) configuration chores. While we may need to break this into multiple session beans later, we can start with one called ConfigurationManager.

Here too, we want to give it methods based on the functionality it encapsulates. Since no taskflows are detailed above, we will assume that all three items need to be created, updated, and deactivated. Thus, these actions (for the three entities) become nine initial methods:

We can now expand our entity diagram into the class diagram of Figure 19-5.

Figure 19-5. Entity diagram expanded into a class diagram

Now we need to look for the message-driven beans in the application. As our review of the EJB types reminds us, message-driven beans (MDBs) implement taskflows like session beans but can be invoked asynchronously. Roughly put, they are transactional message handlers.^[61]

Here’s where our system architecture diagram helps us. There are two places where messaging takes place between our system and another (ostensibly external) system:

As you can see from our functional requirements and the technical architecture diagram, our system receives messages only from external travel agencies, so we’ll focus on the travel agent functionality.

Since we’ve not been told anything to the contrary, we assume that external travel agent systems function like ours. Thus, ours should include all the functionality incorporated into ReservationManager. Additionally, the external travel agencies need some way to retrieve a list of ships and their cabins. This listing ability is included because the external travel agency systems can only communicate via messaging. This suggests that one or more MDBs could be used to implement this functionality.

For the Titan application, we will have two MDBs:

Compare the responsibilities of ReservationListener with those of ReservationManager. The cruise-listing behavior and the reservation-specific behavior are implemented in separate MDBs. Why? Guideline #4 tells us that if we are only going to execute a given piece of functionality in the context of a given process, we should combine that function with the others. This guideline is appropriate for session beans. To add another method to a session bean does not introduce any complexity to the bean. It’s just another method. However, in JMS-based MDB, you have only one onMessage function. While you can certainly have many different types of messages coming into the queue on which the MDB is listening, each message type must be processed separately. Each message type adds another significant condition to the MDB’s processing logic. Furthermore, the functionality represented by the various messages for the ReservationListener will be largely the same, but messages representing queries for cruise information might be different.

While we’re talking about JMS-based MDB, it makes sense to discuss the importance of message design. When a message listener is invoked, the only information it has is the message that it has been passed. In many cases, the message listener needs specific business information to do its work, and that information is packaged in the message.

Exactly how it is packaged depends on which message type you choose: javax.jms.Message or its subinterfaces (BytesMessage , MapMessage , ObjectMessage , StreamMessage , and TextMessage ). A general rule of thumb is to use ObjectMessage for messaging between systems that are guaranteed to be Java-based and to use TextMessage for messaging between potentially non-Java systems. Because ObjectMessage carries a full Java object, the data inside it is already structured for easy access by the MDB, whereas all but the simplest data embedded in a TextMessage (and the other types to varying extents) will generally have to be processed before it can be used (by a StringTokenizer, an XML parser, Integer.parseInt, or something similar).

On the upside, TextMessage (and maybe BytesMessage) is the most universal message type—every messaging system knows how to send and receive simple text (and also binary data). That said, you should investigate message types and their trade-offs before making final decisions.

Because we need to accept messages from the greatest variety of external travel agency systems, we will use TextMessage messages carrying XML payloads. While it requires a heavy XML parser when processing messages, it provides interoperability benefits that fit our needs.

We’ve now identified all of the EJBs in our sample application. Figure 19-6 is an updated class diagram.

Figure 19-6. Updated class diagram

As their names indicate, the difference between the two sub-types of session beans is the maintenance of state. A common source of confusion is that we use similar words when we talk about web session state, as with servlets and other aspects of web-based applications. Session bean state is taskflow-related and should have little or no relation to the web or presentation tiers of your application. Session bean state is a way of sharing information between multiple methods of the same session bean. For example, the stateful version of ReservationManager contains the current Customer, so that it is not passed into the bookReservation, updateReservation, and cancelReservation methods (Figure 19-7).

Figure 19-7. Stateful version of ReservationManager

Contrast that with the stateless version of ReservationManager, in which the current Customer is a parameter for those methods (Figure 19-8).

Figure 19-8. Stateless version of ReservationManager

The stateful session bean appears more elegant when we need to call bookReservation, updateReservation, or cancelReservation multiple times. However, that elegance has a cost. Stateful session beans are slower and more resource intensive than stateless session beans. This makes the choice of stateful session beans a trade-off rather than a pure benefit.

Perhaps you’re thinking, “That’s a pretty balanced trade-off.” Unfortunately, stateful session beans are not as useful as they first appear. Remember that stateful session beans share information between multiple methods of the same session bean. But the methods in the session bean’s interface are coarse-grained enough that the application should only be calling one at any given time. Why would your code call bookReservation and then cancelReservation?

In our example, we wouldn’t. However, you will encounter situations where you will need to execute multiple methods on the same EJB. In that case, you should apply the Session Façade design pattern.^[62] In essence, the Session Façade pattern manages a taskflow, and it can manage information just as a stateful session bean does. Even better, it offers the same transaction and security management between multiple EJBs. Thus, stateless session beans with the Session Façade pattern are preferable to stateful session beans.

The decision to use containter-managed or bean-managed persistence for an entity bean determines the bean’s persistence mechanism, affecting the bean’s implementation. BMP beans must implement their data access, while CMP beans are implemented by the container. BMP offers greater flexibility in the datastores your application can use and how your application integrates with them. CMP beans can only use datastores that the container knows about, usually those with JDBC drivers. The flexibility of BMP can be essential if you need to integrate with external systems, making a good match with the Java Connector Architecture. BMP is also an option with entity beans that require complex data operations, such as those spanning multiple datastores or multiple tables in one datastore.

However, this heightened flexibility has a cost: you must develop data access functionality yourself, rather than depending on the container. This means that BMP beans require more effort to develop and maintain. CMP beans are virtually guaranteed to integrate flawlessly with the container, while BMP beans may contain code that is not EJB safe. BMP beans that integrate with external systems should hide the operational and semantic differences between EJB and the external system’s technology. Otherwise, the external system may cause all kinds of potentially serious side effects, some subtle and unpredictable. Also, BMP code may not be portable—which makes sense for code that is specifically written for complex data operations or integration with external systems.

CMP beans don’t have these issues. Here are some considerations about CMP:

Don’t use BMP beans unless the requirements supporting them are strong and clear-cut. If you are using BMP beans to integrate with external datastores, locate or create as much documentation as possible.

Don’t use remote interfaces unless you really have to: it can’t be emphasized enough. Distributing your EJBs adds a whole layer of complication that is often unnecessary. There are the basic, only somewhat irritating issues, such as handling RemoteExceptions in your client code, and there are the complex, intractable issues, such as loss of performance and reliability when your components must operate across a network. One big complication is that remote interfaces (and the implementation they present) are often difficult to change, because the remote interface will be used by other systems or applications that may be resistant to change.

Our application clearly needs to be distributed: it must support the standalone Java client that our internal travel agents will use. In your application, take a long, hard look at any requirements that push you in the direction of distributed components. Approach such requirements as with BMP:

If, after this process, you determine that you need distributed functionality, your next task is to identify which EJBs should be implemented with remote interfaces and which should stay as local interfaces. In our application, travel agents will use the standalone client to access the full range of application functionality. We already know that session beans are the workhorses of our application—which is why we have exposed the session beans via remote interfaces.

However, none of our entity beans use remote interfaces. Why not? Remember that session beans encapsulate taskflows that manage entity beans, especially when we make good use of the Session Façade pattern. If our session beans are well designed, there should be no need to access entity beans remotely. Also, recall that CMR requires the dependent entities have local interfaces. So we avoid remote interfaces for entity beans.

In that case, how do we pass the entity data, such as cruise information, across the remote interface? Good answers to this question are provided in Returning Entity Data from EJBs. The Transfer Object pattern is preferable to the other approaches when working with remote interfaces. Transfer Objects complement the strict interface of EJB components, and most EJB applications will have Java clients.

In the EJB list above, we chose to implement both remote and local interfaces for our session beans. While this does result in slightly more code to build and maintain, it is a good idea to use the local interfaces in the code that runs inside the application server, such as servlets or JSPs. The small duplication is worth avoiding the remote interface.

Thus, our interface recommendations are:

As you flesh out your EJBs, especially session beans, make sure that your transactions have the smallest scope possible. By scope, we mean the number of operations executed and the number of components used. Operations executed inside a transactional context require more container management than nontransactional operations, and this management generally results in limitations and performance costs. The limitations depend on the container, database, and other transactional components of your application. Exceeding these limitations can create problems that depend greatly on the execution environment and the exact processing being done.

This variability often makes diagnosis and troubleshooting of transactional problems difficult, so the best approach is to minimize transactional scope during design or early in coding. Here is how to identify possible transaction resource problems:

Repeat this evaluation if you make significant changes to your EJBs, especially after revisions that affect your session beans.

This may seem like a no-brainer, but don’t try to make one EJB type behave like another. If you’ve been paying attention throughout this book (you have, haven’t you?), the differences between EJB types should be pretty clear in your head. Session and message-driven beans manage processes (synchronously and asynchronously, respectively), entity beans persist data, and everyone is happy. That’s great! There are two possible wrinkles:

As a consequence, you may find some of the following in your application:

These are all bad things.^[66] If you see these or any similar misconceptions about what each kind of EJB does, do everything you can to fix them ASAP. Depending on the exact circumstances, the consequences may be minor—an additional class or two requiring creation and maintenance—or they may make the EJB nonfunctional or impossible to maintain.

In all but the simplest applications, you will need to return data from your EJBs. This data will be used by other components, other tiers of the application, and maybe even other systems. While EJBs, specifically entity beans, could fulfill this need, there are several reasons why entity beans should not be used outside the EJB container (see the “Local versus remote interfaces” section, above).

The Transfer Object pattern is one solution to this problem. It provides lightweight objects specifically for sending data outside the EJB container. We can also use some other approaches to represent an entity’s data, such as an array of Strings, a Map of field-value pairs, a JDBC ResultSet, or XML. These approaches are generally more loosely coupled than Transfer Objects, providing greater flexibility with commensurate costs. Here’s a quick summary of the pros and cons of each approach:

You have lots of freedom in how you choose to implement these approaches. For example, you could implement a Map-like structure using arrays of Strings to get the benefits of the former while remaining platform-agnostic. However, the benefits of that approach may be offset by the effort needed to build it.

One drawback to these approaches is that the data is a snapshot. If the underlying data changes, none of these structures will know. Therefore, it’s possible that changes to the underlying data could render the data contained in these structures incorrect. This risk can be mitigated by the following data latency strategies:

Of course, all of these strategies have downsides. You will need to balance the trade-offs of entity beans, these “snapshot” approaches, and the above data latency strategies against your requirements.

Many applications, especially those focused on business operations, require sequential (“batch”) processing, such as for an end-of-day process. In these kinds of taskflows, a series of well-defined steps are executed, and many of these steps involve processing a collection of entities. For example, our travel agent application might have an end-of-day process wherein it iterates through all the Customers and generates an invoice record for any new Reservations. Another step might populate reporting tables in a database. There are many other possible steps.

EJB makes implementing these features both easier and more difficult. It is easier because of the transactional enforcement and the logical assignment of responsibilities. After all, the application will make multiple changes in each step (at least one to each entity), and wrapping the changes in a transaction might save us from having to keep track of which entities we’ve processed and which we haven’t. It makes sense to put any processing logic in one place, such as a session bean.

On the other hand, sequential processing can be challenging because of EJB’s performance and resource overhead, and the constraints of transaction enforcement (see the “Minimize transaction scope” section, above). The more steps involved in your taskflow, the more likely you will be to exceed your system’s capabilities. The same is true as more EJBs (entity or session) are used in the taskflow: each additional EJB slows the processing that much more, perhaps unacceptably. Additionally, a gargantuan transaction that takes a long time to complete can have extreme concurrency ramifications.

The bottom line is EJB alone will probably not be successful here. A framework must be developed that incorporates EJB but is not limited by EJB. The heart of the framework is a process controller that knows how to execute a series of steps, each in its own transaction. Part of the process controller is implemented as a session bean. Then you can group the logical tasks of the business process into separate transactional steps. Each of these steps is implemented as a plain Java class that in turn calls the best feasible technology, and each class is called by the process controller. For example, aggregating reporting data in a database might be best implemented as a database stored procedure. Figure 19-9 illustrates a rough UML diagram of the framework.

Figure 19-9. Rough UML diagram of the framework

In short, the sequential processing in your application will probably require some creative integration of EJB and other technologies. Be willing to explore different technologies to serve your needs.

The first step is to determine the application exceptions. Application exceptions encapsulate business errors that prevent the completion of a taskflow. The user should be notified, or the application should attempt to recover from the error, or both. The essential criterion is that the error needs to be propagated several layers (at least) up the application call stack. For example, the Titan application would throw an application exception if a reservation could not be completed because the desired cruise was sold out, and this exception would cause the user interface to display an error message. Avoid scenarios where application exceptions are used as costly if-then statements or other forms of flow control. Exceptions are exceptional.^[67]

Application exceptions can often be identified almost straight from your business requirements, so if the requirements are fully defined, much of the work in this step is already done. The trick is to make sure your exceptions focus on error conditions. Some developers have used exceptions for user interface control, which is bad. For example, if a query for cabin information from the Titan application had no results, it is better to return an empty Collection than throw an exception. Exceptions should be reserved for errors, and other mechanisms should be employed for controlling user interaction.

After you have determined what application exceptions you need, incorporate them into a class hierarchy. A hierarchy provides at least two benefits:

Here are some specific steps to assist in creating the hierarchy:

Subsystem exceptions should not appear in your EJB method signatures. The EJB interface presents functionality and data from a business perspective, while subsystems are implementation-specific. If you cannot recover from a subsystem exception inside your EJB, always catch and rethrow it wrapped in an EJBException.

try {
   ...
} catch ( SQLException se ) {
   throw new EJBException("SQLException caught during processing: " +
                              se.getMessage( ), se);
} catch ( RemoteException re ) {
   throw new EJBException("RemoteException caught during processing: "
                              + re.getMessage( ), re);
}

We will create base classes for our EJBs that contain empty implementations of the container callback methods as well as methods for getting and setting the EJB context. Since the specific set of callback methods and the EJB context class depend on the type of EJB, we will create three base classes: AbstractEntityBean, AbstractSessionBean, and AbstractMessageDrivenBean. In addition, we will add support for the LAST_MODIFIED timestamp column, as it is a common feature in EJB applications. This step requires that we incorporate two abstract methods (getLastModified( ) and setLastModified( )) into the AbstractEntityBean class.

This is the code for AbstractEntityBean:

package com.titan.common;

import javax.ejb.EntityContext;
import javax.ejb.EntityBean;
import java.sql.Timestamp;

public abstract class AbstractEntityBean implements EntityBean {

   private EntityContext entityContext = null;

   public void setEntityContext(EntityContext context) {
      entityContext = context;
   }

   public EntityContext getEntityContext( ) {
      if ( null == entityContext ) {
         throw new IllegalStateException("The entity context has " +
                                         "not been set.");
      }
      return entityContext;
   }

   public void unsetEntityContext( ) {
      entityContext = null;
   }

   public void ejbActivate( ) {
   }

   public void ejbPassivate( ) {
   }

   public void ejbLoad( ) {
   }

   public void ejbStore( ) {
   }

   public void ejbRemove( ) {
   }

   public abstract Timestamp getLastModified( );

   public abstract void setLastModified(Timestamp lastModified);

}

This is the code for AbstractSessionBean:

package com.titan.common;

import javax.ejb.SessionBean;
import javax.ejb.SessionContext;

public abstract class AbstractSessionBean implements SessionBean {

   private SessionContext sessionContext;

   public void setSessionContext(SessionContext context) {
      sessionContext = context;
   }

   public SessionContext getSessionContext( ) {
      if ( null == sessionContext ) {
         throw new IllegalStateException("The session context has " +
                                         "not been set.");
      }

      return sessionContext;
   }

   public void unsetSessionContext( ) {
      sessionContext = null;
   }

   public void ejbActivate( ) {
   }

   public void ejbPassivate( ) {
   }

   public void ejbCreate( ) {
   }

   public void ejbRemove( ) {
   }
}

And here’s the code for AbstractMessageDrivenBean:

package com.titan.common;

import javax.ejb.MessageDrivenBean;
import javax.ejb.MessageDrivenContext;

public abstract class AbstractMessageDrivenBean implements MessageDrivenBean {

   private MessageDrivenContext messageContext;

   public void setMessageDrivenContext(MessageDrivenContext context) {
      messageContext = context;
   }

   public MessageDrivenContext getMessageDrivenContext( ) {
      if ( null == messageContext ) {
         throw new IllegalStateException("The message context has " +
                                         "not been set.");
      }

      return messageContext;
   }

   public void unsetMessageDrivenContext( ) {
      messageContext = null;
   }

   public void ejbCreate( ) {
   }

   public void ejbRemove( ) {
   }
}

Empty implementations of ejbCreate( ) have been provided for the session and message-driven bean base classes. We did not provide an ejbCreate( ) for the entity bean base class because each entity bean’s ejbCreate( ) must return that bean’s primary key type.

Our bean implementation classes will now extend the appropriate base class, like so:

public abstract class CabinBean extends AbstractEntityBean {
    ...
}

public class ReservationProcessorBean extends AbstractMessageDrivenBean 
implements javax.jms.MessageListener {
    ...
}

public class TravelAgentBean extends AbstractSessionBean {
    ...
}

MDBs must still implement the javax.jms.MessageListener interface.

With these changes, we have decreased the amount of code we have to write and maintain. During the implementation phase, you will probably find additional code that can be moved into the base classes.

Using base classes in this way presents three pitfalls:

Now that we have taken care of the base classes, let’s turn to the utility classes. Utility classes are hard to define precisely, because they include generalized data-holding classes, such as a DateRange class that encapsulates a start date and an end date, and non-data classes that contain infrastructure-related, library-like, and convenience methods. Examples of non-data classes include a StringUtils class containing String manipulation functionality, an ObjectUtils class containing various equality and comparison convenience methods, or a DatabaseUtils class containing primary key generation and database connection functionality. Data-holding classes can be more ambiguous. Determining whether they are utility classes or domain-specific types will depend on your particular application and design. For example, a Money class that combines an amount and a currency could be considered a generalized, cross-package class or a finance-specific class.

The primary benefit of utility classes is reducing code duplication, which makes it easier to fix or improve your application without risking shotgun surgery.^[69] Utility classes can also increase code readability.

You will discover candidate utility classes as you implement your design. The biggest sign that you might need a utility class is code duplication. If your code performs the same or very similar logic multiple times, or if two or more classes always accompany each other in methods or method signatures, you have a possible utility class (more correctly, a possible utility method or a possible utility class). Here’s a method that might belong in a utility class:

   public static boolean isEmpty(String str) {
      return ((str == null) || (str.trim( ).equals("")));
   }

The isEmpty method is very simple, but implementing it in a utility class is worthwhile if you check for null or empty Strings often enough—say, when validating method arguments. I would put this method in a StringUtils class.

Here’s an example of a data-holding utility class: suppose you have a series of classes with method signatures that require both a currency and an amount parameter every time:

public Ticket bookPassage(CreditCard card, double price, Integer currency)

If you created a Money class, the modified method from the TravelAgent session bean would look like this:

public Ticket bookPassage(CreditCard card, Money amount)

A DateRange utility class is a common requirement in handling reservations. For example, say that we had added startDate and endDate virtual persistence fields to the Cruise EJB:

public Date getStartDate( );
public void setStartDate(Date start);

public Date getEndDate( );
public void setEndDate(Date end);

Because travel agents will want to search for cruises by these fields, we have added a listMatchingCruises method to the TravelAgent EJB:

public Collection listMatchingCruises(Date start, Date end) throws RemoteException;

After a DateRange class is created, this method changes to:

public Collection listMatchingCruises(DateRange range) throws RemoteException;

While reduced duplication is the most obvious benefit to implementing utility classes, an additional benefit is that reduced duplication makes the interface more coherent: it’s easier to understand a method signature with a date range than a method signature with separate parameters for the start and end dates. Likewise, it’s easier to understand a Money parameter than separate price and currency parameters. Everyone who touches the revised bookPassage and listMatchingCruises methods—their developers, the developers of any client code, or some college intern tasked with maintaining the code a year or two down the line—will have a more intuitive grasp of what those methods expect.

Unfortunately, knowing when to implement this type of refactoring comes with experience. Fortunately, there is an excellent book on refactoring: Martin Fowler’s Refactoring: Improving the Design of Existing Code (Addison-Wesley). Take a look for other ways to identify candidates for utility classes (and for other ways to refactor your code).