MESSAGE-DRIVEN BEANS 155 grate enterprise beans with packages and legacy applications. Chapter 6 dis- cusses this approach further. • When you want the message delivery to drive other events in the system. For example, workflow steps can be based on the mere fact of message delivery, or they can be based on the message content. • When you want to create message selectors. A message selector is designed to take on only specific messages, thus making it possible to use message-driven beans as triggers. 5.6.2 Example: Invoice Message-Driven Bean Code Example 5.5 shows a message-driven bean that updates purchase orders based on invoice information received in a JMS message. The message-driven bean listens for JMS messages containing invoice data. When it receives a message, its onMessage method extracts the invoice data from the message text. In this example, the data has been encoded in XML, which is parsed and then used to process an invoice. public class InvoiceMDB implements MessageDrivenBean, MessageListener { public void onMessage(Message msg) { try { String msgTxt = ((TextMessage) msg).getText(); Invoice invoice = Invoice.fromXML(msgText); // do further processing } catch ( ) { // handle exceptions } } } Code Example 5.5 Message-Driven Bean Example DEA2e.book Page 155 Friday, March 8, 2002 12:31 AM CHAPTER 5 THE ENTERPRISE JAVABEANS TIER 156 5.7 Design Guidelines While you are free to write your application and enterprise bean code according to your own needs, we do recommend certain guidelines. • Keep the code in enterprise beans as “client-neutral” as possible. Enterprise beans are meant to contain business logic that can be used by many client types. Methods in enterprise beans that serve only oneclient type make any logic within that method inaccessible to other client types. Code that is specific for a particular client type belongs with the software managing that client type. In particular, Web-tier and HTTP-related functions and data do not belong in an enterprise bean. • Keep as much business logic as possible in the EJB tier. By doing so, you take advantage of the EJB container services and simplify your programming ef- fort. • Use stateful session beans to manage conversational state rather than manag- ing conversational state in the client or Web tier. As with the previous point, this leverages the advantages of enterprise beans. In addition to the guidelines discussed previously for choosing specific bean types, there are other design choices that you need to make when developing objects for the EJB tier. These choices include the types of objects that should be enterprise beans, and the role an enterprise bean may play in a group of collabo- rating components. You may also need to consider the services provided by enterprise beans and the EJB container, and decide whether these services benefit your application. You should take into consideration these EJB services and advantages: • The EJB architecture handles such system services as transaction manage- ment, security, scalability, persistent data access, distributed processing, and concurrency. An enterprise bean developer does not have to include code to handle these services. As a developer, you can focus on the application and business logic. • Enterprise beans support multiple types of components. • Enterprise beans support applications with a complex series of operations and accumulation of conversation state over time. DEA2e.book Page 156 Friday, March 8, 2002 12:31 AM DESIGN GUIDELINES 157 • Enterprise beans are portable across hardware platforms, operating systems, server implementations, and databases . • Enterprise beans can be easily customized in the runtime environment. • Enterprise beans are reusable software modules. 5.7.1 Remote versus Local Client Access for Entity Beans As noted earlier, an entity bean must implement a local client view to be the target of a container-managed relationship. However, the requirements of the application might necessitate that the same entity bean implement a remote view as well. It is possible for an entity bean to use a local view and have the advantages of container- managed relationships, and to expose its functionality to remote clients. This can be done in the following two ways. A bean provider can implement a session bean with a remote client view that serves as a facade to the local entity beans implementing the container-managed relationships. Clients use the methods of the remote session bean, which in turn provides a conduit to the functionality of the local entity bean or beans. Because the session bean implements a remote view, clients are not restricted to the same Java Virtual Machine as the session bean. The functionality of the local entity beans is available to remote clients through this session bean. Alternatively, the bean provider can implement an entity bean with both a local and remote client view. This dual-purpose entity bean may have one or more entity beans with local interfaces behind it. The remote entity bean interface pro- vides a coarse-grained view of the persistent data that is modeled by the network of entity beans related through their local interfaces. The remote entity bean may be accessed directly by clients of the EJB tier, or the bean provider may imple- ment a remote session bean that serves as a facade to the entity bean with both the local and remote view. Note that if the same method is exposed through both local and remote interfaces, the method will be called with the pass-by-reference semantics in the local case, and with the pass-by-value semantics in the remote case. The bean provider needs to take care while writing and invoking the method to avoid any unintended side-effects. 5.7.2 Session Beans as a Facade to Entity Beans A facade provides a unified interface to a set of interfaces. This section describes when and how to use a session bean as a facade to entity beans. DEA2e.book Page 157 Friday, March 8, 2002 12:31 AM CHAPTER 5 THE ENTERPRISE JAVABEANS TIER 158 Entity beans represent an object-oriented view of data and provide business logic to manipulate this data. In an enterprise environment, entity beans often need to be shared among different applications representing different tasks. In such cases, use of application-specific stateful session beans to manage the inter- action of various entity beans provides a simpler interface to the client by giving the client a central point of entry. The client always interacts with this session bean and is unaware of the existence of other entity beans in the system. However, if the client interacts with only a few entity beans in a relatively simple way, the entity beans can be exposed directly. Stateful session beans are logical extensions of the client programs. The deci- sion to use one or many session bean facades depends on the types of clients the application supports. Since the sample application has only a single type of client, the shopping client, the sample application uses a single stateful session bean called ShoppingClientFacadeLocal. It’s easy to imagine another client that would provide administration functionality such as inventory and order status monitor- ing. The work flow of such a client would be entirely different from a shopping client. Therefore, it is advisable to define another stateful session bean that encap- sulates this administrative work flow. However, it is not recommended that a session bean be created as a facade for every entity bean in the system, as that approach would waste server resources. 5.7.3 Fine-Grained versus Coarse-Grained Object Access Entity beans with local interfaces provide efficient access to fine-grained objects. Model these objects as local entity beans when you can assure that their clients are co-located on the same JVM, or implement the business objects with a local view and provide a remote enterprise bean facade to them. As mentioned earlier, enterprise beans that are implemented as remote objects may consume significantly more system resources and network bandwidth to exe- cute. Because of the overhead of remote access, remote entity beans should not be used for fine-grained access. Therefore, only model a business object as a remote entity bean if its clients are distributed. In such a case, keep the entity bean access coarse grained, and use a value object to pass data across the remote interface. A value object is a serializable Java object that can be passed by value to the client. A value object can be used to aggregate state extracted from a remote entity bean for use by the client. By avoiding the use of fine-grained remote method calls to retrieve the persistent state of an entity bean, value objects help reduce the network overhead involved in remote access. DEA2e.book Page 158 Friday, March 8, 2002 12:31 AM DESIGN GUIDELINES 159 The sample application models the details of an order as a value object repre- senting the state of a particular order in the database and providing getter methods to query the state of this account. An administration client makes just one remote call to execute getOrdersByStatus on the remote object account and gets back a collection of the serialized OrderDetails objects. The client can then query the state of these orders locally via the methods provided with the OrderDetails object. 5.7.3.1 Example: An Address Value Object In the sample application, an address and credit card information are modeled as value objects. The definition of the Address class is shown in Code Example 5.6. public class Address implements java.io.Serializable { public Address (String streetName1, String streetName2, String city, String state, String zipCode, String country){ this.streetName1 = streetName1; this.streetName2 = streetName2; } public String getStreetName1() { return streetName1; } private String streetName1; private String streetName2; } Code Example 5.6 Address value object An Address does not exhibit complex behavior, but is merely a data structure that contains only data fields. An address is fine-grained, having only get and set methods. Moreover, it only has meaning if it is associated with an account. When making the object pass-by-value it is important to make it immutable to reinforce the idea that the value object is not a remote object and changes to its state will not be reflected on the server; in other words, it is just a copy and not the remote reference. To make an Address object immutable, declare all its instance data private and supply only get methods. To change a pass-by-value object, the DEA2e.book Page 159 Friday, March 8, 2002 12:31 AM CHAPTER 5 THE ENTERPRISE JAVABEANS TIER 160 client must first remove it and then create a new object with the desired field values. 5.7.4 Master-Detail Modeling Using Enterprise Beans In a master-detail relationship, one object serves as a pointer to another. Typically such a relationship is represented to the user as a list of items from which to select. This list is called a master record and its contents are provided by the master object. Selecting an item from this list leads to an expanded view of that item. The expanded view is provided by a detail object. A master-detail relationship is a one-to-many type relationship among data sets. A set of purchase orders and a set of line items belonging to each purchase order is an example of a master-detail relationship. An application can use this master-detail relationship to enable users to navigate through the purchase order data and see the detail data for line items only when needed. Entity beans with container-managed persistence are the preferred way to implement master-detail relationship modelling, since they support container- managed relationships. Further, container-managed relationships provide a cascade-delete facility that automatically enables the lifetime of the detail object to be dependent on the lifetime of the master, capturing an important aspect of this dependency. 5.7.5 Data Access Objects In situations where the use of container-managed persistence is not suitable, data access objects can be used to encapsulate access to persistent data. A data access object (DAO) design pattern separates the interfaces to a system resource from the underlying strategy used to access that resource. Both entity beans with bean- managed persistence and session beans can use DAOs. A DAO class provides an abstract API for manipulating a data source. This abstract API makes no reference to how the data source is implemented. The DAO simply has to know how to load itself from persistent store based on some identity information (a primary key or a file name, for example), how to store itself, and so on. By encapsulating data access calls, data access objects allow adapting data access to different schemas or even to different database types. Data access objects for different schemas and databases can share a common interface enabling the application assembler to choose the appropriate object from among DEA2e.book Page 160 Friday, March 8, 2002 12:31 AM DESIGN GUIDELINES 161 several at assembly time. Section 6.4.3 on page 188 extends this approach to show how access objects can be used to create an integration layer. The DAO pattern is not limited to representing data in a database. It can also encapsulate XML data sources as DAO classes. 5.7.5.1 Clarifying Bean Implementations When a session bean or an entity bean with bean-managed persistence needs to access a database within a method implementation, a corresponding method in the data access object implements the actual logic of fetching or updating data in the database. This removes the data access logic from the enterprise bean implementa- tion. The bean’s business logic is not cluttered with data access calls, such as JDBC calls, making it much cleaner and readable. For example, consider the Catalog session bean. The business method getProducts needs to return all the products for a category. Whenever getProducts needs to operate on data residing in the database, it hands over control to a data access object. The data access object formulates the query, fetches the result set, and returns the data in the desired format to the bean’s calling method. In the sample application, the implementation of the Catalog session bean is provided by CatalogEJB. The code for CatalogEJB.getProducts appears in Code Example 5.7; the code for the corresponding data access object appears in Code Example 5.8. public Page getProducts(String categoryId, int start, int count, Locale l) { try { // initialize dao to an instance of CatalogDAOImpl return dao.getProducts(categoryId, start, count, l); } catch ( ) { // catch exceptions and throw an EJBException } } Code Example 5.7 CatalogEJB.getProducts public Page getProducts(String categoryId, int start, int count, Lo- cale l) { // initialize database connection and other variables DEA2e.book Page 161 Friday, March 8, 2002 12:31 AM CHAPTER 5 THE ENTERPRISE JAVABEANS TIER 162 String query = "select COUNT(*) from (product a join" + "product_details b on a.productid=b.productid) " + "where locale = ? and a.catid = ? "; PreparedStatement ps = con.prepareStatement(query, ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY); ps.setString(1, l.toString()); ps.setString(2, categoryID); ResultSet rs = ps.executeQuery(); // Create page from the result set and return it } Code Example 5.8 CatalogDAOImpl.getProducts 5.7.5.2 Consequences of Using DAO Pattern Potential consequences of using the data access object pattern include: • Resource vendor independence When a component uses a vendor-specific API, it is locked into that vendor’s product line. The DAO pattern provides a layer of indirection that isolates ven- dor-specific code in a class or several classes, where it can easily be replaced if necessary or desirable. • Resource implementation independence DEA2e.book Page 162 Friday, March 8, 2002 12:31 AM DESIGN GUIDELINES 163 • Similar types of resources are often available in various formats through vari- ous access methods. For example, persistent data can be implemented by a re- lational database, an object database, flat files in a file system, interaction with a remote persistence server, and so on. The DAO pattern separates the manage- ment of data access mechanism details from the behavior of application ob- jects. Easier migration to container-managed persistence A data access object, by encapsulating persistence logic and separating it from business logic, facilitates migrating from bean-managed persistence to con- tainer-managed persistence. • Enhanced extensibility It is easier to add new data source types using data access objects. Each such type requires only a new DAO class, plus integration of that class into the ex- isting framework. 5.7.6 Implementing an Entity Bean without a Create Method There are times when you do not want to provide create methods in an entity bean’s home interface. Omit the create methods when you do not want the entity bean to create persistent data. Typically in these situations, some other system or process is responsible for creating the data underlying the entity bean’s persistent representa- tion. For example, database functions insert new data into a database, and clients use the entity bean to retrieve data. 5.7.7 Representing References to Entity Beans References between enterprise beans are common in many applications. Entity beans reference other related beans, stateful session beans may keep references to entity beans in conversational state, and stateless session beans and message-driven beans may look up and pass references to other beans. Developers can represent ref- erences between entity beans in the following ways: • Use a container-managed relationship With the EJB 2.0 architecture, model persistent references between entity beans using container-managed persistence as container-managed relation- DEA2e.book Page 163 Friday, March 8, 2002 12:31 AM CHAPTER 5 THE ENTERPRISE JAVABEANS TIER 164 ships. Container-managed relationships automatically maintain persistent ref- erences between entity beans and collections of entity beans. • Store a reference to a home or component interface in a non-persistent field of an entity bean with bean-managed persistence or in an instance variable of a session or message-driven bean. Beans can retain references to other entity beans in instance fields. • Use the referenced entity bean’s primary key If a referenced entity bean’s home interface is known, the referencing bean can use the findByPrimaryKey method in the referenced bean’s home interface to find a bean’s component interface. • Do not pass this as a reference to an enterprise bean. Doing so circumvents the EJB container and causes errors. 5.8 Portability Guidelines The best way to achieve application portability is to use only J2EE-compatible application servers and tools. These products pass the rigorous J2EE Compatibility Test Suite (CTS) that ensures “Write-Once-Run-Anywhere” portability for J2EE applications. Another way to ensure portability is to use more than one application server in the development cycle. The J2EE Reference Implementation (J2EE RI) is a good choice for a second application server. It is also helpful to use code generation wizards to write enterprise beans. Besides enhancing productivity, such wizards typically generate code that is con- sistent with the J2EE specifications, thereby eliminating inadvertent errors. For example, such wizards will typically ensure that your enterprise bean methods throw all required exceptions— RemoteException, FinderException, and so on. These tools are particularly useful for generating the deployment descriptor since the deployment descriptor content must follow a precise XML syntax. Writing them manually is prone to errors because it is easy to incorrectly order elements, duplicate element entries, or make simple typing mistakes. Most application servers also ship with verification tools that validate the components and their deployment descriptors against the J2EE specifications. The DEA2e.book Page 164 Friday, March 8, 2002 12:31 AM [...]... of databases The principal advantage of data access objects is that they decouple the user of the object from the programming mechanism that accesses the underlying data The DAO exposes the same interface to its clients regardless of the API it uses to access the EIS data Even changes to the schema or function specification of the EIS may not impact the DAO’s user interface This means that the user’s... access to data The middle tier of enterprise computing has evolved as the ideal place to provide these services The J2EE platform promotes the Enterprise Java- DEA2e.book Page 169 Friday, March 8, 2002 12:31 AM SUMMARY Beans architecture as a way to provide the system services that most enterprise applications need The EJB architecture frees enterprise application developers from concerns about these services,... PortableRemoteObject.narrow method The overhead on this method call is usually quite small In addition, EJB containers that do not use RMI-IIOP typically optimize away all such overhead Note that the narrow method must not be used in the clients of local enterprise beans since they are in the same JVM The local enterprise beans are always typenarrowed using the regular typecast of the Java programming language 5. 8.2 Mark... existing applications and EISs The emergence of Web-based architectures and Web services has made it more imperative for enterprises to integrate their EISs and applications and expose them to the Web The EIS integration problem is one part of the broader scope of enterprise application integration (EAI) EAI entails integrating applications and enterprise data sources so that they can easily share business... model to interact with the messaging system For example, a client application can produce a set of messages and use a transaction to group the messages together into a single atomic unit of work When the transaction commits, the messaging system sends the set of messages as one unit If the transaction rolls back, the messaging system discards the entire set of messages produced within the rolled back transaction... Integrating with the Enterprise Information System Tier by Rahul Sharma and Beth Stearns THIS chapter focuses on the integration of enterprise applications with existing enterprise information systems (EIS) and applications Enterprise information systems provide the information infrastructure critical to the business processes of an enterprise Examples of EISs include relational databases, enterprise resource... J2EE applications and the target EIS Synchronous communication between a J2EE application and an EIS follows the request-response interaction model An application initiates a request to the target EIS The application then blocks its processing in the request invocation thread while it waits for a response from the EIS The application continues its execution after it receives the response Most EISs... waits synchronously while the function executes on the EIS and continues when the remote function returns The 1.0 version of the Connector architecture supports a synchronous requestresponse interaction mode where an application component initiates the synchronous request The application server and resource adapter for the underlying EIS manage transaction and security through the system contracts provided... methods This is because the container can choose several ways to manage the life cycle of its enterprise beans For example, in the ejbActivate method the container is not required to load an entity bean’s instance fields from its persistence store Similarly, in the ejbPassivate method the container is not required to store the instance fields to its persistence store In addition, the container is not... of an application The following sections describe each of these aspects from the perspective of relational database access using JDBC API, with the exception of transactions, which are discussed in Chapter 8 An important point to note is that the following sections are not meant to be a programmer’s guide to using the JDBC API While the following discussions refer to the JDBC API, the concepts are generic . in the clients of local enterprise beans since they are in the same JVM. The local enterprise beans are always type- narrowed using the regular typecast of the Java programming language. 5. 8.2. bean types, there are other design choices that you need to make when developing objects for the EJB tier. These choices include the types of objects that should be enterprise beans, and the role an enterprise. serialized OrderDetails objects. The client can then query the state of these orders locally via the methods provided with the OrderDetails object. 5. 7.3.1 Example: An Address Value Object In the sample application,