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.

There were a hundred and forty-two staircases at Hogwarts: wide, sweeping ones, narrow, rickety ones; some that led somewhere different on a Friday; some with a vanishing step halfway up that you had to remember to jump. Then there were doors that wouldn't open unless you asked politely, or tickled them in exactly the right place, and doors that weren't really doors at all, but solid walls just pretending. It was also very hard to remember where anything was, because it all seemed to move around a lot. . . .

And the ghosts didn't help, either.

J. K. Rowling, Harry Potter and the Sorcerer's Stone (Scholastic Press, 1998, p. 122)

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.

DEFINITION

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.

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

DEFINITION

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

ADVICE

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:

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.

PERSPECTIVES

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

• Program write time, when most design decisions are frozen into code, including the decisions not to bind certain decisions, which are inserted into the code as points of variation to be bound at one of the later times.
• Compile time, when variation points that can be understood by a compiler are bound. Through macro facilities, such as #ifdef, alternative versions of the code can be selected. Parameters, often numbers, can be assigned their value. Compile-time parameters are used to achieve the effect of multiple copies of the source code that differ in slight ways but without having to maintain actual copies.
• Link time, when the system build environment looks around for all the files and external definitions it expects to have available at runtime. Some late-binding parameters are bound at link time, especially those having to do with versions of external filescomponentswith which the main program expects to interact.
• Program start-up time, when programs take special actions, which may be made to vary, the first time or each time they are powered up. For example, a large air traffic control system reads a massive file of adaptation data each time it starts. The data is a rich compendium of directions to the software, telling it the displays and display formats chosen by its human users, what the geography is like where it's been installed, how to divide the local sky into sectors, and a host of other tailoring information. Another example is the worm that, on finding itself infiltrated into your computer, consults your address book to see where to send itself.
• Runtime, when many decisions in modern infrastructures are bound. Browsers patiently wait while their users obtain necessary plug-ins on demand; middleware oversees the negotiation of compatible interfaces among components written in almost total ignorance of one another. And architectures that we call dynamic change their shape and connectivity.

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.

P.C.C.