UML Best Practice: One Operation => One Sequence Diagram
Purpose
Model the implementation of your operations with a single sequence diagram for each operation.
Details
Most UML models I’ve seen in my career contain classes with attributes and operations. An Operation is a specification of a behavioral feature. Adding an operation to a class means that you are specifying that your class will respond to a specific request by executing a certain behavior.
So the operation defines the details of the request to be sent to the class (such as name, parameters…), but it doesn’t specify the details of what needs to happen when the operation is called. Those details are stored in a Behavior, and the operation specifies which behavior needs to be executed when it is called.
In the UML metamodel that looks as follows
The abstract Behavior is linked to the abstract BehavioralFeature where Behavior has the role of method and the BehavioralFeature has the role of specification.
So please never again mix up the terms Operation and Method, these are two different things!
From this diagram we also learn that Behavior is actually an abstract metaclass, and that there are four concrete subclasses of behavior that can be used to be the method of the Operation.
- OpaqueBehavior
A simple textual definition of the behavior one or more languages (such as English, Java, C#…) - Activity
The natural owner of an Activity Diagram - StateMachine
The natural owner of a State Machine Diagram - Interaction
The natural owner of a Sequence Diagram
From these four choices I’ve had the best experience using Interactions containing a Sequence Diagram to express the method of my operations.
Enterprise Architect Example
I created a small example in Sparx Enterprise Architect to illustrate this:
This view of the project browser shows the class MyClass, containing the operation MyOperation. Then there is the MyOperation Interaction which contains the MyOperation Sequence diagram.
In order to specify that the MyOperation interaction is the method of MyOperation operation you need to link them in the Behavior tab of the operation. Clicking the Element button will allow you to select the Interaction to use.
This interaction owns a single sequence diagram which contains the actual details of the implementation.
For the sequence diagram itself I have the following rules or habits:
- First Message
The first message, calling MyOperation on MyClass is not strictly necessary, but it helps the reader to quickly identify for which operation this is the implementation, without having to search for the operation in the model. - caller
The gate “caller” is the representation of any other object calling the MyOperation operation on MyClass. It is important to keep this “caller” anonymous, even if there is only one class that effectively calls MyOperation. In the future other classes may start using MyOperation as well, and we don’t want to start duplicating the sequence diagram to include all the callers of this operation. - Only messages from MyClass
Since this sequence diagram represents the implementation of the operation MyOperation I only want to show what happens in that operation. So the sequence diagram will only have messages starting from MyClass and it will not show any details of the implementation of operations on SomeOtherClass or YetAnotherClass. These operations will all have their own Interaction and sequence diagram to specify their behavior. - Objects for “non-static” operations, classes for static operations.
Non-static operations are always called on instances of a class. Static operations are called on the class itself. Notice the difference between the object “:SomeOtherClass” and the class “YetAnotherClass”.
To quickly navigate between operations and sequence diagrams I of course use the free and open source EA Navigator add in.
More UML best practices
- UML Best Practice: Attribute or Association
- UML Best Practice: 5 rules for better UML diagrams
- UML Best Practice: There are no Activities on an Activity Diagram
update 29/05/2011: Changed the “Caller” lifeline into a gate as suggested by Davide. Thanks Davide!
Good article, IMHO I say little widely: one sequence diagram per one use case, it determine that use case’s coul’d not be complicated… it must be simple. If we see the use case as a one class operation, probably one operation means one use case…
Jarek,
I’m not sure about that. I usually don’t document my use cases (or use case realizations) with sequence diagrams.
Especially the type of “manage users” type of use cases that are heavily GUI driven are often realized by many operations (and thus many SD’s)
Probably it is depend on the use case definition. You have right that “heavily GUI driven are often realized by many operations” but we can model this as a collection of simple events..
I see the heavily GUI as a dashboard: each thinks on this “means” simple use case.
Nice blog, thanks. Here is what I’ve done in the past.
For complex operations, I’ve essential followed the same rules you described. For simple operations I do not create sequences.
In my application of use case driven analysis, starting the sequencing effort at the use case level is a way to drive the behavior design directly from the use cases which is what the users have agreed to.
The Sequence Diagrams strength is showing how objects collaborate to provide functionality. Starting this at the use case level is very natural to me. When the use case description says “User does A” and “System responds by doing B”, on the use case level sequence you have the actor representing the user and messages going to the UI object representing the interaction, then subsequent messages showing how the functionality of the system response is achieved.
I always keep my use case level sequences fairly high-level and then detail out complex operations on their own sequence diagram.
Mark
Hi Geert
nice article.
Some questions: to me, it seems that the definiton of Specification and Method is exactly the opposite of what you have stated; the method should be the operation, whereas the specification is the sequence (or the activity).
Normally I put the activity or sequence in the class directly, so that the whole class can be reused in other projects.
Instead of the caller, I use a gate.
Davide
Davide,
Please look at figure 16.3 of the UML superstructure specification 2.3 on page 440 (456). There is is clearly stated that the Behavior is playing the role of “Method” while the behavioralfeature is playing the role of “Specification”.
Where you place the activity or sequence diagram is of course to your own liking, although the diagrams should always be owned by a proper behavior (Activity, Interaction,…). So a sequence diagram owned directly by the class would be “wrong” in UML terms.
In general I don’t tend to put too much under the class as it clutters the model view too much, but again, I think that is subject to personal preference.
The suggestion to use a Gate iso a Lifeline for the caller is a very good one. I must admit that i’ve never used Gates before. I think I’m going to adapt this post to use a Gate. Thanks!
Post adjusted to use a gate i.s.o. a lifeline for the caller.
Thanks Davide!
It’s probably quicker to use websequencediagrams.com for this.
Hi,
great Post, I agree – for me a Sequence Diagram is a Scenario
BR
Daniel
Good explanation of the metamodel 😉
Regarding your statement: “From these four choices I’ve had the best experience using Interactions containing a Sequence Diagram to express the method of my operations.”
I think it’s a matter of the class containing the operation (for what this Class/Operation was designed) if a Sequence, Activity, StM or OpaqueBehaviour is the best choice, isn’t it?
In case, the operation is responsible to access many different objects to get the needed information, a Sequence is a good choice to represent the interactions, even if just the calls from MyClass are included.
In case of a more algorithmic behaviour (method) or if very less additional operation calls are included, an Activity would be the proper one, because a Sequence will not contain much information 😉
If the designed system is more state base, a State Machine is maybe a better choice to express the method of the operation!?
However, I agree that UML 2 Sequences are powerful enough to represent very much details of a method and it is often a matter of what information are you interested in, Interaction or the concrete algorithm.
… I like the idea of the EA Navigation Add-In 😉
BR, Horst
Horst,
Thanks for your comment.
I do agree that in some circumstances one of the other behaviors are better suited to express the method.
The problem however is that UML has so many ways to express behavior. Maybe you and I can decide case by case which would be the most suitable behavior to use, but in a corporate environment you just can’t allow each analyst to decide that on his own.
Currently I’m already happy when most of my analysts understand how to express the behavior of an operation in a sequence diagram. I’m afraid I can’t ask them to get to know all the subtle details of all other types of behavior, and make an informed choice between them.
Given these restrictions I think Interactions with Sequence Diagrams are the better choice.
Hi,
I totally agree with you about modelling possibilities and eventually different levels of modelling maturity. I always suggest to define a reference model (which and how model-elements should be used in a specific context). Based on this reference model, further automatic validations of the model can be provided! However, Sequences for Operations is a good reference model 😉
Hi Geert
thanks for the comments.
I would have another proposal in order to improve the documentation:
normally, if AnotherOperation in SomeOtherClass has an associated interaction just like the one described for MyClass, I put the interaction occurence referring to that interaction just below the message AnotherOperation(); in this way, it is easy to navigate through the different behaviors of the model. In case AnotherOperation has an associated activity or state machine, I put the diagram reference (there is no Activity occurence or state machien occurence in EA) of that behavior.
Another thing: normally, when one creates the class diagram of MyClass and SomeOtherClass, one puts a named association between them, or at least the instance of SomeOtherClass referred by MyClass has a known name.
In order to make this relationship clear in the sequence diagram, I create an object in MyClass (through the composite diagram), type SomeOtherClass, with the name described in the association.
In the Interaction diagram of MyOperation, I drop a link to that named object instead of a generic instance of the class SomeOtherClass. In this way, it is easier to trace the usage of that class instance.
What do you think about it?
Davide
Davide,
I don’t really like the idea of having to put diagram/interaction references on my sequence diagrams as they would mean extra work, and they would clutter my sequence diagrams.
But I certainly understand the need for easy navigating. That’s exactly why I created the EA Navigator, to easily browse up and down my behavioral model.
Come to think of it, the EA Navigator could also do with a navigate to “Implementation” feature; something to work on the next few days;)
The idea of using the role name as name of an instance on the sequence diagram is another good one, although I’m not convinced about the need to create all those instances already as nested object in MyClass. I’m going to need some experimentation with that..
Geert
I just added a new feature to the EA Navigator to navigate to the implementation. See http://geertbellekens.wordpress.com/2011/06/03/new-navigate-to-operations-implementation-with-ea-navigator-1-2/
Geert
Hi Geert,
About the placement of interactions, inside or outside the class. When you apply the code generation feature for activities or stds, would it be important to put it inside the class in order to generate the associated code inide the class?
In EA it is important to put the behavioural models inside the class to get the code generated from it. Furthermore, if you link the behaviour to the behavioural feature, like it is displayed in the screenshot above, the behaviour (method) is generated as body of the operation (Behavioural Feature). Otherwise, EA creates a new Operation in Code, with the name of the Behaviour. When you synchronize the code back, you will get a corresponding operation (Behavioural Feature) in the UML::Class.
This also reflects the UML MM, a class has ownedAttributes and ownedOperations (both are connected with a composition to the UML::Class). See UML Superstructure 2.3 Page 32, Figure 7.12
Hi Horst Kargl,
I have arranged the sequence diagram in the way you said, but I have a problem.
When I create three objects A,B, and C,and these three objects interact with each other, how do I generate their respective code under methods A,B, and C?like this:
ObjectA ObjectB ObjiectC
Message 1.1
———————->
Message 1.2
———————————————->
Message 1.3
———————–>
I generated the code using the sequence diagram shown above, but from “ObjectB” to “ObjiectC” the Message1.3 has no generated code.Why is that?
Hi Geert,
“To quickly navigate between operations and sequence diagrams I of course use the free and open source EA Navigator add in.”
Is there any way to perform the same navigation on a UML diagram?
Regards, Mark
Mark,
I’m sorry, I don’t understand what you are asking.
Geert
Hi Geert,
By using EA Navigator you are augmenting the tool to achieve the navigation between the operation and sequence diagram. If I am distributing the model either by html export or eap then my readers might not have that facility. I then wondered if there was some UML construct that would let you perform that neatly on a diagram. I guess the fallback way in EA is to add a hyperlink.
Mark
Hi Mark,
I understand now.
Well in fact there is already a UML construct there, EA just fails to provide easy navigation. So until EA improves the navigation facilities for these UML constructs I guess you are stuck with hyperlinks and the likes. (in fact EA already improved some navigation functions. Since version 9 you can find sequence diagrams starting from an operation)
Geert
It is interesting how people do not understand that classes cannot collaborate or go through states and sequence activities but OBJECT only.