In some situations, decisions about some aspects of an architecture have not yet been made, but the options still need to be documented. We distinguish two cases: variability and dynamism.
Variability in an architecture can occur because
In the first two cases, three kinds of information need to be documented.
Variability refers to the decisions that will be made by a member of the development team prior to system deployment.
A variation point is a place in the architecture where a specific decision has been narrowed to several options but the option to be chosen for a particular system has been left open.
In the case of documenting a framework, extension points need to be documented. An extension point is a place in the architecture where additional elements can be added. Each extension point is documented by an interface description of what the framework provides and the extension requires.
So-called reference architectures provide a collection of categories for elements. The type of the elements is specified and some indication of how they relate, but the specification for the elements is not sufficient to give more than an indication of their responsibilities. Figure 6.17 shows the ECMA "toaster" model for the integration of development tools.
Figure 6.17. The ECMA toaster model for integrating development tools. This multidimensional layered diagram shows that services are provided within the integration framework for data integration, control integration, and process integration. Tools provide the layers, and a single user interface applies to all the tools (NIST special publication 500-201, ECMA, Technical Report ECMA TR/55, 2d Edition, 12, 1991, p 23).
Regardless of the type of variation, the documentation suite should include a variability guide where points of variation are identified, rationale for choosing one option over another are given, and the APIs are identified for extensions. The variability guide also describes what needs to be doneranging from editing a configuration file to implementing new modulesin order to choose an alternative that fulfills certain interfaces.
Dynamism refers to the decisions that will be made or reconsidered by the system itself during execution.
Architectures change during runtime in response to user requirements or to better enable the achievement of particular quality attributes. An architecture can change dynamically by creating or deleting components and connectors, including replicas. Components or connectors can be created or deleted either in a fine-grained (e.g., object) or a coarse-grained (e.g., client) fashion. For example, when a new user enters an environment and wants new services, components to provide those services would be created. When the user leaves the environment, the components would be deleted. The created component or connector may be a replica or a singleton. In any case, the number of allowable replicas, the conditions under which the creation or deletion occurs, and the connectors or components that are created must be documented.
Another way in which an architecture can change dynamically is by reallocation of resources or responsibilities. Components may be moved from one processor to another to offer better performance. Responsibilities may be shifted among components; perhaps a backup could assume primary status in the event of a failure. Other resources that affect the architecture could also be reallocated. Again, the circumstances under which resources are reallocated and the particular reallocation that will occur must be documented.
6.4.3 Recording the Information
Document variability and dynamism using the same styles you normally would choose for that architecture. Show what is constant and what is not. For the latter, describe the range of options and when the option is bound.
Fortunately, the same work is involved in documenting dynamism and variability in architectures. We provide a few simple rules for documenting architectures with those characteristics:
6.4.4 Notations for Variability and Dynamism
Variation points contain information needed to choose a variant. Some of the attributes that may be used to characterize the variation point are name, description, optional or mandatory, binding time for variation decision, number of possible occurrences of the variants, and the rules for choosing the option(s) listed. Variation points can be represented graphically by any symbol that represents options. Each option is then attached to this symbol.
A variation point is a place in the architecture where a specific decision has been narrowed to several options but the option for a particular system has been left open. Figure 6.18 shows a variation point.
Figure 6.18. A narrowly based variation point. This example is derived from a radio display software system. The display will show a station by displaying either a frequency or a station name. The ovals show a variation point and the possible options with a specific rulechoose 1that guides the selection process. Depending on the choice, particular modules, depicted as rectangles, will be included in the architecture (Bachmann and Bass 2001, p. 131).
A broadly based variation point is one in which very few of the decisions have been made (see Figure 6.17). Intentionally, only some decisions are made here to support integration into the process and user interface environment. A variability guide in this case should include specifications that have to be fulfilled and perhaps some design or implementation rules.
In an informal graphical notation, component replication is almost always documented showing shadow boxes:
Almost always lacking are an indication of the possible range of replication and when the actual number is bound. Make sure to include both. For example:
Creation and Deletion of Components or Connectors
Chapter 8 describes notations that can be used to indicate the creation and deletion of components or connectors. An example is a UML sequence diagram, in which a line on a time-line scale is used to indicate the existence of a component or a connector.
Some forms of reallocation of resources, such as the migration of objects, can be described by the UML construct become. This is represented by a dashed arrow whose tail is on the original location of an object and whose head is on the subsequent location.
What Time Is It?
When I was a student first learning to program, a concept that gave me fits was compile time versus runtime information. Put in post-Watergate terms: What does the software know, and when does it know it? I struggled with this until, of all things, I took a written multiple-choice exam one year to renew my driver's license. One of the questions was about signage. The question asked the meaning of a sign like this:
The possible answers were (a) road slippery when wet, (b) dangerous curve, (c) reduce speed, (d) drunk driver ahead.
The last choice made me laugh out loud. The attendants supervising the exam smiled, having no doubt which question I was on. But I was laughing because the concept of runtime versus compile time was no longer a mystery: A slippery road is slippery every time it gets wet, but a drunk driver comes and goes, and no static sign, which was installed before the road's "runtime," can be correct all the time.
Since then, I've learned that those two "times" are but a few of the possible stages of a software system's life at which bindings occur that can affect its behavior. Other times of importance are
Why is all this relevant? Because documenting when things can change is as important as documenting what things can change. Take care to consider all the possible times at which you want variabilities to be available, and specify the mechanisms by which the available choices are made.
Software Architectures and Documentation
Part I. Software Architecture Viewtypes and Styles
The Module Viewtype
Styles of the Module Viewtype
The Component-and-Connector Viewtype
Styles of the Component-and-Connector Viewtype
The Allocation Viewtype and Styles
Part II. Software Architecture Documentation in Practice
Documenting Software Interfaces
Choosing the Views
Building the Documentation Package
Other Views and Beyond
Rationale, Background, and Design Constraints