Initial States

Each use-case needs an initial state, an initial state is displayed as a solid black disc. It denotes the starting point of the use-case, it can have no incoming transitions and only one outgoing transition. Only a single initial state is allowed per activity graph.

Since our example features only one use-case it will therefore contain exactly one initial state.

Action States

An action state represents a certain state in which the application can be recorded, an action state is displayed as a rectangle with rounded corners. In bpm4struts you will use action states for both server-side states (the controller: struts actions) as client-side states (the view: JSP, VTL, ...).

Make sure the actual name property of each action state is unique in the activity graph. Additionally, make sure the name is properly entered: sometimes people enter the action state's label in the activity diagram instead of the real name of the element.

Client-side action states are tagged with the <<FrontEndView>> stereotype, they represent a JSP and may have multiple outgoing transitions (one per call to the server).

Server-side action states do not need any stereotype but can only have a single outgoing transition.

Most of the time you'll want exactly a single outgoing transition for your server-side action states, but in a few cases it is required to take full control of the process flow, meaning you don't want to have the application forward to the next resource. In this case simply don't model an outgoing transition, the Struts action class will return null. Don't forget to write to the HTTP response yourself, you can do this is you defer to a controller operation in your action state.

You'll want to make use of this feature when you want an action returning a dynamically generated report such as a PDF.

Transitions

Transitions are used to interconnect the different states in the activity graph, they make up the actual process logic.

A few tagged values exist for transitions coming out of <<FrontEndView>> action states, please see this page to learn more about them: profile.html.

Using these tagged values a transition may be marked to carry a message to the (indirectly) targeted <<FrontEndView>> action state:

• andromda_struts_action_success_message: Write a message that will be displayed in a green box. This message will be stored into the default resource bundle.
• andromda_struts_action_warning_message: Write a message that will be displayed in a yellow box. This message will be stored into the default resource bundle.

It is possible to model exceptions to the process logic, in doing so you express how the system should behave in case something goes wrong. You just need to add the <<FrontEndException>> stereotype to the transition and you're good. Additionally you can add a tagged value to such a transition in order to refine the exception handling: andromda_struts_exception_type needs the fully qualified classname of the exception to be handled by this transition, others will be ignored; the default value if not specified is java.lang.Exception meaning all exceptions will be handled.

The default exception handling strategy is to return to the source page on which the exception has been triggered.

Event Parameters

Event parameters are parameters modeled on transitions exiting client-side action states (the ones with the <<FrontEndView>> stereotype). Whenever you model such a transition it represents a call to the server from a webpage, usually by submitting a form. The parameters you model will represent the form fields.

Please note that you will need to add the parameters to the transition's trigger, this trigger should be of type 'signal', but don't worry about that if your UML tool does not support setting the type of the trigger.

Different tagged values exist to control the generation of the type of the event parameter.

andromda_struts_view_field_radio=7
andromda_struts_view_field_radio=cd,dvd,book,hardware

Page Variables

Page variables are modeled the same way event parameters are, the only difference is that you model them on transitions entering a <<FrontEndView>> action state. In doing so the modeled parameters will be available in the generated JSP page.

Page variables can be rendered in tabular format, this is an advanced feature which is explained in more depth on this page: Tables.

Decision Points

In some cases action states and transitions just aren't enough, a good example is when you want to fork the flow based on a specific decision. Suppose you want to follow the first transition if the user login credentials are valid, and follow the second transition if they are invalid.

In order to do this we must need to be able to call an operation with a return value, on which the decision is based. We will see how to do this later, click here to proceed there now: Custom Code.

Finally we must tag the transition indicating when it must be followed, in UML this is done by means of guards. Not to make things overly complex it is not necessary to model the OCL for the guard (very few tools properly support this), so instead it will be sufficient to model the name of the guard, it must match the return value of the method call (matching is done using String.valueOf(returnValue)).

Some modeling tools do not properly show the name of the guard in the activity diagram, in that case you might consider copying the name also in the guard's body, this will be ignored by the cartridge and might show it on screen for clarity.

Final States

You may have as many final states as you want in an activity graph. In bpm4struts a final state represents the end of the use-case and the flow into the next use-case. Final states are displayed as bulls-eyes in activity diagrams.

There are two ways of modeling a final state: either you give it the name of the next use-case (which can be the same as the current use-case), either you do not name it and you use a hyperlink to the next use-case (this is not supported in all UML tools).

Sending parameters across use-cases

Sometimes it can happen that you would like to send parameters from one use-case into another use-case. This is easy with the bpm4struts cartridge: just model the parameters on an action leading into a final state and the parameters will automagically be available in the target use-case.

This is the first use-case

This is the second use-case

Respect the fact that use-cases are supposed to be loosely coupled: do not assume incoming parameters to always be present and check for null, this will improve your application's robustness.

JSP pages

Each action state carrying the <<FrontEndView>> stereotype will result in the generation of a JSP page. If you have properly modeled your use-case then these pages will contain already everything to have a working application: forms, buttons, hyperlinks, a menu, breadcrumbs, an online help, client validation, server calls, security ...

The generated JSP pages comply to the JSP 2.0 specification, as found in J2EE 1.4.

Struts Actions/Forms

For each transition modeled exiting either an initial state or an action state with the <<FrontEndView>> stereotype the cartridge will generate a Struts Action class and a Struts Form class. The parameters modeled on the transition's signal event will make up the fields that go into the form.

The generated struts-config.xml descriptor will contain a form-bean entry per generated Form. Here's an example:

<form-beans>
    ...
    <form-bean
        name="purchaseItemsEnterUserDetailsPurchaseForm"
        type="my.onlinestore.purchase.EnterUserDetailsPurchaseForm" />
    ...
</form-beans>

Each action will have a corresponding action-mapping entry, like this:

<action-mappings>
    ...
    <action
        path="/PurchaseItems/EnterUserDetailsPurchase"
        type="my.onlinestore.purchase.EnterUserDetailsPurchase"
        name="purchaseItemsEnterUserDetailsPurchaseForm"
        scope="request"
        input="/my/onlinestore/purchase/enter-user-details.jsp"
        unknown="false"
        validate="true">
        <exception
            type="java.lang.Exception"
            key="purchase.items.enter.user.details.exception"
            path="/my/onlinestore/purchase/enter-user-details.jsp"
            scope="request" />
        <forward
            name="purchase.items"
            path="/PurchaseItems/PurchaseItems.do"
            redirect="false" />
    </action>
    ...
</action-mappings>

A Struts action class and associated form is generated per sequence of transitions between two <<FrontEndView>> action states. The form fields are determined by the parameters modeled on the transitions, for maximum usability some parameters from neighbouring actions might also be included, but we'll not get into this just yet.

The action class has a private method for each different state it encounters, those methods might delegate control to a controller operation, this is explained here. A code fragment taken from the online-store sample is shown below, it contains a single action state deferring control to the loadItems controller operation. Please notice exception handling is taken care of. Such methods start with an underscore not to cause naming conflicts with existing Struts Action methods.

private ActionForward _loadItemsForSale(
        ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response)
    throws Exception
{
    ActionForward forward = null;

    final org.apache.struts.action.ActionMessages errors = this.getExceptionHandlerErrors(request);
    try
    {
        if (this.errorsNotPresent(request))
        {
            PurchaseControllerFactory.getPurchaseControllerInstance().loadItems(
                mapping, (EnterNameAndPasswordProceedForm)form, request, response);
        }
        if (this.errorsNotPresent(request))
        {
            forward = _promptUserWithItemList(mapping, form, request, response);
        }
    }
    catch (Exception ex)
    {
        final String messageKey = PatternMatchingExceptionHandler.instance().handleException(ex);
        errors.add(ActionMessages.GLOBAL_MESSAGE, new ActionMessage(messageKey));
    }
    finally
    {
    }
    if (!errors.isEmpty())
    {
        forward = mapping.getInputForward();
    }
    return forward;
}

Action classes and action forms, and struts-config.xml too for that matter, are never manually edited when using AndroMDA.

Screenshots

The screenshots shown here are taken from the Online-Store sample, which is part of the AndroMDA distribution, for more information on the samples please go here.

	(Larger View) This screenshot shows a typical custom login screen, note how the passwords are masked using asterisks. The password confirmation is also automatically rendered into the page using JavaScript (server-side validation will also be performed). The tooltip is shown when hovering over an input field, in this case the password field. Also notice the online-help link at the bottom of the screen.
	(Larger View) Another screen showing some different types of input fields, depending on the type of the expected input (integer, date, email, creditcard, url, ...) a specific validation will be performed to make sure the user does not needlessly call the server. This validation makes use of the Struts validation framework.
	(Larger View) This screen is what you see when you click on the online-help link: a list of actions, input fields and corresponding documentation. What you see here is (like everything else in this how-to) 100% generated by the cartridge, information can be added on the corresponding element in the UML model.
	(Larger View) Did you notice the little calendar icon next to the date input field ? If you click it you will get a popup like this from which the date can be selected. Depending on the desired input format it will be formatted correctly.