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

update 29/05/2011: Changed the “Caller” lifeline into a gate as suggested by Davide. Thanks Davide!

28 replies
  1. Jarek Żeliński
    Jarek Żeliński says:

    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…

    Reply
    • geertbellekens
      geertbellekens says:

      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)

      Reply
      • Jarek Żeliński
        Jarek Żeliński says:

        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.

        Reply
  2. Mark Reynolds
    Mark Reynolds says:

    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

    Reply
  3. Davide
    Davide says:

    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

    Reply
    • geertbellekens
      geertbellekens says:

      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!

      Reply
  4. Horst Kargl
    Horst Kargl says:

    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

    Reply
    • geertbellekens
      geertbellekens says:

      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.

      Reply
      • Horst Kargl
        Horst Kargl says:

        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 😉

        Reply
  5. Davide
    Davide says:

    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

    Reply
    • geertbellekens
      geertbellekens says:

      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

      Reply
  6. Joost van der Schoot
    Joost van der Schoot says:

    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?

    Reply
  7. Horst Kargl
    Horst Kargl says:

    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

    Reply
    • LiangQiulan
      LiangQiulan says:

      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?

      Reply
  8. Mark Elson
    Mark Elson says:

    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

    Reply
  9. Mark Elson
    Mark Elson says:

    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

    Reply
    • geertbellekens
      geertbellekens says:

      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

      Reply
  10. Bill
    Bill says:

    It is interesting how people do not understand that classes cannot collaborate or go through states and sequence activities but OBJECT only.

    Reply

Trackbacks & Pingbacks

  1. […] UML Best Practice: One Operation => One Sequence Diagram […]

  2. […] UML Best Practice: One Operation => One Sequence Diagram […]

  3. […] UML Best Practice: One Operation => One Sequence Diagram Share this:MoreLike this:LikeBe the first to like this post. Categories: UML Tags: best practice, Diagram, rules, UML Comments (0) Trackbacks (0) Leave a comment Trackback […]

  4. […] EA Navigator to navigate from an Operation to the Behavior set as its Method. In my previous post UML Best Practice: One Operation = One Sequence diagram I explained how to set a behavior as the implementation of an operation in Enterprise […]

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.