Part I. A Collection of Software Architecture Styles
The starting point of architecture design is most often a preexisting package of design decisions. Very few architects design systems completely by closing their eyes, thinking hard, and conjuring up a brand-new design.
A most useful package of design decisions is the architecture style. Chapters 1–5 present a range of important and widely used architecture styles. The emphasis here is on how to document a view that results from the use of a style.
I.1 Three Categories of Styles
Chapters 1–5 are organized along the lines of the three categories of styles we discussed in the prologue: module styles (Chapters 1 and 2), component-and-connector (C&C) styles (Chapters 3 and 4), and allocation styles (Chapter 5). Plan for your documentation package to include at least one module view, at least one component-and-connector view, and at least one allocation view.
Modules are the primary elements of module styles. A module is an implementation unit that provides a coherent set of responsibilities. A module might take the form of a class, a collection of classes, a layer, an aspect, or any decomposition of the implementation unit. Every module has a collection of properties assigned to it. These properties are intended to express the important information associated with the module, as well as constraints on the module. Sample properties are responsibilities, visibility information, and author or owner. The relations that modules have to one another include is part of, depends on, and is a.
A module style is a kind of style that introduces a specific set of module types and specifies rules about how elements of those types can be combined.
Module styles are described in Chapters 1 and 2.
Component-and-connector styles express runtime behavior. They are described in terms of components and connectors. A component is one of the principal processing units of the executing system. Components might be services, processes, threads, filters, repositories, peers, or clients and servers, to name a few. A connector is the interaction mechanism among components. Connectors include pipes, queues, request/reply protocols, direct invocation, event-driven invocation, and so forth. Components and connectors can be decomposed into other components and connectors. The decomposition of a component may include connectors and vice versa.
A component-and-connector style is a kind of style that introduces a specific set of component and connector types and specifies rules about how elements of those types can be combined. Additionally, given that C&C views capture runtime aspects of a system, a C&C style is typically also associated with a computational model that prescribes how data and control flow through systems designed in that style.
C&C styles are described in Chapters 3 and 4.
Allocation styles describe the mapping of software units to elements of an environment in which the software is developed or executes. The environment might be the hardware, the file systems supporting development or deployment, or the development organization(s).
I.2 Style Guides: A Standard Organization for Explaining a Style
Styles presented together for comparison and selection should be described consistently with each other. In this way, an architect can better make an informed decision about which one(s) to use. This is an application of the fourth rule for sound documentation: Use a standard organization. The outline used for describing a style is called a style guide.
An allocation style is a kind of style that describes the mapping of software units to elements of an environment in which the software is developed or executes.
Allocation styles are described in Chapter 5.
The styles in Chapters 1–5 are presented using the form of a style guide. Below is the outline for that style guide.
Outline for a Style Guide
1. Overview. The overview in a style guide explains why this style is useful. It discusses what it is about a system that the style addresses and how it supports reasoning about systems.
A style guide is the description of an architecture style that specifies the vocabulary of design (sets of element and relationship types) and rules (sets of topological and semantic constraints) for how that vocabulary can be used.
2. Element types, relation types, and properties.
a. Elements are the architecture building blocks native to the style. A style guide defines one or more element types, instances of which will populate an architecture that uses that style.
b. Relations determine how the elements work together to accomplish the work of the system. A style guide defines one or more relation types that apply to the style’s element types. An architecture using the style will describe the relations (instances of the relation type) that determine how the elements can work together, and any important properties of those relations. The style guide provides rules on how elements can and cannot be related.
An element is an architecture building block native to the style. An element can be a module, a component or connector, or an element in the environment of the system whose architecture we are documenting. The description of an element tells what role it plays in an architecture, lists its important properties, and furnishes guidelines for effective documentation of the element in a view.
A relation defines how elements cooperate to accomplish the work of the system. The description of a relation names the relations among elements and provides rules on how elements can and cannot be related.
A property contains additional information about elements and relations. A style definition includes the property name and description. When an architect documents a view based on that style, the properties will be given values. Property values are often used to analyze an architecture for its ability to meet quality attribute requirements.
3. Constraints. This section of the style guide lists the rules for putting the elements and relations together to form a valid instance of the style. For example, in a pipe-and-filter style, a pipe is allowed to attach to a filter, but not to another pipe. In a layered style, the layers are laid out adjacently in a stack, not scattered about randomly. In a work-assignment style, every software unit has to be allocated to at least one organizational element.
4. What it’s for. This section of the style guide describes the kind of reasoning supported by views in the style. The intent is to help the architect understand to what purpose(s) a view in this style may be put. This might be how using the style helps in the development process (for example, the “uses” style is good for reasoning about modifiability). Or it might be about how the style helps the product (for instance, pipe-and-filter yields good performance when processing a series of data elements).
5. Notations. This section of the style guide will give descriptions of graphical and/or textual representations that are available and useful to document views in the style. Different notations will also support the conveyance of different kinds of information in the view.
6. Relation to other styles. This section of the style guide describes how views derived from this style might be related to views derived from different styles. For example, views from two different styles might convey different but related information about a system, and the architect would like a way to choose which one to use. This section might also include warnings about other views with which a particular view is often confused, to the detriment of the system and its stakeholders. (Layers and tiers are a good example of this. They are fundamentally different, but are often [mis]used interchangeably.)
7. Examples. This section provides or points to an example of a documented view derived from the given style.
I.3 Choosing Which Element and Relation Properties to Document
The discussion in Chapters 1–5 heavily emphasizes styles, which are documented in published style guides. But as you read about the styles in Part I, remember that the end game is to produce views based on the chosen style. Recall that a view is a representation of a style applied to a particular system—in this case the system whose architecture is being documented.
One of the tasks in documenting a view is deciding which properties of elements to document. Recall from our preceding discussion of style guides that properties are additional information about the elements and their relations that are useful to document. The styles of Chapters 1–5 are each described with a set of properties likely to be useful; consider them suggestions.
When documenting a view, decide on the list of properties to document about the elements in that view. Choose properties that will aid the analysis you wish the documentation to support. Documenting a view, then, includes documenting the values for the properties you chose.
Properties almost always include the name of the element as well as some description of its role or responsibility in the architecture. For example, properties of a layer—an element of the layered style, which is one of the module styles—should include the layer’s name, the units of software the layer contains, and the nature of the capabilities that the layer provides. A layered view will then, for each layer, specify its name, the units of software it contains, and the capabilities it provides.
Beyond these basic properties, however, are properties that will support architecture-based analysis. If you want to analyze an architecture for performance, then properties in some views probably should include an element’s best- and worst-case response times, or the maximum number of events an element can service per time unit. If you want to analyze an architecture for security, then you probably want to document properties that explain levels of encryption and authorization rules for different elements and relations.
So: If you care about quality attribute x, then define properties that will let you analyze for x in the views that are related to achieving x.
Also as you read Chapters 1–5, remember that a view may represent more than one style. In fact, this is the norm. Since all nontrivial software systems employ many styles at once, mandating that each view come from just one style would result in a plethora of views and a very thick architecture document. Some styles can be fruitfully combined, and that combination used to create a view. Component-and-connector styles in particular tend to combine well, and many architects produce a single component-and-connector view for their system that reflects all of the C&C styles they used.
Section 6.6 discusses which styles go together well to produce combined views.
By learning the “pure” (uncombined) styles, however, you can make more informed choices about which ones to combine. Each comes with its own vocabulary (of element and relation types); you can use these vocabularies to build meaningful combined views that carry forward the pedigree of each of their constituent styles.
I.4 Notations for Architecture Views
Notations for documenting views differ considerably in their degree of formality. Roughly speaking, there are three main categories of notation:
1. Informal notations. Views are depicted (often graphically) using general-purpose diagramming and editing tools and visual conventions chosen for the system at hand. The semantics of the description are characterized in natural language and cannot be formally analyzed.
Think carefully about the choice of design notation for each diagram in your architecture documentation. Consider available tool support, the knowledge and the needs of the documentation stakeholders, and the purpose of the diagrams (for example, implementation guidance, analysis, or model and code generation). Some architecture information can be documented more effectively with other notations.
2. Semiformal notations. Views are expressed in a standardized notation that prescribes graphical elements and rules of construction, but does not provide a complete semantic treatment of the meaning of those elements. Rudimentary analysis can be applied to determine if a description satisfies syntactic properties. Unified Modeling Language (UML) is a semiformal notation in this sense.
3. Formal notations. Views are described in a notation that has a precise (usually mathematically based) semantics. Formal analysis of both syntax and semantics is possible. There are a variety of formal notations for software architecture available, although none of them can be said to be in widespread use. Generally referred to as architecture description languages (ADLs), they typically provide both a graphical vocabulary and an underlying semantics for architecture representation. In some cases these notations are specialized to particular styles. In others they allow many styles, or even provide the ability to formally define new styles. The usefulness of ADLs lies in their ability to support automation through associated tools—automation to provide useful analysis of the architecture, or automation to assist in code generation.
An architecture description language is a language for representing a software and/or system architecture. ADLs are usually graphical languages that provide semantics that enable analysis and reasoning about architectures, often using associated tools.
Appendix C describes one particular architecture description language, called AADL, in depth. The “For Further Reading” section of Chapter 3 provides resources for learning about other ADLs.
Determining which form of notation to use involves making several trade-offs. Typically more-formal notations take more time and effort to create, but they repay this effort in reduced ambiguity and better opportunities for analysis. Conversely, more-informal notations are easier to create, but they provide fewer guarantees.
We’ll see examples of views rendered in these different kinds of notations throughout Part I.
There is no greater impediment to the advancement of knowledge than the ambiguity of words.
—Thomas Reid, Scottish philosopher
I.5 Examples
Throughout this book, but especially in Part I, we will present many examples of architecture documentation fragments extracted from real systems. When you look at these examples, please keep in mind the following notes:
• The goal is for you to understand the kinds of information the example conveys and how the chosen notation is used to depict different types of elements and relations.
• The goal is usually not for you to understand the meaning of the specific elements and relations, that is, the responsibilities they satisfy. Any software system uses acronyms and internal jargon that become part of the vocabulary of the stakeholders familiar with that system. The examples in the book should allow you to recognize what information the architect wanted to capture without knowing the meaning of these terms.
• For each example, the piece extracted from the original architecture documentation is typically just a diagram. To that diagram we add a brief description with information that can’t really be inferred by the diagram alone. This information comes from other parts of each system’s architecture documentation that are not reproduced in the book. A diagram is not enough to document a view!
• We chose diagrams that we think are good examples of different styles and notations. However, they may not be perfect with respect to notation choice and usage, diagramming aesthetics, and quality of the design itself.
• Very often architecture diagrams do not show a single style in its pure form. In many of our examples, you will be able to find vestiges of styles other than the one the diagram is illustrating. That’s normal.
• The example does not necessarily show the latest version of the design.