8.3 Parts Developed at Star Enterprise

Prior to the deployment of Wombat's benefits application, Star Enterprise already had a Benefits Enrollment application that it had developed internally. (See Chapter 4 for the description of the Benefits Enrollment application using session beans.)

With the deployment of Wombat's benefits application, Star Enterprise needs to integrate some parts of its application into Wombat's application. This section addresses these issues.

8.3.1 The Employee Database and Deployment of EmployeeEJB

The human resources department at Star Enterprise maintains the information about employees and company departments in EmployeeDatabase. The information is stored in multiple tables. The Employees table within the database is relevant to the benefits application. The schema for EmployeeDatabase is described in Section 4.6.1, The Employee Database, on page 120.

Note that as an ISV, Wombat had no knowledge of the schema of EmployeeDatabase and did not need that knowledge. Coding its benefits application as generically as possible, Wombat's primary consideration was that the application work regardless of an individual customer's schema and type of DBMS. If Wombat coded the benefits application according to the Star Enterprise schema, the application would be unusable by customers having a different schema or even a different type of DBMS.

Star Enterprise has two choices for deploying the EmployeeEJB entity bean developed by the ISV Wombat:

1. It can use an object-relational mapping tool to map the CMP fields of the EmployeeEJB to the columns of the Employees table in its relational database EmployeeDatabase. An example of such a mapping of fields follows:

   CMP Field in EmployeeBean	Column Name in Employees Table
   employeeNumber	empl_id
   firstName	empl_first_name
   lastName	empl_last_name
   birthDate	empl_birth_date

2. It can develop an entity bean by using bean-managed persistence and can write the database access code in the BMP bean class. This approach is described in the next section.

8.3.2 EmployeeBeanBMP Entity Bean Class

The EmployeeBeanBMP bean class uses bean-managed persistence to manage the state of the EmployeeEJB entity bean. This class uses the same local interface Employee and local home interface EmployeeHome as in the EmployeeEJB entity bean. (See Section 8.2.3, EmployeeEJB Entity Bean, on page 255.) The EmployeeBeanBMP class subclasses the EmployeeBean container-managed persistence class.

This section discusses some of the important issues that need to be kept in mind when developing entity beans with bean-managed persistence. Portions of code from the EmployeeBeanBMP class are used to illustrate these points. See Section A.7, EmployeeBeanBMP Class, on page 402 for the complete code for the EmployeeBeanBMP class.

The EmployeeBeanBMP class has three types of methods:

• Get and set methods for CMP fields

• EntityBean interface life-cycle methods

• Database access helper methods

CMP Field Methods

The EmployeeBeanBMP class needs to implement all abstract methods defined in the EmployeeBean class. These methods correspond to the abstract get and set methods for the CMP fields declared in the EmployeeBean CMP class. These methods get and set concrete fields in the EmployeeBeanBMP class corresponding to the CMP fields. Code Example 8.27 shows the code for these methods:

Code Example 8.27 Implementation of EmployeeBeanBMP Get and Set Methods

 public class EmployeeBeanBMP extends EmployeeBean {    // this field holds the JDBC DataSource for the employee database    private DataSource dataSource;    // the following fields hold the persistent state of    // the EmployeeBean.    private Integer employeeNumber;    private String firstName;    private String lastName;    private Date birthDate;    // The following methods implement the abstract CMP    // field getters/setters declared in the EmployeeBean class.    public Integer getEmployeeNumber() {       return employeeNumber;    }    public void setEmployeeNumber(Integer n) {       employeeNumber = n;    }    public String getFirstName() {       return firstName;    }    public void setFirstName(String s) {       firstName = s;    }    public String getLastName() {       return lastName;    }    public void setLastName(String s) {       lastName = s;    }    public Date getBirthDate() {       return birthDate;    }    public void setBirthDate(Date d) {       birthDate = d;    }    .... } 

Life-Cycle Methods

The EmployeeBeanBMP class also implements the entity bean life-cycle methods, including ejbCreate and ejbPostCreate, and methods of the javax.ejb.EntityBean interface. Code Example 8.28 shows the code for the ejbCreate and ejbPostCreate methods:

Code Example 8.28 EmployeeBeanBMP ejbCreate and ejbPostCreate Methods

 public Integer ejbCreate(int emplNumber, String fname, String lname,                   Date birthDate) throws CreateException {    // this sets all the CMP fields    super.ejbCreate(emplNumber, fname, lname, birthDate);    // check if the primary key exists    if ( primaryKeyExists(emplNumber) ) {       throw new DuplicateKeyException("Employee number " +              emplNumber + " already exists in database");    }    // create a row for this bean instance    createRow();    // return the primary key    return new Integer(emplNumber); } public void ejbPostCreate(int emplNumber, String fname,           String lname, Date birthDate) throws CreateException {} 

EmployeeBeanBMP's ejbCreate method first calls its superclass EmployeeBean's ejbCreate method, which sets the values of the CMP fields by calling the respective set methods. This operation sets values in the Java fields in the EmployeeBeanBMP class. EmployeeBeanBMP's ejbCreate method then checks whether the primary key for the employee, which is the employee number emplNumber already exists in the database. If it does, the method throws DuplicateKeyException to indicate to the client that an application-level error has occurred. If the employee number does not exist, the ejbCreate method creates a row for the employee in the database by calling the createRow helper method. Finally, the ejbCreate method returns the new bean instance's primary key, as required for BMP entity beans. The container converts this primary key to an Employee reference and returns it to the client.

Two additional entity bean life-cycle methods are in the EmployeeBeanBMP class: setEntityContext and unsetEntityContext. Code Example 8.29 shows the code for these methods:

Code Example 8.29 The setEntityContext and unsetEntityContext Methods

 public void setEntityContext(EntityContext c) {    super.setEntityContext(c);    String dataSourceName = "java:comp/env/jdbc/EmployeeDatabase";    try {       Context ctx = new InitialContext();       dataSource = (DataSource)ctx.lookup(dataSourceName);    } catch ( Exception ex ) {       throw new EJBException("Unable to look up dataSource "              + dataSourceName);    } } public void unsetEntityContext() {    dataSource = null;    super.unsetEntityContext(); } 

The setEntityContext method is called immediately after the EmployeeBeanBMP class is instantiated. The method first calls the EmployeeBeanBMP superclass's setEntityContext method to allow the superclass to do any necessary initialization. The method then looks up the JDBC DataSource object for EmployeeDatabase from the JNDI environment.

The unsetEntityContext is the last method called before the EmployeeBeanBMP instance is destroyed. This method clears the value of the DataSource field and calls the superclass's unsetEntityContext method to allow the superclass to perform any required cleanup.

Database Access Methods

The EmployeeBeanBMP class implements the ejbFindByPrimaryKey method (Code Example 8.30):

Code Example 8.30 The EmployeeBeanBMP Class ejbFindByPrimaryKey Method

 public Integer ejbFindByPrimaryKey(Integer emplNum)            throws FinderException {    // Try to load the row for this primary key    if ( !primaryKeyExists(emplNum.intValue()) ) {       throw new ObjectNotFoundException("Primary key " + primaryKey                  + " not found");    }    return emplNum; } 

The ejbFindByPrimaryKey method checks whether the emplNum argument the primary key for the EmployeeEJB bean exists in the database, doing so by calling the helper method primaryKeyExists. If the employee number does not exist, the method throws ObjectNotFoundException to inform the client. If the employee number does exist, the method returns the primary key. The container converts this primary key to an Employee reference and returns it to the client.

The EmployeeBeanBMP class also implements the ejbRemove method, as shown in Code Example 8.31:

Code Example 8.31 The ejbRemove Method in EmployeeBeanBMP

 public void ejbRemove() throws RemoveException {    super.ejbRemove();    // remove the row for this primary key    removeRow();    // clear all CMP fields    employeeNumber = null;    firstName = null;    lastName = null;    birthDate = null; } 

The ejbRemove method first calls the ejbRemove method of the superclass EmployeeBean. This allows the superclass's ejbRemove implementation to do any needed work. Then EmployeeBeanBMP's ejbRemove method calls the helper method removeRow to remove the row for this bean instance from the database. After this, the ejbRemove method clears all employee-specific fields. This is an important step because the bean instance goes into the container's pool after removal and can be used for another employee with a different identity and different fields. The ejbRemove method needs to clean up all fields that are specific to the particular employee. Note that ejbRemove does not need to clear the dataSource field, because that field's value does not depend on any particular employee.

Now let's examine the ejbLoad and ejbStore methods, which are used to synchronize the state of the bean with the persistent state in the database. The ejbLoad method is usually called at the beginning of a transaction, before any business methods are called. The ejbStore method is usually called at the end of a transaction, when a transaction is committed. Code Example 8.32 shows the code for these methods:

Code Example 8.32 EmployeeBeanBMP's ejbLoad and ejbStore Methods

 public void ejbLoad() {    try {       loadRow();    } catch ( Exception ex ) {       throw new NoSuchEntityException(          "Exception caught in ejbLoad: "+ex);    }    super.ejbLoad(); } public void ejbStore() {    super.ejbStore();    try {       storeRow();    } catch ( Exception ex ) {       throw new EJBException("Exception caught in ejbStore ", ex);    } } 

The ejbLoad method calls the loadRow helper method to load the state of the bean. The loadRow helper method does a database read, using the employee number primary key; retrieves the row for the employee; and sets the CMP fields in the EmployeeBeanBMP class. After the loadRow method completes successfully, the ejbLoad method calls the superclass EmployeeBean's ejbLoad method to allow the superclass to initialize any cached transient variables from the CMP fields.

The ejbStore method first calls the superclass EmployeeBean's ejbStore method. This allows the superclass to save any cached data to the CMP fields. After this, the ejbStore method stores the state of EmployeeBeanBMP by calling the storeRow helper method, which writes all the CMP fields to the database row representing the employee. For better performance, EmployeeBeanBMP should perform this database write only if the bean's CMP fields have been modified since the last time they were loaded. This optimization can be done by maintaining a flag in the EmployeeBeanBMP's instance variable that indicates whether the bean's state is "dirty" that is, changed. The flag needs to be set in every set method that modifies the bean's state.

An entity bean with bean-managed persistence must also implement the ejbPassivate and ejbActivate methods. Code Example 8.33 shows how EmployeeBeanBMP implemented these two methods:

Code Example 8.33 EmployeeBeanBMP ejbActivate and ejbPassivate Methods

 public void ejbActivate() {    employeeNumber = (Integer)entityContext.getPrimaryKey(); } public void ejbPassivate() {    // clear all CMP fields    employeeNumber = null;    firstName = null;    lastName = null;    birthDate = null; } 

The ejbActivate method is called when an entity bean instance is being associated with a specific primary key value. The EmployeeBeanBMP's ejbActivate method initializes the employeeNumber field to the instance's primary key value. This association step is very important because it allows subsequent methods, such as ejbLoad, to operate on the correct primary key. In fact, ejbActivate is typically called immediately before ejbLoad at the beginning of a transaction.

The ejbPassivate method is called when the container wants to reclaim the memory associated with a bean instance and return the bean instance to its pool. The ejbPassivate method clears the values of all employee-specific fields that is, the CMP fields. After the ejbPassivate method completes, the bean instance is no longer associated with an identity and, by calling ejbActivate, can be used to service a request on behalf of a different employee.

8.3.3 Payroll System

Prior to the deployment of Wombat's benefits application, Star Enterprise's payroll department developed a payroll application to give its enterprise applications access to payroll information. The payroll application consists of the PayrollEJB stateless session bean, described in Section 4.5, PayrollEJB Stateless Session Bean, on page 110. The payroll information is stored in PayrollDatabase, whose schema is described in Section 4.6.3, The Payroll Database, on page 123.

To integrate the PayrollEJB with the Benefits Enrollment application developed by Wombat, Star Enterprise's IT department develops an implementation of the DeductionUpdateBean command bean interface provided by Wombat. The deployer then sets the class name of this interface in the EnrollmentEJB's environment. This allows EnrollmentEJB to instantiate the DeductionUpdateBean implementation and use it to update the benefits deduction in Star Enterprise's payroll system.