Entity Bean Classes and Interfaces

As shown in Figure 22.3, there are many parts of an Entity bean. This section takes you through the required parts and the optional ones. It also shows the differences in requirements of BMP Entity beans and CMP Entity beans.

Primary Keys

Every Entity beans stored in a data store has a primary key associated with it. A primary key is a unique identifier that's used to locate existing Entity beans in a data store. A primary key can consist of a single value, such as an integer, or multiple values, such as date of birth and last name. Every Entity bean must have a primary key. As per the EJB specification, the Home interface can implement the findByPrimaryKey() method.

Note that not only is a primary key mandatory in an Entity bean, but once it's set in ejbCreate, this key's fields cannot change. These limitations are set forth in the EJB specification.

Home Interface

The Home interface of an Entity bean is used to declare methods related to creating new Entity beans, locating existing ones, and for performing a business method that can span across more than one Entity bean.

Creation Methods

An Entity bean can be created in multiple ways with varying amounts and types of information. For example, a Customer Entity bean may be created with merely a customer's Social Security number. If more information is available, we could create one with the customer's Social Security number, name, and phone number. A third option is to create the Customer Entity bean with demographic information such as name, date of birth, and marital status. Creating a new Entity bean equates to a new business object in the data store and a new in-memory copy of that object.

Creation methods must be called with an optional number of types of variables. However, every parameter must be able to be serialized. Each creation method defined in the Home interface is implemented by a corresponding ejbCreate and ejbPostCreate method with the same parameters in the bean's implementation class. So, if the method create(int age) is defined in the Home class, the bean class implements this method with an ejbCreate(int age) and an ejbPostCreate(int age) methods. You can also describe further the create method by adding suffixes. For example, we can have three versions of the create method such as createByAge(int age), ejbCreateByAge(int age), and ejbPostCreateByAge(int age). The return type of the create method is the Remote interface.

Finder Methods

Locating existing Entity beans is accomplished through finder methods. Finder methods can take zero or more parameters to help locate existing Entity beans. For example, a finder method that returns all Entity beans representing orders that have not been paid for could be accomplished without a parameter. A finder method that returns all orders processed within a particular month and year must have the specific month and year passed in as parameters. As a requirement, the Home interface must declare a finder method for locating existing Entity beans using a primary key, named findByPrimaryKey(), taking a primary key class object as a parameter and returning a component interface.

The naming convention for finder methods is findByXYZ where XYZ is user-specified and refers to the method of locating Entity beans. Each finder method defined in the Home interface will be implemented by a corresponding ejbFindByXYZ method with the same parameters in the bean's implementation class. So, if the method findByLastName(String lastName) is defined in the Home class, the bean class will implement this method with an ejbFindByLastName(String lastName) method. Finders can return either a single object of a component interface type or a collection of them.

Business Methods

Additionally, the Home interface can contain business methods that do not relate to a particular entity. For example, an Order bean can have a method that closes all orders by marking an Order Completion flag to be true.

Remote Interface

The Remote interface of an Entity bean is used to declare methods that relate to business logic pertaining to a single element of data. Clients of the Entity bean will work with this interface by calling these methods. Because Entity beans represent business objects that have state, many of these methods will be used to store and retrieve the state or attributes of a business object. For example, a Car Entity bean could have getMake(), setMake(), getModel(), setModel(), getColor(), and setColor() as Remote interface methods.

These getter/setter methods work well when an object and its client are in the same JVM, as in the case of JSPs, servlets, and co-located EJBs. However, if the Entity bean client is not in the same JVM, as the case is for standalone Java clients, we want to access multiple attributes simultaneously to reduce the number of round trips between the Entity bean and its clients. One way of doing this is to employ value objects; another is to use a Session bean as a façade to access the Entity beans locally.

Bean Class

The bean class is where the Entity bean methods are implemented. This class implements the javax.ejb.EntityBean interface, which defines seven methods that must be implemented. However, in some cases, the actual implementation is an empty method. The EJB container calls each of these methods; the EJB client can't invoke them directly.

• ejbLoad() is invoked when the EJB container realizes that the Entity bean needs its states refreshed from the data store. When using BMP, this is where your code is placed to load business object data from a database or other data store and update Entity bean attributes. For CMP, this is just a notification method.

• ejbRemove() is invoked when a business object needs to be removed from the data store. When using BMP, this is where your code to remove the business object from a database or other data store is placed. For CMP, this is a notification method.

• ejbStore() is invoked when the EJB container realizes that the data store needs to be updated with Entity bean information. When using BMP, this is where your code to update the database or other data store with Entity bean data is placed. For CMP, this is a notification method.

• setEntityContext(EntityContext) is invoked when an Entity bean instance is created. The EntityContext object provides the Entity bean instance with access to EJB container runtime context information, such as a reference to itself or its primary key. The EntityContext object is generally stored in a local variable for further use later.

• unsetEntityContext() is invoked when the EJB container will no longer be using this Entity bean instance. It's generally left empty.

• ejbActivate() is used to initialize any resources needed by the EJB. By careful not to hold on to resources for the life of the Entity bean that are not required. For example, a database connection can be requested as needed, and should not be tied up for the life of an Entity bean.

• ejbPassivate() is used to release resources initialized in ejbActivate(). Be sure to release those resources here.

Missing from the EntityBean interface are methods to create a new instance of an Entity bean. These are the implementations of the creation methods defined in the Home interface. Because the parameters are application specific, these methods could not be placed in the EntityBean interface but are nonetheless required for an Entity bean. Every creation method in the Home interface needs a corresponding ejbCreate and ejbPostCreate method in the bean class.

• ejbCreate(parameters) is invoked when the EJB container needs to create a new instance of an Entity bean and its attributes in the data store. This method is responsible for initializing Entity bean instance attributes and creating a representation in the data store. When using BMP, this is where your code to add the business object to a database or other data store is placed.

• ejbPostCreate(parameters) is invoked after its corresponding ejbCreate method is called. Further initialization of Entity bean attributes could be placed here. Because ejbPostCreate is called after setEntityContext, an EntityContext is available in this method, but not in ejbCreate. Setting up relationships can be done here because the current Entity object is now ready to use. This can be useful for initialization purposes.

Deployment Descriptors

The J2EE specification dictates the use of a deployment descriptor named ejb-jar.xml for all EJBs. Entity beans use this XML file to specify runtime behavior, including transactional awareness, primary key information, initial parameters, and security roles for protected methods.

The file weblogic-ejb-jar.xml is used to specify WebLogic Server–specific information about one or more Entity beans. This information includes JNDI addresses, persistence, and security information.

Container-Managed Persistence Entity beans must be accompanied by a weblogic-cmp-rdbms-jar.xml file. This file contains information about the JDBC data source to use and the associations between Entity bean attributes and RDBMS table fields.

Local Interfaces

Normally, Entity beans are accessed as remote objects as explained in Chapter 20, "Enterprise JavaBeans and WebLogic Server." This makes sense when the client is in a different JVM or container, but if the client is another EJB in the same JVM, there's no reason to reference it as a remote object. Local interfaces allow EJBs to call each other as local objects. This is a much quicker and more efficient way of accessing dependent EJBs. Both the Home and the Remote interface can have local counterparts. The local counterparts are optional, whereas the Home and Remote interfaces themselves are mandatory.

When modeling relationships with Entity beans, dependent business objects can communicate using local interfaces. In fact, for Container-Managed Relationships (CMR), dependent Entity beans must access each other with local interfaces.

Primary Key Class

There are many occasions when the primary key for an Entity bean consists of a single value, such as a string or an integer. Basic data classes (String, Integer, Long, and so on) can then be used as the primary key class. However, a compound primary key consisting of multiple values sometimes will be needed. If this is the case, you have to create a class for the primary key.

Value Object

As mentioned earlier, Remote interface methods usually consist of getter and setter methods for each attribute of a business object. When the Entity bean client is in a different JVM and/or container, calling many of these methods in the context of one business operation adds a lot of network overhead because each method call is remote. Value objects are JavaBeans that carry many pieces of information and have getter and setter methods for them. They are just helper classes, like exceptions, objects that are passed as parameters or returned by methods, or any other class that the bean implementation might need. These are generally always used with EJBs, but they aren't required by the EJB specification.

For example, a client can request doctors name, specialty, and contact number information from a Doctor Entity bean. The Doctor Entity bean can create a DoctorVO value object and fill it with this information. The client then can extract this information from the DoctorVO value object. With one remote method call, the client has actually received three attributes of the Doctor Entity bean. This design pattern is a typical way to optimize access to EJBs.