In my last major entry on the UML I covered the Use Case diagram. The Use Case
diagram is a diagram used to gather requirements and help with analysis. Once
you have gathered your Use Case diagrams you can continue on with the analysis
phase by using Activity Diagrams.

Activity Diagrams are used to illustrate the activities
implicit in a use case. For example, consider this Use Case diagram:

This Use Case diagram clearly states that Search Users will
Search Content. However, it doesn’t make any attempt to say anything about the
steps involved. This is where Activity Diagrams come in.

Activity Diagrams are very similar to standard flow charts.
The major difference is that activity diagrams allow for parallel processing of
tasks. (In the ColdFusion world you really don’t need to worry about this difference.)

Here is an example Activity Diagram illustrating the Get Out
of Bed use case:

This diagram is made up of the following notational
elements:

Activities

Activities are used to indicate actions which are preformed
in your diagram. In the previous example the activities were: Alarm Goes Off,
Hit Snooze, Shut off Alarm and Get Out of Bed. Activities are shaped like
pills and have a description inside.

Transitions

The lines with open arrow heads are called Transitions.
Transitions are used to indicate the process flow between elements in your
diagram. In the Get Out of Bed example above, you can see that the Alarm Goes
Off activity transitions to the Sleepy state. There are nine transoms total in
the example.

Decision Points

There are two ways to draw logical branching in activity
diagrams. The Get Out of Bed example uses a decision point "Still Tired?" If
Still Tired? is Yes then the flow transitions to the Hit Snooze activity and
then back to the Asleep state. If Still Tired? is No then the flow transitions
on to the Shut off Alarm and Get Out of Bed activities.

The text shown in square brackets on transitions out of the
decision points is called Guards. For flow to progress through a guarded
transition the guard must evaluate to true in the context of the decision point.
For example:

This rather simplified diagram illustrates the decisions
involved in buying a car. We can see that if we’ve got less than a $100 we’re
going to be stuck in a used Yugo. However, as long as we don’t have too much
money we’re going to be able to drive a Sensible Car. And, if we happen to have
too much money we’re going to end up with a nice sports car.

Guards need to be mutually exclusive. For instance, it
wouldn’t make since in the diagram above to show that if we have more than $100
that we’ll buy a sensible car, because that could overlap with Too Much Money
guard and we wouldn’t know what to do.

You don’t need to use decision points to show decisions.
You can also simply draw multiple guarded transitions out of an activity.
Here’s the car buying diagram again, this time without the transition point:

In general, the decision to use Decision Points is up to you.
(Frankly, no one seems to use the same conventions in UML diagrams anyhow, so
you could probably use pink elephants to indicate decision points, so long as
you’re consistent!)

States

States are represented by rounded rectangles. (Sometimes
they are segmented like in the examples above, sometimes they’re not. As far
as I can tell, there’s no difference.) States are used to indicate milestones
in processing of your activity diagrams.

In the example above there are three states, Asleep, Sleepy
and Awake. These indicate the "state" of the person being woken up.

Starting State

Start States are a special type of state indicating the
starting point for your activity diagram. There can be only one start state on
your diagram. Starting States are always drawn as a filled circle. Sometimes
people draw a descriptive caption underneath the Starting State. In the Get
Out of Bed example we could probably have gotten rid of the Asleep state and
called the starting state Asleep instead.

Ending State

Ending States are similar to Starting States; accept that
they indicate ending points for processing. The other big difference is that
there can be multiple Ending States on your diagram. Ending States are drawn
as a filled circle with a ring around it. (It makes me think of Saturn, for
some reason.) As with Starting States, sometimes people draw a descriptive caption
underneath the Ending State. In the Get Out of Bed example we could probably
have gotten rid of the Awake state at the end and called the Ending State Awake
instead.

Forks and Joins

Seeing as my audience is primarily ColdFusion programmers,
forks and joins probably won’t make much of a difference to you (unless you use
ColdFusion MX 7 Enterprise, which now has an asynchronous event gateway).
However, for the sake of completeness I will do a brief overview of them.

Forks and Joins are shown as black bars and are used to
indicate parallel processing. For an example, look at this diagram:

This diagram illustrates the process of getting in the shower. The diagram
starts with the Turn on Shower event. However, the shower always comes on cold
and takes a while to warm up, so, for the sake of efficiency, we will fork out
and do more than one thing at a time. In our example, while we Brush our Teeth
and Shave we are also busily waiting for the water to get warm and happily
wasting precious natural resources. When we’re done with all of that, we will
join our processes back together and Get in Shower and proceed to play with the
Rubber Ducky.

Forks are always shown as a solid bar with one entry
transition and multiple exit transitions.

Joins are always shown as a solid bar with multiple entry
transitions and a single exit transition.

Swim Lanes

There is one other big notational element to activity
diagrams, Swim Lanes. Swim Lanes are used to illustrate which portions of a
system are responsible for particular elements of your diagram. Here’s an
example:

This diagram illustrates a User and a Website. The user is
attempting to log on to the website. As you can see, the User is responsible
for providing login credentials, while the Website is responsible for
authenticating the user.

One thing about swim lanes which confuses me is where elements
like Show Error Message or Show Intranet should be placed. I put them in the
User column because the User sees it. However, it’s really the website which
performs the action of showing, isn’t it? My opinion is that it doesn’t really
matter where these are placed. The purpose is to show that the User and the
Website work together to Authenticate the User and Show the Intranet.

Note: The diagram above is interesting too because it
shows multiple Ending States, one for success and one for failure.

How to Draw Activity Diagrams

The process for creating activity diagrams is pretty
simple. You can accomplish it by following these steps:

1. Identify a Use Case you want to create an Activity Diagram for.
2. Draw
   a simple Activity Diagram which shows the primary success scenario from beginning
   to end. Don’t worry too much about details yet.
3. Go
   back and add in alternative paths through the use case, including those which
   will result in errors.
4. Add detail to the diagram.

As a note, you might end up with portions of your diagram
which are so complex that they warrant an activity diagram. This is part of
the point of these diagrams. This level of discovery helps you understand the
scope of your software.

Let’s Draw Some Diagrams

In previous
entries on UML, I created a requirements
document and Use Case
diagrams for a searching and indexing API for ColdFusion based on Lucene. I will now
use the Use Case Diagrams to create a set of Activity Diagrams.

Search Content

The Search Content Use Case diagram was pretty simple:

I started diagramming by creating a simple Activity diagram
which illustrated the primary success scenario.

Now that I have the primary success scenario I need to go
back and add some detail. For instance, what happens if I don’t provide any criteria
or what happens if the index I’m searching doesn’t exist?

Now that I’ve got a pretty good idea of the flow through the
process, I would like to get a better idea of what we’re interacting with. I
know I’ve got a Search User and a Search API. I think we could add some swim
lanes to help clear this up a bit.

Index Content

The Index Content Use Case will necessitate a bit more
complexity in our next Activity Diagram. Here’s the Use Case diagram:

I started by modeling the primary success scenario like
this:

This activity diagram does a pretty good job of illustrating
the primary success scenario but it does need some more detail. For instance,
what happens when the index does not exist? How does the system know where the
index is located? What if there are no items in the queue? What if you can’t
retrieve the document?

I went ahead and added some detail and some swim lanes to
this diagram and this is what I came up with:

By now, you should be able to read this diagram (and I’m
tired of typing) so I’ll leave its interpretation to you.

One thing I’ve decided not to cover in this diagram is
exactly what information is being indexed and how the information is being
extracted from the document. This could easily warrant another activity
diagram. However, I have some complex plans for these so I think I’ll leave
the implementation details to another type diagram, perhaps a sequence diagram.

Do you have any comments, criticisms or questions on this
entry? If so, please leave feel free to comment below.

• Bookmark on Delicious
• Digg this post
• Recommend on Facebook
• share via Reddit
• Share with Stumblers
• Tweet about it
• Subscribe to the comments on this post