Specifying a BMP Entity Bean

Following the pattern of Session beans, specifying an Entity bean involves defining the local-home and the local interface:

• The local-home interface extends javax.ejb.EJBLocalHome.

• The local interface extends javax.ejb.EJBLocalObject.

A discussion on each of these interfaces follows.

Local-Home Interface

Listing 6.1 shows the complete JobLocalHome interface as an example.

Listing 6.1. JobLocalHome Interface

 1: package data;
 2:
 3: import java.rmi.*;
 4: import java.util.*;
 5: import javax.ejb.*;
 6:
 7: public interface JobLocalHome extends EJBLocalHome
 8: {
 9:      JobLocal create (String ref, String customer) throws CreateException;
10:      JobLocal findByPrimaryKey(JobPK key) throws FinderException;
11:      Collection findByCustomer(String customer) throws FinderException;
12:      Collection findByLocation(String location) throws FinderException;
13:      void deleteByCustomer(String customer);
14: }

Each of these methods has a corresponding method in the bean class itself. Taking the JobBean code as an example:

• The ejbCreate(String ref, String customer) method in JobBean corresponds to create(String ref, String customer) in the JobLocalHome interface.

• The ejbFindByPrimaryKey(String name) method in JobBean corresponds to findByPrimaryKey(String name) in the JobLocalHome interface.

• The ejbFindByCustomer(String customer) method in JobBean corresponds to findbyCustomer(String customer) in the JobLocalHome interface.

• The ejbHomeDeleteByCustomer(String customer) in JobBean corresponds to deleteByCustomer(String customer) in the JobLocalHome interface.

This seems straight-forward enough, but note that the return types for the bean's ejbCreate() and ejbFindXxx() methods are different from the return types of the methods in the local-home interface. Specifically, while the bean returns (to the EJB container) either primary key objects or Collections of primary key objects, the local-home interface methods return (to the client) either local proxies (that is, instances of objects that implement the JobLocal interface, for the example) or Collections of such.

Create and Remove Methods

The list of exceptions thrown by the local-home methods and the bean's corresponding methods should match in each case. For the createXXX() method, the list should be the union of the exceptions thrown by both ejbCreateXXX() and ejbPostCreateXXX(). If a home and a remote interface are being provided for the Entity bean, the java.rmi.RemoteException must be declared for the methods of the home interface.

As well as the create() method, the local-home interface inherits a remove(Object o) method from javax.ejb.EJBLocalHome. This corresponds to the ejbRemove() lifecycle method of the bean itself.

Finder Methods

Finder methods in the bean return either a single primary key (if a single bean matches the underlying query) or a java.util.Collection of primary keys (if there is more than one matching bean). The ejbFindByPrimaryKey() method is always required to be one of the bean's methods, although it is not part of the EntityBean interface. This is because the argument type and return type will depend upon the bean.

Obviously, to specify the findByPrimaryKey() method, the primary key of the Entity bean must have been identified. As was noted earlier today, if persisting to an RDBMS, identifying the primary key is probably quite easy, because the primary key will correspond to the columns of the primary key of the underlying RDBMS table. A custom-developed primary key class is needed when two or more fields identify the bean; otherwise, the type of the single field of the bean that represents the key is used.

Custom Primary Key Classes

As noted earlier, the primary key can be either a field of the bean (in which case, the primary key class is just the class of that field) or can be a custom-developed class. The latter is required if more than one field is needed to identify the bean (and can be used even for single field keys).

For the JobBean, the primary key is a combination of the customer and the job reference (the customer and ref fields, respectively). Because the primary key is composite, a custom primary key class is needed; this is the JobPK class.

Custom primary key classes are required to follow a number of rules. Specifically

• The class must implement java.io.Serializable or java.io.Externalizable.

• The values of the class must all be primitives or be references to objects that, in turn, are serializable.

• The equals() method and the hashCode() methods must be implemented.

• There must be a no-arg constructor (there can also be other constructors that take arguments, but they would only be provided for convenience).

In other words, the class must be what is sometimes referred to as a value type.

Listing 6.2 shows the JobPK primary key class.

Listing 6.2. JobPK Class Identifies a Job

 1: package data;
 2:
 3: import java.io.*;
 4: import javax.ejb.*;
 5:
 6: public class JobPK implements Serializable {
 7:     public String ref;
 8:     public String customer;
 9:
10:     public JobPK() {
11:     }
12:     public JobPK(String ref, String customer) {
13:         this.ref = ref;
14:         this.customer = customer;
15:     }
16:
17:     public String getRef() {
18:         return ref;
19:     }
20:     public String getCustomer() {
21:         return customer;
22:     }
23:
24:     public boolean equals(Object obj) {
25:         if (obj instanceof JobPK) {
26:             JobPK pk = (JobPK)obj;
27:             return (pk.ref.equals(ref) && pk.customer.equals(customer));
28:         }
29:         return false;
30:     }
31:     public int hashCode() {
32:         return (ref.hashCode() ^ customer.hashCode());
33:     }
34:     public String toString() {
35:         return "JobPK: ref="" + ref + "", customer="" + customer + """;
36:     }
37: }
							

Note that the ref and customer fields have public visibility. This is a requirement of the EJB specification. Each field must correspond—in name and type—to one of the fields of the bean itself. This might seem like a strange requirement, but is needed by the EJB container to manage CMP beans.

To implement the equals() method, test that all fields of the object have the same value as the fields in the provided object. For primitive values, the regular == operator should be used, but for object references, the equals() method must be called.

To implement the hashCode() method, generate an int value that is based entirely and deterministically on the value of the fields, such that

if A.equals(B) then A.hashCode() == B.hashCode().

There are a couple of ways to accomplish this. A quick way to do this is to convert all the values of the primary key class' fields to Strings, concatenate them to a single String, and then invoke the hashCode() on this resultant string. Alternatively, the hashCode() values for all of the fields could be or'd together using the ^ operator. At runtime, this will execute more quickly than the concatenation approach, but it does mean that the distribution of hashcodes may be less good for primary keys with many fields. This is the approach used in Listing 6.2.

Home Methods

In addition to finder, create, and remove methods, it is also possible to define home methods within the local-home interface. These are arbitrary methods that are expected to perform some business-type functionality related to the set of beans. In other words, they are an EJB equivalent of Java class methods (defined with the static keyword).

Some common uses for home methods include defining a batch operation to be performed on all bean instances (such as decreasing the price of all catalogue items for a sale), or various utility methods, such as formatting a bean's state for a toString() method.

UPDATE catalogue
set price = price * 0.9

Local Interface

Just as for Session beans with their remote interfaces, the local interface defines the capabilities of the Entity bean. Because first and foremost an Entity bean represents data, it is entirely to be expected that many of the methods exposed through the local interface will be simple getter and setter methods. Listing 6.3 shows the local interface for the Job bean.

Listing 6.3. JobLocal Interface

 1: package data;
 2:
 3: import java.rmi.*;
 4: import javax.ejb.*;
 5:
 6: public interface JobLocal extends EJBLocalObject
 7: {
 8:     String getRef();
 9:     String getCustomer();
10:     CustomerLocal getCustomerObj(); // derived
11:
12:     void setDescription(String description);
13:     String getDescription();
14:
15:     void setLocation(LocationLocal location);
16:     LocationLocal getLocation();
17:
18:     Collection getSkills();
19:     void setSkills(Collection skills);
20: }

Note that the setLocation() method accepts a LocationLocal reference rather than, say, a String containing the name of a location. In other words, the Job bean is defining its relationships to other beans, in this case the Location bean directly, effectively enforcing referential integrity. The client of the Job Entity bean is thus required to supply a valid location or none at all.

This is not to say that Entity beans cannot provide further processing. An example often quoted might be for a SavingsAccountBean. This might provide withdraw() and deposit() methods. The withdraw() method might well ensure that the balance can never go below zero. The bean might also provide an applyInterest() method, but it almost certainly would not provide a setBalance() method (if only!).

Each of these methods has a corresponding method in the bean itself, and the exceptions list matches exactly. The implementation is shown in the “Implementing the Local-Interface Methods” section later today.