6
Interaction Between Clients and Business Logic Objects

Previous chapters describe the JSP client files and the business logic objects. This chapter describes how these objects interact with each other: it shows how the JSP files access objects and retrieve data from the objects.

Contents of this chapter:

6.1 Client Interface to Business Tier Objects

Although some methods in the business tier objects are declared public, client tier objects (that is, the JSP files) should access only some of these objects and methods. The methods are declared public so that other business tier objects can invoke them.

JSP files do not invoke methods on the Employee bean or the BenefitCatalog bean directly. Instead, the files invoke methods on an EmployeeManager bean, and these methods invoke methods on the Employee or BenefitCatalog objects. The EmployeeManager class has methods to execute the business logic operations. See Section 4.7, "EmployeeManager (Stateless Session Bean)" for details.

To get a reference to the EmployeeManager bean, the JSP files reference the SessionHelper class, which is a "regular" Java class. The SessionHelper class contains the getEmployeeManager static method which returns an instance of EmployeeManager. The SessionHelper class instantiates and stores the session bean in an attribute of HttpSession class. For example:

// from addBenefitToEmployee.jsp
<%
  int empId = Integer.parseInt(request.getParameter(
                             SessionHelper.EMP_ID_PARAMETER));
  EmployeeManager mgr = SessionHelper.getEmployeeManager(request);
  Collection unelected = mgr.getUnelectedBenefitItems(empId);
  ...
%>

6.2 Query Employee Operation

Typically, the user accesses the application through a link on an external page. The link's URL looks like this:

http://<host>/empbft/controller?action=queryEmployee

The user then sees the ID page (Figure 2-1).

6.2.1 High-Level Sequence

Figure 6-1 diagrams the query operation. The numbers in the figure correspond to the steps that follow the figure. This figure covers requests from browsers only. See Section 7.5.1, "Query Operation" for requests from wireless clients.

Figure 6-1 Query Operation

Text description of da_clie7.gif follows

Text description of the illustration da_clie7.gif

B1: The Controller servlet handles the request to the application.

B2: The value of the action parameter is queryEmployee, so the Controller invokes the performAction method in the QueryEmployee class.

B3: The performAction method forwards the request to the queryEmployee.jsp file, which displays an ID page (Figure 2-1).

B4: The user then enters an employee ID and clicks Query. The request still has the same value in the action parameter (queryEmployee), but it also has an employee ID parameter. The request is again handled by the QueryEmployee class.

B5: The performAction method in the QueryEmployee class and the queryEmployee.jsp file validate the employee ID entered by the user.

B6: For valid employee IDs, the JSP file queries the database to retrieve data for the specified employee ID.

6.2.2 Querying the Database and Retrieving Data

To get employee details, queryEmployee.jsp invokes the getEmployeeDetails(employeeId) method in EmployeeManager. The method returns an EmployeeModel object, which contains the data. The JSP then retrieves values from the EmployeeModel object to display the employee data.

// from queryEmployee.jsp
<%
   ...
   int id = Integer.parseInt(empId);
   EmployeeManager mgr = SessionHelper.getEmployeeManager(request);
   EmployeeModel emp = mgr.getEmployeeDetails(id);
   ...
%>
...
<h4>Employee Details</h4>
<table>
<tr><td>Employee ID: </td><td colspan=3><b><%=id%></b></td></tr>
<tr><td>First Name: </td><td><b><%=emp.getFirstName()%></b></td><td>Last Name: 
</td><td><b><%=emp.getLastName()%></b></td></tr>
<tr><td>Email: </td><td><b><%=emp.getEmail()%></b></td><td>Phone Number: 
</td><td><b><%=emp.getPhoneNumber()%></b></td></tr>
<tr><td>Hire Date: 
</td><td><b><%=emp.getHireDate().toString()%></b></td><td>Job: 
</td><td><b><%=emp.getJobId()%></b></td></tr>
</table>

The getEmployeeDetails method in EmployeeManager starts off the following sequence:

It calls getEmployee to get an instance of the desired employee.
getEmployee invokes findByPrimaryKey on the Employee class. This calls ejbFindByPrimaryKey in EmployeeBean.
ejbFindByPrimaryKey calls findByPrimaryKey in EmployeeDAOImpl, which returns an int.
This int enables the EJB container to return an Employee bean from findByPrimraryKey, as declared in the Employee home interface.
Note that findByPrimaryKey in the Employee class is a special method. When you invoke this method, the EJB container automatically calls ejbLoad for you. ejbLoad calls load in EmployeeDAOImpl, which returns an EmployeeModel. This is used to populate the m_emp class variable.
getEmployeeDetails then calls getDetails with the Employee bean returned from step 1.
getDetails returns an EmployeeModel to the JSP.

Figure 6-2 getEmployeeDetails

Text description of the illustration da_clieb.gif

6.2.3 findByPrimaryKey Method

The EmployeeBean class implements the ejbFindByPrimaryKey(int empId) method. This method calls the EmployeeDAOImpl class to retrieve data from the database.

// from EmployeeBean.java
public Integer ejbFindByPrimaryKey(int empId) throws FinderException
{
    try {
      if (m_dao == null) m_dao = new EmployeeDAOImpl();
      Integer findReturn = m_dao.findByPrimaryKey(empId);
      return findReturn;
    } catch (Exception e) {
      throw new FinderException ("\nSQL Exception in find by primary key.\n"
        + e.getMessage());
    }
}

In the EmployeeDAOImpl class the findByPrimaryKey(int id) method queries the database for the specified employee ID. It executes a SELECT statement on the database and returns the employee ID if it finds an employee. If it does not find an employee, it throws an exception.

6.2.4 Getting Benefit Data

For benefit data, where a user can have more than one benefit, the application iterates over the Collection.

// from queryEmployee.jsp
<h4>Elected Benefits</h4>
<table>
  <%
    Collection benefits = emp.getBenefits();
    if (benefits == null || benefits.size() == 0) {
  %>
      <tr><td>None</td></tr>
  <%
    } else {
      Iterator it = benefits.iterator();
      while (it.hasNext()) {
        BenefitItem item = (BenefitItem)it.next();
  %>
        <tr><td><%=item.getName()%></td></tr>
  <%
      } // end of while
    } // end of if
  %>
</table>

Figure 6-3 Sequence Diagram for Query Employee

Text description of the illustration query.gif

6.3 Add and Remove Benefit Operations

For the add and remove operations, the JSPs send which benefit to add or remove, plus the employee ID, to the EmployeeManager. The EmployeeManager adds or removes the benefit and returns the status of the operation.

The add and remove benefits operations follow similar sequences in presenting a list of benefits to the user, and executing the add or remove operation on the database.

To add benefits, the user clicks the Add Benefit link on the Info page (Figure 2-1). The URL behind this link looks like:
```
<a href="/empbft/controller?empID=<%=id%>&amp;action=addBenefitToEmployee"> 
Add benefits to the employee</a>
```
To remove benefits, the user clicks the Remove Benefit link on the Info page (Figure 2-1). The URL behind this link looks like:
```
<a href="/empbft/controller?empID=<%=id%>&amp;action=removeBenefitFromEmployee"> 
Remove benefits from the employee</a>
```

See the following sections for details on the add and remove operations.

6.4 Add Benefit Operation

6.4.1 High-Level Sequence of Events

Figure 6-4 shows the events that occur when a user selects the add benefit option:

Figure 6-4 Add Benefits Operation

Text description of da_clie5.gif follows

Text description of the illustration da_clie5.gif

The Controller servlet handles the request first. It gets the value of the action parameter (addBenefitToEmployee) and invokes the performAction method in the corresponding class, AddBenefitToEmployee.
The performAction method checks the value of the benefits parameter. It is null at first, so it forwards the request to addBenefitToEmployee.jsp (or addBenefitToEmployeeWireless.jsp). The JSP displays a list of benefits that the user can add. See Section 6.4.2, "Getting Benefits That the User Can Add".
The user selects the desired benefits to add and submits the request. The action parameter in the request still has the same value (addBenefitToEmployee), but this time, it has a benefits parameter that specifies which benefits to add.
The Controller invokes the AddBenefitToEmployee class to process the request. The class sees that the benefits parameter is not null, and it calls the addBenefits method in the Employee class to add the benefits. See Section 6.4.3, "Updating the Database".

6.4.2 Getting Benefits That the User Can Add

To show a list of benefits that the user can add, the addBenefitToEmployee.jsp page gets a list of benefits that the user does not have. The JSP file gets an instance of EmployeeManager, then invokes the getUnelectedBenefitItems method.

// from addBenefitToEmployee.jsp
<%
  int empId = Integer.parseInt(request.getParameter(
                                 SessionHelper.EMP_ID_PARAMETER));
  EmployeeManager mgr = SessionHelper.getEmployeeManager(request);
  Collection unelected = mgr.getUnelectedBenefitItems(empId);
  ...
%>

The getUnelectedBenefitItems method gets the master list of all benefits from BenefitCatalog, then it gets a list of benefits for the employee. It compares the two lists and returns a list of benefits that the employee does not have.

// from EmployeeManagerBean.java
public Collection getUnelectedBenefitItems(int id) throws RemoteException
{
    Collection allBenefits = null;
    InitialContext initial = new InitialContext();
    Object objref = initial.lookup(AppJNDINames.BENEFIT_CATALOG_EJBHOME);
    BenefitCatalogHome home = (BenefitCatalogHome)
          PortableRemoteObject.narrow(objref, BenefitCatalogHome.class);
    BenefitCatalog catalog = home.create();
    allBenefits = catalog.getBenefits();

    // ... exceptions omitted ...

    Collection unelected = new ArrayList();
    EmployeeModel emp = this.getEmployeeDetails(id);
    ArrayList eb = (ArrayList) emp.getBenefits(); 
    if (eb != null && !eb.isEmpty()) {
      Iterator i = allBenefits.iterator();
      while (i.hasNext()) {
        BenefitModel b = (BenefitModel)i.next();
        if (Collections.binarySearch(eb, b) < 0)
          unelected.add(b);
      }
      return unelected;
    }
    return allBenefits;
}

6.4.3 Updating the Database

To add the benefits the user selected, the AddBenefitToEmployee object gets the Employee object and executes the addBenefits method:

// from AddBenefitToEmployee.java
String benefits[] = req.getParameterValues(SessionHelper.BENEFIT_PARAMETER);
...
int benefitIDs[] = new int[benefits.length];
for (int i = 0; i < benefits.length; i++) {
   benefitIDs[i] = Integer.parseInt(benefits[i]);
}
int empId = Integer.parseInt(req.getParameter(SessionHelper.EMP_ID_PARAMETER));
EmployeeManager mgr = SessionHelper.getEmployeeManager(req);
try {
   Employee emp = mgr.getEmployee(empId);
   emp.addBenefits(benefitIDs);
} catch (RemoteException e) {
   throw new ServletException (
          "\nRemote exception while getting employee and adding benefits.\n" 
          + e.getMessage());
}
forward(req, res, wireless ? "/successWireless.jsp" : "/success.jsp");

The addBenefits method in the Employee object uses the EmployeeDAOImpl class to connect to the database.

// from EmployeeBean.java
public void addBenefits(int benefits[])
{
    try{
      if (m_dao == null) m_dao = new EmployeeDAOImpl();
      m_dao.addBenefits(m_emp.getId(), benefits);
      ejbLoad();
    } catch (Exception e) {
      throw new EJBException ("\nData access exception in adding benefits.\n" 
        + e.getMessage());
    } 
}

After adding the benefits in the database, the addBenefits method calls the ejbLoad method to synchronize the Employee bean with the data in the database.

The addBenefits method in EmployeeDAOImpl connects to the database and sends an INSERT statement.

Figure 6-5 Sequence Diagram for Adding Benefits

Text description of the illustration add.gif

6.5 Removing Benefit Operation

6.5.1 High-Level Sequence of Events

Figure 6-6 shows the events that occur when a user selects some benefits to remove and clicks the Submit button.

Figure 6-6 Remove Benefits Operation

Text description of da_clie6.gif follows

Text description of the illustration da_clie6.gif

The Controller servlet handles the request first. It gets the value of the action parameter (removeBenefitFromEmployee) and invokes the performAction method in the corresponding class, RemoveBenefitFromEmployee.
The performAction method checks the value of the benefits parameter. It is null at first, so it forwards the request to removeBenefitFromEmployee.jsp (or removeBenefitFromEmployeeWireless.jsp). The JSP displays a list of benefits that the user can remove. See Section 6.5.2, "Getting Benefits That the User Can Remove".
The user selects the desired benefits to remove and submits the request. The action parameter in the request still has the same value (removeBenefitFromEmployee), but this time, it has a benefits parameter that specifies which benefits to remove.
The Controller invokes the RemoveBenefitFromEmployee class to process the request. The class sees that the benefits parameter is not null, and it calls the removeBenefits method in the Employee class to remove the benefits. See Section 6.4.3, "Updating the Database".

6.5.2 Getting Benefits That the User Can Remove

To get a list of benefits that the user can remove, the removeBenefitFromEmployee.jsp gets an EmployeeModel, which contains all the data for an employee, then it calls the getBenefits method in EmployeeModel. It then iterates through the list to display each benefit.

<%
  int empId = Integer.parseInt(request.getParameter(
                              SessionHelper.EMP_ID_PARAMETER));
  EmployeeManager mgr = SessionHelper.getEmployeeManager(request);
  Collection elected = mgr.getEmployeeDetails(empId).getBenefits();
  if (elected == null || elected.size() == 0) {
%>
<h4>No Benefits to Remove</h4>
<p>The employee has not elected any benefits.</p>
<h4>Actions</h4>
<a href="./controller?action=queryEmployee&amp;empID=<%=empId%>">Query the same 
employee</a><br>
<a href="./controller?action=queryEmployee">Query other employee</a><br>
<a href="./">Home</a><br>
<%
  } else {
%>
<h4>Select Elected Benefits</h4>
<%
    Iterator i = elected.iterator();
    while (i.hasNext()) {
        BenefitItem b = (BenefitItem) i.next();
%>
<input type=checkbox name=benefits value=<%=b.getId()%>><%=b.getName()%><br>
<%
    } // End of while
%>
<h4>Actions</h4>
<input type=submit value="Remove Selected Benefits">
<input type=hidden name=empID value=<%=empId%>>
<input type=hidden name=action
          value=<%=SessionHelper.ACTION_REMOVE_BENEFIT_FROM_EMPLOYEE%>>
<%
  } // End of if
%>

6.5.3 Updating the Database

To remove the benefits the user selected, the RemoveBenefitFromEmployee object gets the Employee object and executes the removeBenefits method:

// from RemoveBenefitFromEmployee.java
String benefits[] = req.getParameterValues(SessionHelper.BENEFIT_PARAMETER);
String client = req.getParameter(SessionHelper.CLIENT_TYPE_PARAMETER);
boolean wireless = client != null && 
                client.equals(SessionHelper.CLIENT_TYPE_WIRELESS);
if(benefits == null) {
   forward(req, res, wireless ?
           "/removeBenefitFromEmployeeWireless.jsp" :
           "/removeBenefitFromEmployee.jsp");
} else {
   int benefitIDs[] = new int[benefits.length];
   for (int i = 0; i < benefits.length; i++) {
      benefitIDs[i] = Integer.parseInt(benefits[i]);
   }
   int empId = Integer.parseInt(req.getParameter(
                                 SessionHelper.EMP_ID_PARAMETER));
   EmployeeManager mgr = SessionHelper.getEmployeeManager(req);
   try {
      Employee emp = mgr.getEmployee(empId);
      emp.removeBenefits(benefitIDs);
   } catch (RemoteException e) {
      throw new ServletException (
        "Remote exception while getting employee and removing his/her
            benefits." + e.getMessage());
   }
   forward(req, res, wireless ? "/successWireless.jsp" : "/success.jsp");
}

The removeBenefits method in the Employee object uses the EmployeeDAOImpl class to connect to the database.

// from EmployeeBean.java
public void removeBenefits(int benefits[])
{
   try {
      if (m_dao == null)  m_dao = new EmployeeDAOImpl();
      m_dao.removeBenefits(m_emp.getId(), benefits);
      ejbLoad();
    } catch (Exception e) {
      throw new EJBException ("\nData access exception in removing benefits.\n" 
        + e.getMessage());
   } 
}

After removing the benefits from the database, the removeBenefits method calls the ejbLoad method to synchronize the Employee bean with the data in the database.

The removeBenefits method in EmployeeDAOImpl connects to the database and sends a DELETE statement.

Figure 6-7 Sequence Diagram for Removing Benefits

Text description of the illustration remove.gif

6 Interaction Between Clients and Business Logic Objects