What UML Is and Isn't

Abstract：Apply the UML during object-oriented analysis and design to build beautiful Java applications
by Craig Larman
Posted February 20, 2004

The UML is relatively trivial and unimportant. Surprised by that statement? Many are, but we shouldn't be. Nor should the statement be misinterpreted as implying the UML is not useful—it is.

But perspective is critical. The Unified Modeling Language (UML) is merely a standard diagramming notation: boxes, bubbles, lines, and text. The Object Management Group (OMG) UML specification calls it "a standard way to write a system's blueprints," and the term blueprints is an apropos choice. Civil and electrical engineers have standard diagramming languages to illustrate the structure and wiring in a building. We do not equate the ability to read and write standard blueprint diagramming languages with the knowledge and skill to envision and design a building—to be an architect or engineer.

Yet in the context of software development and the UML, acquiring skills to read and write UML notation is often equated incorrectly with skill in object-oriented analysis and design (OOA/D). Getting a book or taking a course that focuses on UML, becoming certified in UML 2.0 notation, or knowing how to use a UML CASE tool has nothing to do with being able to think or analyze in objects or creating well-designed, object-oriented systems. Indeed, there are some who have learned the notation or a UML tool, yet can't skillfully cut code in Java or design with patterns, and in some odd value system are therefore assigned a senior role as an analyst or architect who does the "advanced" work of drawing UML diagrams for others to program. Of course, the diagrams are worthless. Useful UML is sketched by deeply experienced OO programmers (ideally in pairs at whiteboards) as an aid to creative thought and communication before they themselves use their own sketches as inspiration during programming.

What is important is being able to create good object designs and programs—the art of OOA/D. When the rubber hits the road and code needs to be cut, what matters is our ability to assign responsibilities and create a design with low coupling, high cohesion, comprehensibility, and ease of modification. That's very different than knowing a diagramming notation such as the UML.

All that said, I'm an enthusiastic promoter of doing some visual sketching before programming and know that visual modeling (in the UML or any notation) can be a great aid in development, especially when applied in the spirit of agile modeling. Now, let's explore the critical skill, OOA/D, and see how the UML can be applied effectively during analysis and design.

Key Models
Models are abstractions of something. They ignore certain details or summarize. We'll explore various models here, but before going into the specifics, consider this important point: the UML does not define any models. The UML is not a method; it is just raw diagramming notation.

You've probably heard of models such as a "domain model" or a "use case model." These are not defined in the UML. Rather, the UML defines only low-level diagram types, such as "class diagrams" and "use case diagrams." The concept of models and model names are a higher-level concept, above the low level of the UML. Specifically, models are defined by various methods (or development processes), such as the Unified Process (UP), Feature-Driven Development (FDD), or Catalysis. Each of these methods defines models with different names and purposes, yet uses the raw UML notation as the standard with which to visualize the model. But a model is not necessarily even a set of diagrams; for example, a use case model is composed primarily of text documents.

To talk about OOA/D and models, some method that defines models must be chosen. We'll use the UP and its models in this example, as it is a widely used modern iterative and evolutionary method with a well-defined set of optional models. Some models are primarily part of requirements analysis, such as the use case model. Some, such as the domain model, are classic object analysis. And some, such as the design model, are part of object design. I'll be introducing what some common models are, their relationships, a UML visualization example, and key learning resources (see Resources).

Use Case Model
The first UP model we'll consider is the use case model. It describes the functional requirements of a system. (Alistair Cockburn's Writing Effective Use Cases is an excellent book on use case analysis—see Resources). Use cases are text documents, not diagrams, and the most common mistake in use case modeling is to waste time thinking about or discussing use case diagrams, rather than doing real use case analysis—writing text with a word processor. Nevertheless, it's useful to spend a few minutes sketching a UML use case diagram as a visualization that summarizes the names of the use cases and the external actors. Such a diagram serves as a kind of context diagram for the system. After spending a few minutes sketching a diagram, many hours will and should be spent doing real use case modeling: writing text. Since use case text is not an OO artifact but merely a description of functional requirements, we'll just note its presence and influence on later artifacts or models we will explore. Take a look at a sample use case diagram for the domain of a point-of-sale (POS) application that applies UML notation with some diagramming tips (see Figure 1).

The use case model—a popular approach to capture functional requirements—is part of the requirements discipline in the UP. It is composed of several artifacts, including (most importantly) the use case text and, optionally, a use case diagram; system sequence diagrams (SSDs); and system operation contracts.

An SSD is illustrated in UML sequence diagram notation and shows, for one scenario of one use case, the input system operations upon the system treated as a black box and the output from the system (see Figure 2). It serves to summarize the system I/O visually and help identify the system operations (input events on the system). Figure 3 illustrates influential relationships and possible order of creation for use case model artifact relationships. (The UP defines several other important requirements artifacts, such as the supplementary specification for nonfunctional requirements, as well.)

Domain Model
A quintessential object-oriented analysis (OOA) model is the domain model. It is illustrated in a set of UML class diagrams that depict noteworthy (to the stakeholders) concepts and terms in a problem domain and their relationships. It is critical to appreciate that it is not a picture of software (for example, Java) classes; it is a conceptual view of conceptual classes illustrating real-world domain concepts or abstractions of things of interest in the problem domain. You can think of it as a "visual dictionary" of the terminology of a domain.

Why bother creating one? First, as is true in general of analysis artifacts, the smaller the problem and the more familiar the developers are with the domain and its requirements, the less need there may be for creating such artifacts. But if the domain is large, new, or unfamiliar to the developers, a domain model can help in at least these ways. It can improve comprehension of the problem domain by visualizing the terminology of the domain and the important relationships between noteworthy concepts; clarify the key information that is relevant to the problem; and inspire a starting set of software classes (in the domain layer of the architecture) during design and development. The classes' names and attributes are drawn from the domain vocabulary—thus supporting a lower representational gap between our mental model of a domain and its representation in software.

See Figure 4 for a sample domain model for the POS domain. It shows the UML class diagram notation in which classes have a name and attributes and associations with other classes. Since these conceptual classes depict real-world concepts and not software classes, no methods are shown; methods are an OO design or programming concept, not part of a real-world domain.

The domain model is part of the business modeling discipline. The textual use cases, a rich source of domain vocabulary and concepts, will be a key source of inspiration when creating the domain model.

System Operation Contracts
Usually, the text use cases or domain knowledge of the developers is sufficient to understand the details of the functional requirements. However, sometimes they're not. For example, consider the system operation makeReservation(…) on an airline reservation system. There is more complexity and detail in what must happen and what information must be updated than you can probably imagine (unless you work as a developer for an airline). The use case, which emphasizes the flow of the story of actions, is not the most suitable artifact to record this fine-grained detail. In such cases, system operation contracts are another possible OOA artifact. Recall that a system operation is an input event on the system as a whole, such as makeReservation(…) in the airline domain, or enterItem(…) and makePayment(…) in the POS domain. These system operations may be illustrated explicitly in the SSDs (see Figure 2) and are implied in the use case text.

A system operation contract records, in pre- and postcondition format, the effect of an operation in terms of changes to objects described in the domain model. (See the sidebar, "Operation Contracts" for examples.) Notice that the postconditions in the contract are limited to these categories: instances being created, associations being formed, and attributes being changed. In other words, the postconditions are limited to changes to the objects and their relationships in the domain model.

It is important to understand that these postconditions are making conceptual-perspective statements of change, not referring to software behaviors. For example, the postcondition "A SalesLineItem instance sli was created." does not mean that a Java instance was created or a database record inserted; it means abstractly that somehow, someway, a SalesLineItem instance was created in the real world. It could be created in the memory of a clerk or written in a book (one hundred years ago this book was called the "sales register"). However, later during design—as we shall see—these postconditions will be realized in terms of software.

In the UP, the system operation contracts can be considered part of the use case model. Although they are not illustrated in the UML (being text artifacts), they are relevant to our discussion as they refer to the UML-notated domain model and will be input to the design model and visualized in the UML. The SSDs, drawn from the use case text, indicate the system operations for which contracts could optionally be written, and the domain model, also influenced by the use case text, indicates the objects that may be discussed in the postconditions.

Design: Dynamic Modeling
The design model is composed of dynamic and static artifacts, describing the dynamic behavior of the software objects and their static class definitions. The most common misunderstanding in software object modeling is to emphasize drawing static class diagrams, rather than dynamic interaction diagrams. But it is while thinking through the hard, detailed questions of what other objects object Foo should interact with to fulfill a task, and what specifically the messages should be—that is, the questions of responsibility assignment and collaboration—that the hard, creative part of object design is explored. Drawing only a static class diagram leaves unanswered and unexplored the details of object design, especially the details of the methods.

The starting point of dynamic object design is the system operations visualized in the SSDs and possibly elaborated in the operation contracts—for example, the enterItem(…) operation (see the sidebar, "Operation Contracts"). These operations are first captured in the UI layer and then delegated to the application logic or domain layer of a software system. In a Web-based application, Action objects in a Struts Web-UI layer can delegate a request to the domain layer running on a server.

Many details of the design of object interactions to handle the system operations can be explored in UML interaction diagrams sketched on a whiteboard. The UML provides two interaction diagram notations: sequence and communication diagrams. The communication diagram notation (before UML 2.0, these were called collaboration diagrams) uses a format that allows the placement of instance boxes anywhere in 2-D space on the diagram. Sequence diagram notation uses a kind of fence layout in which each instance is shown to the right of another (see Figure 5).

Which is better? There isn't a correct answer, but I, and many others, prefer communication diagrams when sketching on whiteboards because they are more space efficient—more objects can be squeezed on the board (and on a book or magazine page). In addition, erasing lines and sketching changes are easier with communication diagrams. On the other hand, sequence diagrams easily show the order of messages and thus are excellent to document finished designs. These can be generated automatically from the code with some UML CASE tools.

In any event, it is during the sketching of interaction diagrams that we can consider the assignment of responsibilities and the application of design patterns. Figure 6 shows a simple interaction diagram for the enterItem(…) operation. Note that it fulfills the postconditions of the operation contract. The single boxes represent single instances, and the stacked boxes represent collections, such as a Java List or Map object. The create message sent to an instance implies invocation of the Java new operator combined with a constructor call.

Static Designs with Agility
To illustrate the static side of the software object design, class diagrams are used in the UML. In contrast to their use in the domain model, in the design model the class diagrams are used to visualize software objects rather than conceptual objects. Agile modeling promotes the practice of creating models or artifacts in parallel, and I encourage the parallel sketching of interaction and class diagrams on different whiteboards. We may spend five minutes on interaction diagrams, and then walk over to the wall containing the related class diagram and fill it in to correspond to the growing interaction diagrams. Creative exploration and discussion on both diagrams is complementary.

Figure 7 shows a complementary design class diagram of the domain layer of the software objects related to the interaction diagram you see in Figure 6. (See Resources for several books that cover basic principles of object design and responsibility assignment captured in the GRASP patterns, advanced object design, and useful learning aids for the basics of object design and object models.) In the UP these interaction and class diagrams are part of the design model. The functional requirements described in the textual use cases and nonfunctional requirements in the supplementary specifications are the main inputs to the object design.

Optionally, operation contracts may provide more detailed input. The domain model can be input optionally to the design by virtue of the object-oriented principle of low representational gap. That is, we create software classes with names and information inspired from the domain vocabulary (illustrated in the domain model), such as Sale or CashPayment, so that the software design of objects in the domain layer of the application has some similarity to our conceptual model of the domain—there's a sale in the real world (the domain model) and there's a Sale in Java. That reduces the gap in representation between the software and the domain, improving comprehensibility, among other advantages. Figure 8 illustrates possible influential relationships and possible order of creation.

This introduction has just touched on some key object design elements related to the UML, but others are relevant. For example, UML package diagrams can be used to model and visualize the logical package structure, which can of course be mirrored in implementation with Java packages. These are also part of the design model. UML class diagrams can also be used to illustrate a data model schema, using a special UML profile for data models. UML deployment diagrams can be used to model the physical deployment of components onto different operating system processes (or JVM processes) and onto different computer nodes in a network. These are part of the UP deployment model, and the overall architecture can be summarized visually with the UML in a set of architectural views, based on the very well-known N+1 view model of architecture (see Resources).

Iterative Modeling
As software engineering evidence now shows, the waterfall life cycle and values that promoted an attempt to create "complete" or accurate models or specifications before programming is a worst practice associated with the highest degrees of failure and defects and the lowest productivity rates. However, some UML or OOA/D modeling sources still promote such ill-advised, grand-modeling attempts.

We should do lightweight incremental modeling in the iterative and evolutionary spirit promoted by the UP, FDD, and other methods, and not attempt to create a complete use case model or domain model before programming in Java. Rather, in the context of time-boxed iterative development, we should do a little analysis and design work (such as a few hours or a day) that fills in a small portion of the use case or domain model related to and bounded by the requirements chosen for the next two- or three-week iteration. Then, after a day of partial, incomplete, and only semi-accurate modeling, we should move on to developing the code and tests for the iteration, using the roughly sketched models as imperfect hints during development.

Then, through testing the software, demonstrations, and feedback from the customers, developers, and tools, we will clarify our inevitable misunderstandings expressed in the models and evolve them. Only writing code and running tests reveals the truth on a software project. Models lie, and can easily delude us into thinking the diagrams or text documents are correct. They won't be.

But these comments should not be misinterpreted as implying that visual modeling at the whiteboard for a few hours is useless—far from it. Sketching out alternative UML-ish design ideas with a partner—working quickly and easily with a marker pen, whiteboard, and digital camera to explore variations at the tough points in the design space—can be a wonderfully creative, effective effort that allows orders-of-magnitude faster exploration compared only to exploring in code.

Finally, after iteration-1 software is complete, iteration-2 begins. We can again spend a few hours or a day evolving the models based on iteration-1 feedback and the new requirements chosen for iteration-2. Before each subsequent modeling session, I suggest reverse engineering the code into UML diagrams, printing them on large plotter paper, and using those as a starting point for further sketching. This process repeats, iteration by iteration, applying a few hours every few weeks to some evolutionary modeling with the UML.

Evolving the Modeling Art
Agile modeling, described by Scott Ambler in his book (see Resources), captures many of the best practices that skilled modelers apply and evolves the art of modeling in the agile and evolutionary spirit of iterative methods such as the UP, FDD, and Extreme Programming. Agile modeling views the purpose of drawing or writing models not as a form of documentation or specification, but as a vehicle to understand and communicate more quickly. That's a key value in effective UML modeling.

Part of agile modeling that I have also called "low-tech, high-touch modeling," means to do modeling with very simple tools that don't get in the way, but rather that encourage creative flow. This concept primarily means to model on whiteboards and large posters rather than with computer tools (that is, not with UML CASE tools), and to capture our sketches with digital cameras.

In publishing I normally use a CASE tool or drawing tool to illustrate the diagrams clearly. But doing so gives the wrong impression of what I do when working with a development team, such as coaching them for a week during my consultancy. In practice, I usually sketch drawings with a marker pen—lots of messiness! And I always recommend, as does the agile modeling practice, to do modeling with at least one partner, if not triplets. I'll arrange work in a common project room where the walls are all exposed—no furniture against them—and there is maximum access to the walls for sketching or display of project information.

Here's another tip: if whiteboards are in short supply, there is a useful product called Write-On Cling Sheets from Avery (and others) that clings to walls with a static charge and allows writing and erasing as on a whiteboard. This material can be wallpapered to expand the "whiteboard" space of the walls.

The UML or visual modeling can be a wonderful, creative aid for exploring requirements or design quickly and collaboratively. Alas, it is all too often taught as some kind of private, semi-useless or academic exercise that has little bearing on creating real Java software. But many people are now learning to apply the UML and patterns in the spirit of agile, evolutionary modeling that complements developing beautiful, useful code—our central job as software developers.

About the Author
Craig Larman is the author of Applying UML and Patterns (Prentice-Hall, 1997), the world's best-selling text on OOA/D, iterative development, and the UML, which has been translated to many languages and used worldwide in industry and colleges. He is also coauthor of Java 2 Performance and Idiom Guide (Pearson Education, 1999). His most recent book is Agile and Iterative Development: A Manager's Guide (Addison-Wesley, 2003). He has been working with and coaching development teams in OOA/D for close to 20 years. Craig also serves as chief scientist at Valtech, an international consulting group. Contact Craig at craig@craiglarman.com.