Subdiagrams

When logic of the activity diagram gets complex, it is often useful to partition the logic, separating discrete units of logic into subdiagrams. Each subdiagram is associated with a particular main diagram.

Figure 38 illustrates a scenario in which the main activity diagram contains references to two subdiagrams, Retrieve Subdiagram and Delete Subdiagram.

Figure 38. Scenario with two subdiagrams


Note:
An iterator is a specialized form of subdiagram. All basic information about subdiagrams applies to iterators; for information that applies specifically to iterators, refer to "Iterators".

The activity diagrams in a scenario are hierarchically arranged. All subdiagrams and iterators in a scenario descend from the scenario's main activity diagram. Figure 39 illustrates this relationship. The activity diagram in which the subdiagram symbol appears is referred to as the parent diagram for the subdiagram.

Figure 39. Relationship of main diagram and subdiagrams


A subdiagram has access to all collaboration template properties and to all

scenario variables. Table 26 summarizes how a subdiagram differs from the main diagram.

Table 26. Comparison of main diagram and subdiagrams
Issue Main diagram Subdiagram
How it is created at design time Automatically created when you create a scenario Controlled by the subdiagram symbol in the parent diagram
Cause of execution at runtime Starts execution when the collaboration runtime environment hands it a triggering event Starts executing when the parent diagram's execution path leads to it; has no triggering event
What happens to unhandled or raised exception Passes to the collaboration runtime environment Passes to the parent diagram
Completion at runtime Returns to the collaboration runtime environment Returns to the parent diagram

Creating a subdiagram

To add a subdiagram to the activity diagram:

  1. In the Symbols toolbar, click the Subdiagram button.
  2. Click in an active activity diagram to place the subdiagram symbol.

    A unique identifier appears for the subdiagram in the scenario tree, hierarchically arranged under the parent diagram. The scenario tree displays the name in the following format:

    (UID)
     

    If you provide a label for the subdiagram, the scenario tree displays the name in the following format:

    label (UID)
     

    The UID is a unique identifier that is also the name of the subdiagram object in the scenario tree. As with UIDs for other symbols, you can choose whether or not to display the UID for the subdiagram. To turn on or off display of the UID, use the context menu on the scenarios node in the template tree.

  3. Double-click the subdiagram name in the scenario tree, or right-click its node in the diagram editor window and select Open Subdiagram.

    A new window displays in the Working Area in which to define a new activity diagram.

Like the main activity diagram, the subdiagram starts with a Start symbol and ends with an End Success symbol, and, optionally, one or more End Failure symbols. A subdiagram can contain all diagramming components, including subdiagrams and iterators.

Defining a subdiagram

After the subdiagram appears in the activity diagram, you can define its properties in the Subdiagram Properties dialog. The properties of a subdiagram are its label and description. All are optional.

To define subdiagram properties:

  1. Display the Subdiagram Properties dialog.

    You can display this dialog in any of the following ways:

  2. Optionally, specify the label and description for this subdiagram.

    The label makes the activity diagram more readable, by labeling the subdiagram with text that is more descriptive than the UID. The description field is a place for a comment, which describes the purpose of the subdiagram.

  3. Click Apply to save the subdiagram properties. Click Discard to clear the properties. Click Close to cancel this subdiagram definition.

Deleting a subdiagram

To delete a subdiagram, display its parent diagram or subdiagram and do the following:

  1. Select the symbol of the subdiagram to delete.
  2. Choose the Delete option from the Edit menu. Alternatively, you can click the DEL (Delete) key.

If the parent diagram is expanded in the scenario tree, the subdiagram name disappears from the scenario tree when it is deleted.

Handling subdiagram completion status

The execution of a parent diagram responds to the execution status of its subdiagrams. It is the subdiagram's developer who decides the subdiagram's completion status, as well as its exception-handling behavior. A collaboration can intentionally end a subdiagram in either of the following ways:

Handling successful subdiagram execution

The End Success termination node indicates that execution has completed successfully. When a subdiagram ends with an End Success node, the collaboration runtime environment ends the subdiagram and passes control to the parent diagram. The flow of the parent diagram proceeds to the next node after the subdiagram node. This next node is usually a decision node that tests the status of the subdiagram. This decision node can include any of the following branches to test if the subdiagram execution:

A subdiagram can end successfully in the following ways:

Note:
The developer can have a subdiagram end in success even if it encounters an exception, as long as it handles the exception. Successful completion means only that execution of the subdiagram reached an End Success symbol and that code was available to handle any exceptions that were raised.

For information on how to create a decision node, see Decision nodes. For more information on how to implement exception handling, see Handling exceptions.

Handling unsuccessful subdiagram execution

The End Failure termination node indicates that execution has not completed successfully. When a subdiagram ends with an End Failure node, the collaboration runtime environment ends the subdiagram as well as the entire collaboration. Control passes to the collaboration runtime environment, which makes an entry in the collaboration's log destination and creates an unresolved flow.

A subdiagram can end unsuccessfully in the following ways:

Whenever a subdiagram ends with the End Failure node, the collaboration runtime environment terminates the entire collaboration. For information on how to handle exceptions encountered in a subdiagram, see Successfully ending a subdiagram or iterator. For information on how the collaboration runtime environment creates unresolved flows, see Successfully ending the main diagram.

Copyright IBM Corp. 2003, 2004