Create Search Timecards Use Case

This page provides directions to create the Search Timecards use case along with its state machine diagram and the SearchController. Note that all three elements mentioned here will be placed in the package org.andromda.timetracker.web.timecardsearch.

Let's start by creating the Search Timecards use case.

  1. Create a package under the timetracker model by right-clicking on it in the containment tree and selecting New Element > Package. Name this new package Use Cases because we will create our use case diagrams here.
  2. In the Use Cases package, create a use case diagram by right clicking on it and selecting New Diagram > Use Case Diagram. Type in the name Application Use Cases for this diagram and press Enter
  3. In the toolbar on the left of the use case diagram click on the Use Case icon. Now click anywhere inside the diagram. A new use case will be created. Type the phrase "Search Timecards" to name the use case. Note that the use case is created under the Use Cases package in the containment tree. This is not the final location of the use case, but we will move later to the correct location.
  4. Right click on the use case and give it two stereotypes as discussed earlier: FrontEndUseCase and FrontEndApplication.

Now lets create the package org.andromda.timetracker.web.timecardsearch which is the final destination of our front-end elements.

  1. Create a package called web under org.andromda.timetracker.
  2. Create a package called timecardsearch under web.
  3. Drag the Search Timecards use case under the timecardsearch package.
  4. Right-click on the Search Timecards use case and choose New Diagram > State Machine Diagram to create an state diagram. Name it Search Timecards State Machine. This action automatically creates a state machine in the Search Timecards use case and associates the created state diagram to the state machine.
  5. Now create a class called SearchController under the Search Timecards State Machine state machine. Do this by right-clicking on Search Timecards State Machine, choose New Element > Class.

We are done with the basic structure for the web page. Now let's create the page flow on the Search Timecards State Machine diagram. Open this diagram and follow the steps below. Use the tool bar on the left to create various elements on the diagram. Use the tool tips and the status bar to identify the tool bar icons.

  1. Create an Initial State at the top.
  2. Drop a state below it. Double-click on the newly created state and type Populate Search Screen as the name for this state.
  3. Create a transition from the initial state to the Populate Search Screen state.
  4. Drop another action state below Populate Search Screen. Name it Search Timecards. Since this state represents a screen, give it the stereotype of FrontEndView.
  5. Create a transition from Populate Search Screen to Search Timecards and another in the reverse direction. In other words, the use case simply switches between the two states - of course, most of the time it stays in the Search Timecards state, waiting for user input.
  6. Right click on the transition out of Search Timecards and open its specification.
  7. Find the sub-panel Effect
  8. Specify Activity as the type of behavior of the effect.
  9. Enter the word search in the name field.

The effect modeled on the transition out of Search Timecards will make AndroMDA render a form in the Search Criteria panel. This form will submit 5 parameters to server: submitter, approver, start date minimum, start date maximum and status. Follow the steps below to specify these parameters.

  1. Right click on the Behavior Element field and open its specification.
  2. Click on the Parameters tab.
  3. Click Create to add the first parameter. Enter submitter as the name of the parameter and Long as its type (note that it is Long, not long). Set its Multiplicity to 0..1 (this way it will not be required). Now click on the Tag Values tab and click on the tagged value named andromda_presentation_web_view_field_type. This tagged value tells AndroMDA what type of field submitter is. Since submitter is a drop-down box, i.e. selection, we need to set the value of this tag to select. To do this, click the Create Value button. The value is shown in the right panel. Select select and click Back.
  4. Add the second parameter called approver with type of Long and Multiplicity set to 0..1. Again set the tagged value andromda_presentation_web_view_field_type to select.
  5. Add the third parameter called startDateMinimum with type of Date and Multiplicity set to 0..1.
  6. Add the fourth parameter called startDateMaximum with type of Date and Multiplicity set to 0..1.
  7. Add the fifth parameter called status with type of TimecardStatus and Multiplicity set to 0..1. Set the tagged value andromda_presentation_web_view_field_type to select.
  8. Click Close to dismiss the dialog box.

We are now almost done with our activity diagram except for one thing. The state machine still has to call the SearchController to populate the submitter and approver drop-downs. To do this we will first specify a method on SearchController called populateSearchScreen(). Follow the steps below to add this method:

  1. In the containment tree, right-click on SearchController and select New Element > Operation.
  2. Enter populateSearchScreen as the name of the operation.
  3. Double-click on the operation to open the Operation Specification dialog.
  4. Specify the return type as void.
  5. Click on the Parameters tab.
  6. Add the same 5 parameters that you added to the effect above - the names and types should match exactly. But don't add the tag values. That's how AndroMDA knows how to call the controller method.
  7. Tips & Tricks: You can simply copy the four parameters from search activity to the populateSearchScreen operation. To do this:
    1. Right-click on the Search transition Select in Containment Tree, expand the tree until expose the parameters of the search activity. Select the four parameters and copy them (Ctrl + C).
    2. Select the populateSearchScreen operation and paste the parameters (Ctrl + V).
    3. Right click on the submitter parameter, select Stereotype, Clear All and finallyApply. This will remove their stereotype thus their tag value. Repeat the same action on the approver parameter.

Now that we have an appropriate controller method, let's call it from the state machine diagram.

  1. Right-click on the Populate Search Screen state and open its specification.
  2. Find the sub-panel Entry
  3. Specify Activity as the type of behavior of the entry.
  4. Right click on the Behavior Element field and open its specification.
  5. Name it Call populateSearchScreen()
  6. Click on the Node editing area. A + and a - symbol will appear. Click on the +. Select Call Operation Action
  7. By clicking on ... in the operation field, a dialog box will appear. Select the populateSearchScreen() method and clickClose.
  8. Click Close to dismiss the dialog box.

There is just one more thing left. The SearchController needs to be able to call the service layer to get the list of users. To add this capability, we need to create a dependency from the SearchController to the UserService.

  1. Open the Services diagram in the service package.
  2. From the Containment Tree on the left, drag the SearchController class on to the diagram.
  3. Draw a dependency from SearchController to UserService.

We have now completely modeled the Search Criteria panel. Save your model, and export it, as usual.

Please go back to the main tutorial page and continue from where you left off.