Search Criteria Panel

We are finally ready to attack the front-end! In this section, we will use the AndroMDA Javaserver Faces cartridge to develop a JSF based web front-end.

The JSF cartridge generates javaserver Faces web pages from a UML model that defines the flow of your application. Before we get into modeling our application, please read the following material to understand fundamental concepts behind the jsf cartridge. The following links are related with the BPM4Struts cartridge but most of the concepts are similar to the concepts used in the JSF cartridge.

  1. Introduction to BPM4Struts: The Introduction and Goal sections provide a good overview of the cartridge.
  2. BPM4Struts How-to Guide: Quickly look over the concepts behind use-cases, activity graphs/state machines and controllers.

As you might have gathered, there are 3 important concepts associated with creating a web page: a use case, a state machine (or activity) diagram (that details the use case), and one or more controllers (whose methods can be called from the activity diagram). So let's discuss how we will model our search screen. We will start with a use case called Search Timecards. This use case is shown on the right and we have marked it with two stereotypes:

  1. FrontEndUseCase: which means exactly that - it is a front-end use case
  2. FrontEndApplication: which means that it is the application's entry point. Note that, for now, we won't worry about security or navigation -- as soon as you point your browser to this web application, it will show the Search Timecards page!

We will then add details to this use case by creating an state machine diagram. The state machine diagram is shown below:

The state machine diagram can use the SearchController shown below by calling its methods. The key parameter passed to SearchController methods is a form interface that provides access to HTTP request parameters. The SearchController can call services in the service layer. Specifically, we have shown here that it has access to the UserService.

Now let's enter the use case, the state machine diagram and the controller in our model. Please follow one of the links below to edit the model with the UML tool of your choice.

Now let's ask AndroMDA to generate code for the Search Timecards page:

  1. Execute the command mvn install -Peclipse in the Command Prompt (the -Peclipse is needed to update the project configuration in eclipse). Make sure you get a BUILD SUCCESSFUL message.

The only code we need to write by hand is the call from the SearchController to the UserService to populate the drop-downs. So open the SearchControllerImpl class generated at C:\timetracker\web\src\main\java\org\andromda\timetracker\web\timecardsearch. Add the code shown below:

// license-header java merge-point
// Generated by andromda-jsf cartridge (controllers\ControllerImpl.java.vsl) on 04/17/2011 08:25:41-0300
package org.andromda.timetracker.web.timecardsearch;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import org.andromda.timetracker.vo.UserVO;
import org.andromda.timetracker.vo.UserVOComparator;
/**
 * @see org.andromda.timetracker.web.timecardsearch.SearchController
 */
public class SearchControllerImpl
    extends SearchController
{
    /**
     * The serial version UID of this class. Needed for serialization.
     */
    private static final long serialVersionUID = -1584823295709314108L;
    private static final String ALL_STRING = "-- All --";
    /**
     * @see org.andromda.timetracker.web.timecardsearch.SearchController#populateSearchScreen(java.lang.Long submitter, java.lang.Long approver, java.util.Date startDateMinimum, java.util.Date startDateMaximum)
     */
    @Override
    public void populateSearchScreen(PopulateSearchScreenForm form)
    {
        // Get list of users and add the "All" option at the top
        Collection<UserVO> users = getUserService().getAllUsers();
        // Add the 'All' option at the top of the list, as a fake user
        List<UserVO> userList = new ArrayList<UserVO>(users);
        // Sorts the names
        Collections.sort(userList, new UserVOComparator());
        userList.add(0, new UserVO(null, ALL_STRING, null, null));
        // Populate submitter and approver dropdowns
        form.setSubmitterBackingList(userList, "id", "username");
        form.setApproverBackingList(userList, "id", "username");
    }
}
            

Note that we sort the users array so that names appear alphabetically in the drop-downs. The sorting function uses UserVOComparator, which is available under C:\timetracker-completed\common\src\main\java\org\andromda\timetracker\vo. Copy it to your solution using the same directory structure.

Now follow the steps below to build and deploy the application to JBoss and test it.

  1. Build the common and web projects to make sure the code added above is compiled and packaged. Here's how:
    mvn -f common/pom.xml install
    mvn -f web/pom.xml install
  2. Start the JBoss server. To do this, open a Command Prompt in the JBoss bin directory ( C:\Programs\JBoss\7\bin) and execute the command standalone.
  3. Deploy the application to the JBoss server. Copy timetracker.war from web\target to Jboss standalone\deployments directory. Look for JBoss console message indicating that the application has started.
  4. Open a browser and make it point to http://localhost:8080/timetracker. The TimeTracker search page should appear. Note that although the look and feel is not what we have in the prototype, the screen is functionally correct. We will worry about the look and feel later, when all the functionality is complete.
  5. Make sure that the submitter and approver drop downs are populated with the complete user list.

Below is a screen shot of the Search screen so far. Isn't it amazing that we were able to get all this functionality without much coding?

What's Next?

Congratulations! You have successfully deployed a complete vertical slice of the application that includes a front-end, middle-tier and a back-end. We are now ready start our second iteration with the goal to build the Search Results panel. Click here to start iteration 2.