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
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
To add a subdiagram to the activity diagram:
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.
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.
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:
You can display this dialog in any of the following ways:
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.
To delete a subdiagram, display its parent diagram or subdiagram and do the following:
If the parent diagram is expanded in the scenario tree, the subdiagram name disappears from the scenario tree when it is deleted.
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:
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:
If the collaboration's execution is in the Normal state, the collaboration runtime environment evaluates the conditions of any normal branches. The default branch executes if no other normal branches evaluate to true.
If the collaboration's execution is in the Exception state, the collaboration runtime environment evaluates the conditions of the exception branches.
A subdiagram can end successfully in the following ways:
The collaboration's execution is in the Normal state. When control passes to the parent diagram and the parent diagram's next node is a decision node, the collaboration runtime environment evaluates any normal branches.
The collaboration's execution is in the Normal state. When control passes to the parent diagram and the parent diagram's next node is a decision node, the collaboration runtime environment evaluates any normal branches.
In this case, the collaboration's execution is in the Exception state. When control passes to the parent diagram and the parent diagram's next node is a decision node, the collaboration runtime environment evaluates any exception branches. The exception branch should lead to an action node that handles the exception. The best way to handle the exception is to raise it again and include the exception text as the reason for the exception.
In a collaboration with multiple levels of activity diagrams, you must explicitly use the raiseException() method to raise an exception up through each level in the activity diagram to provide the original exception text in the list of unresolved flows. Each subsequent raiseException() call raises the exception and passes the original exception text. When execution reaches the main diagram, the collaboration runtime environment performs its exception-handling operation, such as writing to the log or, if the collaboration is transactional, initiating rollback.
For information on how to create a decision node, see Decision nodes. For more information on how to implement exception handling, see Handling exceptions.
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.