Documenting Variability and Dynamism

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.

6.4.1 Variability

Variability in an architecture can occur because

• Some set of decisions has not yet been made during the design process for a single system, but options have been explored
• The architecture is for a family of systems, and the option taken will depend on the specifics of the particular member of the family to be constructed
• The architecture is a framework for a collection of systems and contains explicit places where extensions to the framework can occur

In the first two cases, three kinds of information need to be documented.

1. The variation points. A variation point is the place in the architecture where variation can occur. The options within a variation point are a list of alternatives. Each alternative has, in turn, a list of elements impacted if that option is chosen.
2. The elements affected by the option. Each option will affect the existence of an element, its interface, the properties of that element, or the relations among the elements. An element can exist in one option and not in another. An element can exist in two options but compute different functions or have different properties. For example, multiple elements may realize a particular interface. Two elements can be related in one fashion in one option and in another fashion or not at all in another option. The elements and relations affected by an option need to be documented.
3. The binding time of an option. Choosing different binding times for elements affects their properties. For example, deciding to bind two components during initial load time will yield different system properties than deciding to bind these two components through a dynamic link mechanism. Possible binding times include design time, compile time, link time, or runtime; if it is runtime, many options are possible. Binding can be done when the program starts or restarts, when the program containing the option starts, or at any other time during execution.

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.

6.4.2 Dynamism

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

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:

1. Choose from the same styles you normally would. That is, there is no special style that you must use specifically to document dynamism or variability. If your possible architectures differ logically, choose a module view to show the variation. If they differ in the processes they contain, choose a communicating-processes view to show the variation, and so forth. On the other hand, if there are many variation points, it may be useful to have a specific view that shows just the variation points. This view would appear in the variability guide.
2. Show what's constant and what's not. Each view you choose should indicate places where the architecture is the same across all possibilities and where it may vary.
3. Denote when the change can take place. When you document variability, indicate whether the alternatives apply at design time, at build time, at runtime or at some finer shading of one of these (such as compile time or link time).
4. Document dependencies among options. When variabilities or dyanamic options are linked, show that linkage.
5. Use scenarios of building different types of systems as a portion of the variability guide. Begin with constructing a simple system and progress to more complicated ones. Scenarios should show dependencies among options.

6.4.4 Notations for Variability and Dynamism

Informal Notations

Variation Point

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.

Component Replication

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.

Reallocating Resources

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.