Flux - The Smart Struts Config Generator
This guide explains what you need to know in addition to the general UML modelling concept if you use Rational Rose as your graphical front end to Flux.
Make sure you have an installation of a Rational Rose 2002 edition.
Install the Rational Rose add-in Chameleon that is packaged in the Flux distribution since Flux version 1.1.0 by executing %ECLIPSE_HOME%\plugins\de.matthias_burbach.flux4eclipse_%VERSION%\chameleon\Setup.exe and following the instructions of the install wizard. Please accept the suggested installation directory for Chameleon if possible. If you can't accept the suggested directory you must manually update the Windows registry entry that is made automatically during installation by adapting the respective path in the %CHAMELEON_INSTALL_PATH%\Chameleon.reg file and double-clicking the saved file afterwards (otherwise Rose will not find Chameleon).
If you have trouble with installing or using Chameleon and you don't need the multi-instance modelling feature you can do without Chameleon and still use the previous Rose model export solution based on the Unisys XMI add-in. To do so, download and install the Unisys XMI add-in that extends Rational Rose by an XMI export feature. Additionally, you need to patch the Flux configuration file de/matthias_burbach/flux/config/flux-config.xml in flux4eclipse.jar by replacing the model builder 'de.matthias_burbach.flux.ChameleonModelBuilder' with 'de.matthias_burbach.flux.XmiModelBuilder'.
Start Rational Rose or choose 'File/New'. If the 'Framework Wizard Add-In' is installed and activated, the 'Create New Model' dialog box is displayed. This dialog box displays a number of frameworks that can be used when creating a new model. Since you don't need a framework for Flux diagrams simply click 'Cancel' to create an 'empty' new model with only the default contents.
Save the new model file under a suitable name and folder. You may want to name the file workflow-<module>.mdl where <module> is the name of your Struts module that you model within this file.
Select the 'Logical View' folder in the 'Browser' view and select 'New / Activity Diagram' in the context menu.
You can now start sketching the workflow on this diagram by creating, labelling and connecting states, activities and transitions as described below.
If you put too many elements on one single diagram it becomes hard to manage and layout nicely. Therefore, you should distribute the whole workflow on several diagrams. Each of these diagrams could be centered around one page and show only activities and transitions up to all the other pages that can be directly reached by one request issued from the centered page. This leads to as many diagrams as there are pages in your model. If you follow this principle you may want to name each of these diagrams after the page it is centered around.
Click the state symbol on the 'Toolbox' view and then click on the diagram where you want to place the new state.
Name the state and afterwards double click it to open its specification dialog. Enter the word 'Page' in the combo box 'Stereotype'. If you entered this stereotype already for another state you can alternatively select it from the combo box.
If you want to reference a defined page mode variable from this page state simply extend the name of the page by ' (<Name of variable>)'.Display the stereotype in the page icon and keep the yellow default color (R: 255, G: 255, B: 204).
Click the activity symbol on the 'Toolbox' view and then click on the diagram where you want to place the new activity. Name the activity and afterwards double click it to open its specification dialog. Enter the word 'Action' in the combo box 'Stereotype'.
Display the stereotype in the activity icon and set the color to white.
Basically, the same as creating an action activity except that you use the stereotype 'Module' instead of 'Action'.
Additionally, you need to add the inner 'do'-action that determines the path to use on entering the module. To do so, go to the tab 'Actions' in the specification dialog and insert an action expression. Double click the inserted expression to open its detail dialog. Change the value in the 'When:' select box from the default 'On Entry' to 'Do' and enter the path in the 'Name:' field. The path must equal the path attribute of the targeted action mapping in the struts-config-<module>.xml except for the leading slash (and it must not end with '.do'!).
Display the stereotype in the activity icon and set the color to light blue (R:222, G:222, B:239).
Click the end state symbol on the 'Toolbox' view and then click on the diagram where you want to place the end state. An end state has no editable name or stereotype. Although Rose permits the creation of more than one end state you must create at most one such state per module model (but you may of course display it multiple times on multiple diagrams).
'End State' is just another name for 'Final State'.
Click the right mouse button on the selected folder 'Logical View' and select 'New Class'. Enter the name and the stereotype 'Variable' of the class in the specification dialog and add a private attribute for each value the variable can have. Don't specify the type of the attributes or anything else (just create their names).
Click the state transition symbol on the 'Toolbox' view and then click on the state or activity the transition is to emerge from. Keep the left mouse button pressed and draw to the mouse cursor away onto the target state or activity. Release the mouse button on the target state or activity.
If you want to add a transition that connects a page or an activity with itself you must use the self transition instead of the state transition symbol.
If your transition emerges from a page state you must add an event name. To do so double click the transition to open its specification dialog. Enter the name of the event in the field 'Event:'.
If your transition emerges from an activity you must add a guard condition. To do so double click the transition to open its specification dialog. Change to the tab 'Detail' and enter the guard condition in the field 'Guard Condition'.
If you want to explicitly set the value of a page mode variable on firing the transition set the expression '<Name of variable>=<Name of variable value<' into the field 'Action:' on the tab 'Detail:'.
If you only develop one fixed web application you create one model (per module) and generate one struts configuration (per module) from it and that's it as far as modelling is concerned. However, if you need to support a whole set of web applications which are customized variations of one basic web application framework, you have to create and maintain n UML models even if there is only the slightest difference in the page and action flow between any two of these variations. To overcome the resulting maintainability problem Chameleon is a tool that enables you to model one super model that contains the sum of all nodes and transitions of all model instances (which are practically only variations of always the same basic model) in only one Rose file!
Chameleon let's you define the differences and commonalities between the various instances of the same basic workflow model by optionally attributing each diagram element (page state, action activity, module activity, event transition, guarded transition) and the variable values representing attributes of classes the model a page mode variable with include or exclude rules. These rules state if such an element occurs within a specific instance of the super model or not.
If you want to specify that a certain diagram element or a variable value is only included in one or more explicitly enumerated model instances named i1, i2, ..., iN write the following line in the documentation property of the respective element:
incl=(i1, i2, ..., iN)
The names of the instances can be arbitrary strings, but you should use short and descriptive names, e. g. the short names of your web applications. Don't insert line breaks in the include directive because this will cause parsing problems.
If you want to specify that a certain diagram element or a variable value is excluded in one or more explicitly enumerated model instances named i1, i2, ..., iN write the following line in the documentation property of the respective element:
excl=(i1, i2, ..., iN)
There may be at most one include and at most one exclude rule per documentation property. If you add one include and one exclude rule to the same element Chameleon won't complain but use the following logic to decide whether the element is part of a chosen instance: element is member of instance if (include rule exists and instance is not included) or (exclude rule exists and instance is excluded). You are highly discouraged to combine an include and an exclude rule for the same element!
Include and exclude rules may coexist with other text in the same documentation property.
If you want to view the super model from the perspective of a single instance and see what's in and what's outside of the model instance at a glance select the menu item 'Tools/Chameleon/Apply Instance Color Scheme...'. A box will pop up letting you choose which instance to look at. If you click OK Chameleon will send all diagram elements which don't belong to the chosen instance visually to the 'background' by colorizing them pale grey (suggesting they are not active in the current context).
If you want to compare two instances of the super model and see what's only in one chosen instance, what's only in the other chosen instance, what's in both instances, and what's in none of the two chosen instances select the menu item 'Tools/Chameleon/Apply Comparison Color Scheme...'. A box will pop up letting you choose a 'red' instance and a 'blue' instance. If you click OK Chameleon will send all diagram elements which don't belong to any of the two chosen instances visually to the 'background' by colorizing them pale grey (suggesting they are not active in the current context), elements that are used by the red but not by the blue instance will appear in red and vice versa. Elements that are used by both instances will be drawn in black.
The menu item 'Tools/Chameleon/Apply Default Color Scheme' will reverse the effect and give back the stereotype dependent color to the previously greyed out elements. You can also use this function to correctly apply the default color scheme to the whole model with one click (instead of changing each element's color individually).
The color changing functions above will of course not modify the include and exclude rules in the documentation properties of elements. They just give a convenient and easily understandable view on things, thus retaining the unique value of diagram modelling when climbing the ladder from single- to mult-instance modelling.
There is always the implicit instance called <ANONYMOUS>. It is assembled from all elements that don't have an include rule. If you don't use include or exclude rules at all <ANONYMOUS> is your only instance and you practically don't use multi-instance modelling (because you obviously don't need it).
Save your Rose model and then select the export menu command 'Tools/Chameleon/Export Instance Model...'. Choose the instance to export and click 'OK'.
Save the export file in the same folder your struts-config-<module>.xml file resides in and name the file 'chm-<module>.xml'. This way Flux will automatically associate this Chameleon file with the respective struts-config-<module>.xml.
Chameleon will only export elements that are part of the chosen instance as defined by include and exclude rules. You can check what will be exported by applying the instance color scheme. Everything that is not turned to grey for the chosen instance will be exported. Make sure the respective sub set is a valid model (especially watch out for dangling transitions and non-deterministic transition ambiguities).
Save your Rose model and then select the export command of the XMI add-in in the menu 'Tools'. Accept the default options and click 'OK'.
Save the XMI export file in the same folder your struts-config-<module>.xml file resides in and name the file 'xmi-<module>.xml'. This way Flux will automatically associate this XMI file with the respective struts-config-<module>.xml (provided you changed the model file pattern in the Flux preferences from chm-%MODULE%.xml to xmi-%MODULE%.xml).
Don't create or keep anything in a model file that doesn't belong to the current workflow which is subject to Flux generation. Don't create packages, only work in the State/Activity Model of the Logical View. Don't go to the Use Case View, the Component View or the Deployment View.
Be aware of the difference between deleting an icon or a transition from a diagram (Del key) and deleting it from the model (Ctrl-D key). It is particularly easy to miss a transition that shouldn't be in the model anymore but which still exists because you just removed it from the diagrams but not from the model. In contrast to states and activities you cannot see these zombie transitions in the model tree.
You can, for example, detect those zombies by applying the function 'Query/Filter Transitions' to your current diagram. Rose then re-adds zombie transitions if their source and their target icon are both in the diagram.
Alternatively, you can check the tab 'Transitions' in the specification dialog of an icon and double click the transitions listed their to see their identifying event name or guard condition.