Modeling Systems and Software

More UML Associations - Composition

2013-04-10T17:59:00.002-05:00

In addition to being directed or bidirectional, associations may be aggregations or compositions. These special classifications provide more information about the association.

A solid diamond on the composing class’ side of the association indicates composition, as indicated in the diagram. If that diamond were hollow, the association would be an aggregation. The next section contains more information about aggregations.

In many books, you read that compositions create containment. The composing object contains the composed object. While this description is true, it doesn't help explain the composition relationship or how to use it. An alternative explanation is that a composing object “has a” composed object, as in “TimeBasedDetector has a Timer.” Now, this “has a” description also works for aggregations. So what is the difference and is it important?

The basic difference between aggregations and compositions has to do with where the objects are created. In an aggregation, the object is created elsewhere in the model. The links between objects get set during a post-instantiation/pre-runtime setup phase. For composition associations, the composed object creates and destroys the composed objects. It also must configure the link relationships. Typically, one configures composition relations during instantiation, as shown in the code snippet below.

//## class TimeBasedDetector

public class TimeBasedDetector implements GenericDetector {

protected int LastSensorValue;

protected Timer itsTimer; //## link itsTimer

// Constructors

public TimeBasedDetector() {

initRelations();

}

//Called by constructor to create the timer composition and configure the links

protected void initRelations() {

itsTimer = newItsTimer();

}

// Construct the timer

public Timer newItsTimer() {

itsTimer = new Timer();

itsTimer._setItsDetector(this); //configures the Timer’s link to point here

return itsTimer;

}

//Configures the link

public void _setItsTimer(Timer p_Timer) {

if(itsTimer != null)

{

itsTimer.__setItsDetector(null);

}

__setItsTimer(p_Timer);

}

//configures the link

public void __setItsTimer(Timer p_Timer) {

itsTimer = p_Timer;

}

// Destructor

//## operation ~TimeBasedDetector()

protected void finalize() throws Throwable {

cleanUpRelations();

//#[ operation ~TimeBasedDetector()

//#]

super.finalize();

}

//called to delete the composed class

protected void cleanUpRelations() {

{

deleteItsTimer();

}

//sets the links to null so that the trash collection runs

public void deleteItsTimer() {

itsTimer.__setItsDetector(null);

itsTimer=null;

}

When we look at aggregation relationships, we’ll see that the construction/destruction of aggregated objects is not handled by the aggregating object. Therefore, the difference between the two is very important for describing how the developers build the code.

System Engineering Tools Demo -- For University Students

2013-03-16T16:40:00.000-05:00

Here is a demo of Systems Engineering tools that I gave to university students today. Ignore the date on the slides.

I'm not thrilled with the quality, so I will rework the video and post soon.

Bidirectional and Directed Associations

2013-02-25T14:19:00.001-06:00

Associations allow classes to interact. By interact, we mean calling an operation or accessing data. In code, pointers or references implement associations in object oriented languages. Functional languages, such as C, use pointers or references when passing data, but only require #include for accessing operations.

Technically, the previous paragraph isn’t right, is it? Associations don’t allow classes to interact, they allow objects to interact. UML Links instantiate associations. That is, an association defines a generic pointer whereas a link defines a pointer to a specific object. For simplicity sake, though, we’ll continue to discuss this subject in terms of classes and associations.

In the previous diagram, the line between Sensor and GenericDetector represents a bidirectional association. That means that Sensor “knows” about (has a pointer to) GenericDetector and GenericDetector knows about Sensor. Sensor refers to GenericDetector with the name itsDetector. Similarly, GenericDetector refers to Sensor as itsSensor. So, an object of type GenericDetector could call the Sense operation of an object of type Sensor. In C++, the code would look like this:

itsSensor->Sense();

Most of the time, however, only one of the two classes involved in the interaction needs a pointer to the other. In fact, requiring bidirectional associations is generally considered bad design because it makes the software harder to reuse and to extend. Instead, use directed associations, as shown in the attached figure. Here, Sensor can call Reset() or ToggleValue(), but GenericDetector cannot call Sense.

Structure -- Class Diagrams

2013-02-18T15:44:00.002-06:00

The interesting thing about structural diagrams is that they look very similar for both UML and SysML, but their interpretations are different. Let’s start with UML Class diagrams because they are more basic and easier to understand.

Class diagrams, such as the one here, show classes and relationships among classes. In UML, classes are entities that contain functionality (operations), data (attributes) and relations. They are not necessarily language (code) classes. When working in a structured language like C, I use UML to help define and allocate functions to files and variables to structures.

Associations are general relationships between classes. They come is several flavors that we'll discuss here, but it helps to understand the basics before we get into the subtleties of the metamodel. The easiest way to understand a relation is to understand how it gets implemented in code. For simplicity sake, I am going to use C++ terminology and syntax. The design principles apply to object oriented languages like Java, AND to functional languages like C.

In UML, classes have two primary types of relations: a class can have an association to another class and a class may be generalized from another class. Associations are how classes know about each other. In C++, an association gets implemented as a pointer or reference. Generalizations show an inheritance. A class that generalizes another (the child) has all of the attributes and operations of its parent.

More on each of these relationships in the next few articles.

The figure shows these two relations.

Adding Structure to Our Lives

2012-05-10T21:24:00.000-05:00

UML and SysML classify diagrams as showing structure, interactions, or behavior. Structural diagrams show the system's pieces and relationships among those parts. Interaction diagrams show the communications among those pieces. Behavioral diagrams specify how the pieces respond when they receive messages. (Please note: I used the term "pieces" specifically because it is not a UML or SysML term. A piece could be a class, object, file, structure, block, or part) Structure diagrams serve similar purposes in both UML and SysML, it with some important differences. For Systems Engineers, the entities represent abstract concepts about a system's decomposition. For software developers, the entities represent code that will be created (i.e., generated or handwritten) to implement the software application. The next few articles discuss structural diagrams.

Coding, designing, and modeling

2012-04-17T18:25:00.001-05:00

"How can I do my design when I haven't written the (expletive deleted) code yet?" a former colleague yelled quite irately as I passed by a manager's office. Now I know Joe. Yes, sometimes he would start out coding and end up with some useless methods and classes. But Joe always had an idea of his code's basic structure. What Joe meant to say was that he could not write the detailed documentation of his design because he hadn't worked out all the details yet.

Unfortunately, many developers look at modeling the way Joe looked at design -- as a documentation step to be completed rather than something that helps the goal of producing properly executing code quickly and efficiently.

Modeling helps developers visualize the structure, interactions, and behavior of the system they are building (NB: I used the plural because developers seldom work alone. One must be able to communicate one's ideas; more on that in another article).

In fact, in a 2008 survey by Scott Ambler found that the vast majority of developers used high level diagrams. From my own practice, I'm assuming that the majority use class diagrams to define structure. I'll bet that a fair number of developers use some variation of sequence diagrams when discussing interactions as well. Here is my point: If you are already using these two common diagrams, why not capture the artifacts in a tool rather than on a white board? Doing so makes the artifacts reusable and captures the design rationale for the rest of the team (including reviewers and maintainers).

Bottom line: if Joe had captured his thoughts in a model, he wouldn't have had the scream match with his boss. He might even still be working there.

Refining Use Cases with Activity Diagrams

2012-04-12T06:01:00.000-05:00

In a previous post, I discussed text based use case descriptions. This post discusses a graphical method: activity diagrams.

Before discussing the advantages of refining use cases with activity diagrams, let's define activity diagrams. One of my colleagues describes them as "flow charts on steroids." Activity diagrams show the possible sequences of activities and the flow of data between activities in a single view.

The rectangles with rounded corners represent activities. In the software world, an activity would be implemented as a functions or method. On this diagram, the dashed red lines represent the order that the actions occur.

Unlike text, graphical activity diagrams are not open to interpretation. Even people not trained in UML's or SysML's subtleties understand an activity diagrams flowchart-like structure. Complicated concepts, including exception condition handling, become clear when viewed on a single page.

Note that you may use nested activity diagrams (not what they are called, we'll get to the proper name later) to describe complex actions.

In summary, the advantages of using activity diagrams to refine use cases include:

Graphical representation is not open to interpretation the way text is
Shows multiple paths (including exception conditions) in one view
Complex actions may be further refined with other activity diagrams

UML Hell Doesn't Exist.

2011-07-11T10:31:00.000-05:00

Recently, customer gave me a paper that basically said that modeling is a mistake and that it takes too much time for the benefits. The author states that UML is strictly an academic concept that has no place in the commercial world. He states several problems including the model not representing the code and modeling slowing down the development process.

Obviously, I disagree. In fact, I disagree so strongly, that I'm not going to give the link to the paper. I will, however, share what I told my customer.

True, modeling just for the sake of modeling provides little value. It is entirely possible to model to such fine detail that the model misses its purpose.  In the Systems Engineering realm, the purpose of the model is to specify what the system must do, not how the system does it. Any modeling that describes how is a waste. The advantages of Systems modeling are fewer missed exception conditions, fewer duplications of effort by multiple subsystems, better definition of the interfaces, and better understanding of the subsystems' responsibilities.

In the software realm, models show the desing -- how the system implements the requirements. I am assuming, of course, that you see value in designing your system before you start coding. Typically, designs include the software structure, class/file interactions, and function/method behavior necessary to build the software.  A UML model, therefore, includes the exact same information you are required to deliver in an SDD.  In fact, you should generate your SDD directly from your model. The advantages of software modeling include better understanding of (by all stakeholders) of the system's functionality, better design reviews, better structural design, less time to develop code, and increased reusability.
If you use the right tools, modeling decreases development time. There are several tools on the market today that generate code directly from the model. Now, the "fitness" of the code varies with the tool. Some require you to make all changes directly in the tool; the code is really not user editable. Others, produce only "code-frames," the header files and the method signatures. I don't recommend using products like these.

Instead, find a product that generates full, production quality code directly from the model. The code should be readable and editable with your favorite editor. Similarly, you should be able to use your tool to visualize existing code. (email me and I'll give you the names of the tool I like)

The proof of the pudding is in the tasting, so rather than get in a war of words with the author of the other paper, I'll point to Dr. Jerry Krasner's paper What to do When the Horse You're Riding Drops Dead. Dr. Krasner's research showed that organizations that model and generate the code from the model finish their projects on time and hand code fewer lines of code to accomplish the same task.

I also add my own experiences. I used to run a software development group that produced the machine control software for high speed mail sorting equipment. My development team had 5-7 people. We developed routinely developed more code, in less time, with fewer erros than groups of 15-20.  The other teams had to stop developmetn for 2 weeks a quarter to update documents. I generated our documents while the team was at lunch.

Bottom line: UML helps real projects develop software faster and with fewer errors.

Text-Based Use Case Template

2010-05-16T15:34:00.000-05:00

I promised a text based use case template some time ago, and now I'm posting it. This template is loosely based on the work by Alistair Couckburn.

Use Case Description

Use Case:
Version:	1.0
Description:
Scope:
Level:
Primary Actor(s):
Trigger:

Assumptions:

Preconditions:
Success End Condition:
Failed End Condition:
Assumptions:

Main Scenario:

Exception Scenarios:

Extensions:

Other Information:

The first thing you will want to do is make it your own by customizing the template to meet your organization. For example, I found that the version number was not valuable because we used a configuration management system to maintain the documents. Therefore, the most recent copy was at the tip of the archive -- a much simpler solution.

Next, you need to create some "Use Case Standards." In my organizations, we number the main flow steps. When an exception occurs, we put , where x is the number of the exception, at the end of the main flow step. Each item in the Exception Scenario part begins with EXCEPTION x. We keep the exception conditions and main flows together by following this practice.

Next time, using Activity Diagrams to Describe Use Cases

Use Cases - Overview

2009-12-22T17:52:00.001-06:00

Use Cases cause a lot of confusion for many people new to UML and SysML. The OMG UML Infrastructure specification calls Use Cases "a means for specifying required usages of a system. Typically, they are used to capture the requirements of a system, that is, what a system is supposed to do." (OMG Unified Modeling Language (OMG UML) Superstructure, V2.1.2, p. 585). This definition seems a bit academic, so let me try to bring some practical world experience.

Let's be clear: Use Cases ARE requirements. They provide much more than simple shall statements, however. From a Systems Engineering perspective, think of about the problem space this way: a Request for Proposal or Statement of Work provides the requirements for any competitor's solution, but your Use Cases explain your organization's specific solution. They list the capabilities of the system. You will use the descriptions to allocate functionality to different parts of the system. Taken together, the Use Cases described your proposal. Each of the functional shall statement requirements should trace from a Use Case.

Since Use Cases detail the system requirements, they tell what the system will do, not how the system will do it. Use Cases do not show functional decomposition, nor do they specify how to write the code.

Another confusing aspect of use cases are the relationships « extends » and « includes » . I am not going to spend much time describing these here because it is an academic argument. Whether you show a capability as « extends » or « includes » is almost irrelevant. Either way, you will need to detail the additional Use Case. Therefore, I only use « includes » ; and then I only use it when multiple Use Cases require the exact same capability.

A Use Case's meat exists in its description. The description shows, step by step, what the system does to implement a capability. It shows the response to external stimuli (Actors). As important, a Use Case description shows the exception conditions when the normal flow of events does not happen. These discussions of exception handling show the real power of Use Cases. They force the engineers, both Systems and Software, to think about the exception conditions up front.

In the next two sections, we will discuss different methods for detailing Use Cases. The first method uses text. The second uses and Activity Diagram.

Why Model

2009-12-19T12:04:00.000-06:00

The model specifies what a system does and how it does it. Logically, therefore, one starts modeling by deciding what the system is going to do. In traditional, document-driven development, one starts with a Request for Proposal (RFP) or Statement of Work (SOW), writes a proposal or System Specification Design Document (SSDD), writes the System Requirements Specification (SRS), and finally writes a System Design Document (SDD). This methodology has worked for the last 50 years and I'm not suggesting that modeling should replace it. For one reason, many contracts require text deliverables. Rather, modeling augments this process.
Text is a very poor way for engineers to communicate. For the most part, engineers are visual people. If I were to ask you to go to whiteboard and describe the system you are currently working on, odds are pretty good that you will not write a bunch of paragraphs. You will draw some circles and boxes and maybe some arrows to describe the flow. In fact, the main reason we text documents to communicate is because computers come with keyboards.
Another problem with text is that words have different meanings in different industries and different parts of the country. Take the word "fixing." It might mean repairing. Or, especially around the holidays, it might refer to side dishes. Here in Fort Worth, Texas, it means you are getting ready to do something.
Not only do words have shadow meanings, but not all of our coworkers are native English speakers. We may work with colleagues overseas. More likely, at least one team member grew up speaking a language other than English.
Another problem with text-based requirements is how we were all taught to write. Each of us had a high school English teacher, for me it was Miss Feage, who said "vary you sentence structure" and "use descriptive verb." While this advice applies when writing the Great American Novel, it does not apply when writing the Great American Requirements Specification. For a requirements specification, we expect "subject shall requirement." Unfortunately, I have yet to see a customer document written in this format.
Building specifications in UML and SysML avoid all of these problems. UML and SysML are graphical languages. Engineers and Computer Scientists relate better to diagrams than to text. Furthermore, the graphics help engineers see the part of the system under consideration in a single view. This view helps them identify missing exception conditions and inconsistencies.

UML and SysML have very distinct syntax. This syntax is designed to specify structure, interaction, and behavior in a distinct manner that, if used properly, is not open to misinterpretation. And when it comes time to generate the deliverable documents, the better modeling tools support generating the documents directly from the model.
Bottom line: modeling is more natural than text, will help you avoid and identify errors earlier, and still lets you follow your existing processes.

Use Case Diagrams, Actors and Associations

2009-12-19T11:11:00.000-06:00

Let's talk a little more about actors.
Actors represent something outside the system that either affects the system or the system affects. The significance here is that an actor is outside of the system. You are not going to build it. You are not going to model its behavior. Even though UML and SysML use stick figures to show actors on diagrams, all actors are not people. Actors may represent people (for example, the user) or they may represent hardware (a sensor or an effector) or they may represent another subsystem.
Any of you who have attended any of my classes know that I am about to get on my soap box now. Hard engineering disciplines (electrical, mechanical, chemical, civil) will never take Systems and Software engineers seriously as long as we use these silly indicators and cutesy terms (e.g., fuzzy logic). Therefore, if you are going to show use case diagrams to your colleagues or customers who are not fluent in UML/SysML, change the picture of the actor to what it represents in the real world (a tank, a letter carrier, the physical actuator). Better modeling tools let you make this substitution (if yours does not, contact me and I'll put you in touch with a sales guy). OK, now I'll step off my soapbox and go back to the discussion.

When developing systems, actors represent anything you are not getting paid for. In an IT system, the actor may represent the server -- or better, an application running the server. In an aircraft flight control system, use an actor to represent the pilot (not the stick because it is part of the aircraft and generally falls under the auspices of the flight control subsystem), the inertial navigation system (it is not part of flight controls), and the surfaces (when you execute the model, you want to confirm they are moving the correct direction).

When developing software, use cases represent a single feature of the code (more on this when we discuss Use Cases and the Development Process). In these cases, the actor represents the other parts of the code that interact with that feature. Let me clarify. A reusable machine control framework includes the concept of generic inputs and outputs. No matter how the physical hardware works, the application interfaces with I/O using the same (virtual) calls. The use case Read_Discrete_Inputs has an association with a Client actor. This actor represents any part of the code that requires a discrete input. By definition, the Client is internal to the system, but it is external to the feature. Therefore, as far as Read_Discrete_Inputs is concerned, Client is external. In other words, your point of view determines internal versus external.

Associations show the virtual connections between actors and use cases. They indicate which use cases an actor affects and which actor the use case affects. Most, but not all, use cases have associations with actors.
Associations provide another purpose when reviewing the model. They indicate the potential interfaces. Specifically, the association between a User actor and use case indicates that the system requires some form of user interface -- a GUI, a push button, a retinal scanner. It forces the Systems Engineer to think about what may be missing from the overall specification.

One last point, in the early days of the UML, we showed associations as arrows. These arrows caused misunderstandings and provided little additional information. Therefore, I recommend that you show the associations without arrowheads.

Use Case Diagrams

2009-12-18T17:01:00.003-06:00

For years, I did not see the point of Use Case diagrams. They were just a bunch of bubbles with stick figures that listed the capabilities of the system. The Use Case descriptions held the real value. They described what the system was supposed to do.

A colleague of mine, Dr. Peter Hoffmann, changed my opinion. Peter preaches that the we should think of the Use Case diagram the way we think of a table of contents of a book. It gives a quick and concise way to show a system's capabilities -- think section 3.3.1 of an IEEE specification.

A common question many customers ask about Use Case diagrams is where does one draw the boundary. I answer that how one displays Use Cases on a Use Case diagram is a function of the model's purpose and the modeler's perspective. Let me explain. For Systems Engineers, the boundary box represents everything that you bill to the customer. Therefore, if you are delivering computer equipment, include it inside the boundary and show the actor as the User.

For Software Engineers, show the boundary at the edge of your work focus. In other words, if your part of the code interfaces with an API, web service, firmware or physical hardware, show these as actors.

Another common question is how to show the Use Case description. Again, my answer is to consider your audience. Use Case description are a great way to share your understanding of the system with the stakeholders. For one project I worked for the United States Postal Service, I gave Use Cases to the head technician so that he could confirm that the machine worked the way I understood it to work. He was very comfortable with ladder logic, so I gave him Activity Diagrams. For another project, the stakeholder was a marketing/sales exec. He was more comfortable with a text description. Both methods worked well for the intended audience.

UML and SysML Diagrams -- an Overview

2009-12-17T16:11:00.001-06:00

UML and SysML diagrams fall into three categories: architectural, interaction, and behavioral. Architectural diagrams show the structure of the elements of the model. Systems Engineers using SysML use Block Definition Diagrams, Internal Block Diagrams to show a system's architecture. Software engineers use class and object diagrams to show the software structure. Both use package diagrams. Though not discussed by here, Deployment Diagrams and Component Diagrams also show the the structure and full under the Architectural Diagram classification.

Interaction diagrams show how model elements communicate. They include communication and sequence diagrams. Of the two, I strongly prefer sequence diagrams because they are easier to understand.
Behavioral diagrams show what the model elements do when they receive communications. Use Case diagrams, Activity diagrams, State Charts, and timing diagrams show the system's and the software's behavior.

Both UML and SysML are visual languages that use diagrams to show views of the model. But remember that the diagrams are views, they are not the model.

The Most Important Diagrams

2009-12-17T09:17:00.000-06:00

The other day, a customer asked what I thought were the most important diagrams when creating a UML model. Organizations new to modeling often ask the same question, so I'm going to spend the next few days answering it.

Always remember that the purpose of modeling is to help one understand the system. Both the UML and SysML are full of diagrams and subtleties that make the languages richer and more expressive, but only if the readers understand the full content. In my practice, I see developers with all levels of experience and comprehension of the UML. As one would expect, the vast majority are somewhere in the middle. They know the diagrams they use frequently very well and are less well versed in those they seldom use.

Use the diagrams most people understand: Use Case Diagrams, Activity Diagrams, Sequence Diagrams, and State Charts.

In the next few posts, I will describe each of these diagrams and how I use them.