The Agile Modeling (AM) Method

UML Package Diagrams: An Agile Introduction

Packages are UML constructs that enable you to organize model elements into groups, making your UML diagrams simpler and easier to understand. Packages are depicted as file folders and can be used on any of the UML diagrams, although they are most common on use-case diagrams and class diagrams because these models have a tendency to grow.Although a UML 2 package diagram can be used to organize any type of UML classifier, I typically create package diagrams to organize either classesdata entities, or use cases. All three styles are effectively business architecture diagrams in my mind.

Class Package Diagrams

When it comes to “class package diagrams” I apply several rules of thumb. First, classes in the same inheritance hierarchy typically belong in the same package. Second, classes related to one another via composition often belong in the same package. Third, classes that collaborate with each other a lot-information reflected by your sequence diagrams and communication diagrams-often belong in the same package. Figure 1 depicts the start at a class package diagram for the university. It shows several packages and the dependencies between them. Notice how the Contact Point package has the “flap” drawn on the right hand side instead of the left – remember the AM principle that Content is More Important Than Representation.

Figure 1. Package diagram organizing the university class model.

I have applied several UML stereotypes on Figure 1. The application stereotype is applied to the Seminar Registration package, indicating that this package contains user interface (UI) classes and application-specific business classes for registering students in seminars. Similarly the technical stereotype is applied to the Java Infrastructure package indicating that it contains technical classes, perhaps a user interface framework such as Apache Struts or a persistence framework such as Prevayler. Both the application and technical stereotypes are my own convention, albeit very common ones. The import stereotype, a UML standard, is applied to several dependencies indicating that the Java Infrastructure package is imported into the other packages on this diagram

Each package in Figure 1 would lead to a more detailed diagram, perhaps another package diagram for a very complicated system or more likely to a UML class diagram. Figure 2 depicts a UML frame which is used to depict the contents of the Schedule Package, in this case a high-level conceptual class diagram. Frames can be used to show the detailed contents of any type of UML model, such as packages, components, classes, or operations. The heading is depicted with a name tag, the rectangle with the cut off bottom-right corner, in the format [ ]Name[ ]. Had the frame represented a component the heading would have read Component Schedule and had it been for an operation it may have read something like Operation EnrollStudent(Student).

Figure 2. The contents of the Schedule package.

Data Package Diagrams

Because you can use the UML to model data it makes sense that you can also have “data model package diagrams”. In this case packages are used to organize data entities into large scale business domains. If you were to remove the Seminar Registration and Java Infrastructure packages from Figure 1 you would have such a diagram, the only difference being that the packages would lead to UML data models instead of UML class models.

Use Case Package Diagrams

Figure 3 depicts a UML use case diagram which has had its use cases organized into packages (the actors are still indicated on the diagram, although they could have been moved into packages as well). Is this really a use case diagram now or is it really a UML package diagram? The important thing is that the diagram somehow adds value to your efforts – how you categorize the diagram is of little real consequence.

When I’m creating a use case package diagram I’ll follow two rules of thumb. First, included and extending use cases belong in the same package as the base/parent use case. This heuristic works well because these use cases typically were introduced by “pulling out” their logic from the base/parent use case to start. Second, I then analyze the use cases with which my main actors are involved. What I typically find is that each actor will interact with the system to fulfill a few main goals, for example, students interact with the university to enroll in it, to manage their schedules, to pay fees, and to manage their loans and grants. Because these four sets of goals are each reasonably cohesive it suggests the need for four separate packages.

Figure 3. Use case package diagram.

Packaging Strategies

Figure 3 is interesting because it shows my typical reason to use packages – to organize a large diagram into several smaller ones. A good rule of thumb is that a diagram should have 7 +/- 2 bubbles on it, a bubble being a use case or class. When a diagram has more bubbles than this it starts to become unwieldy and therefore difficult to understand.

Packages should be cohesive. Anything you put into the package should make sense when considered with the rest of the contents of the package. To determine whether a package is cohesive, a good test is you should be able to give your package a short, descriptive name. If you can’t, then you may have put several unrelated things into the package.

Remaining Agile

I rarely create UML package diagrams in their own right, although I do apply packages on diagrams (particularly when I’m using a CASE tool). I have heard of Java development teams using package diagrams to depict the high-level organization of their code base, Java natively supports packages of classes, although I don’t see how it adds anything beyond the code browsing capabilities of Java development environments. The fact is that I find physical diagrams such as UML component diagrams much more useful.

My best advice is to create a package diagram only if it adds value, and that when you do to keep things as simple as possible.


This artifact description is excerpted from Chapter 10 of The Object Primer 3rd Edition: Agile Model Driven Development with UML 2.



The notation used in these diagrams, particularly the hand drawn ones, may not conform perfectly to the current version of the UML for one or more of reasons:

  • The notation may have evolved from when I originally developed the diagrams. The UML evolves over time, and I may not have kept the diagrams up to date.
  • I may have gotten it wrong in the first place. Although these diagrams were thoroughly reviewed for the book, and have been reviewed by thousands of people online since then, an error may have gotten past of us. We’re only human.
  • I may have chosen to apply the notation in “non-standard” ways. An agile modeler is more interested in created models which communicate effectively than in conforming to notation rules set by a committee.
  • It likely doesn’t matter anyway, because the modeling tool(s) that you’re using likely won’t fully support the current version of the UML notation perfectly anyway. Bottom line is that you’re going to be constrained by your tools anyway.

If you’re really concerned about the nuances of “official” UML notation then read the current version of the UML specification.