Overview

Early treatments of architecture and architecture description languages devoted loving attention to the elements of the system and their interactions but tended to overlook the interfaces to those elements. It was as though interfaces were not part of the architecture. Clearly, however, interfaces are supremely architectural, for one cannot perform analyses or system building without them. Therefore, a critical part of documenting a view includes documenting the interfaces of the elements shown in that view.

The characteristics of an interface depend on the viewtype of its element. If the element is a component, the interface represents a specific point of potential interaction of a component with its environment. If the element is a module, the interface is a definition of services. There is a relation between these two kinds of interfaces, just as there is a relation between components and modules.

By the element's environment, we mean the set of other entities with which it interacts. We call those other entities actors. In general, an actor is an abstraction for external entities that interact with the system. Here, we focus on elements and expand the definition of interaction to include anything one element does that can impact the processing of another element. This interaction is part of the element's interface. Interactions can take a variety of forms. Most involve the transfer of control and/or data. Some are supported by standard programming language constructs, such as local or remote procedure calls, data streams, shared memory, and message passing. These constructs, which provide points of direct interaction with an element, are called resources.

Other interactions are indirect. For example, the fact that using resource X on element A leaves element B in a particular state is something that other elements using the resource may need to know if it affects their processing, even though they never interact with A directly. That fact about A is a part of the interface between A and the other elements in A's environment.

An interaction extends beyond merely what happens. For example, if element X calls element Y, the amount of time that Y takes before returning control to X is part of Y's interface to X because it affects X's processing.

Let's establish some principles about interfaces.

• All elements have interfaces. All elements interact with their environment.
• An element's interface contains view-specific information. Because an element can occur in more than one view, aspects of its interface can be documented in each view, using the vocabulary of that view. For instance, an interface to a module in a uses view might describe which methods are provided, but an interface to the same module in a work assignment view would not include this information. In fact, some views may have little interface information to document. (Whether an architect chooses to document an element's interface separately in different views or in a single treatment is a packaging issue. An interface that transcends views can be documented in the package of documentation that applies to more than one view.)
• Interfaces are two-way. When considering interfaces, most software engineers first think of a summary of what an element provides. What methods does the element make available? What events does it process? But an element also interacts with its environment by making use of resources or assuming that its environment behaves in a certain way. Without these resources, or absent an environment behaving as expected, the element can't function correctly. So an interface is more than what is provided by an element; an interface also includes what is required by an element. The requires part of an element's interface typically comes in two varieties:

  - Resources on which an element builds. This kind of resource is something that is used in the implementation of the element, such as class libraries or toolkits, but often it is not information that other elements use in interacting with the element. This type of resource requirement is typically documented by naming the library, version, and platform of the resource. A build will generally quickly uncover any unsatisfied interface requirements of this kind.

  - Assumptions that the element makes of other elements with which it interacts. For example, an element could assume the presence of a database using specific schema over which it can make SQL (Structured Query Language) queries. Or an element may require its actors to call an init() method before it allows queries. This type of information is critical to documentafter all, the system won't work if the requirement is not metand not easily uncovered if not satisfied.

  When we say that an interface includes what is required, we're focusing on what interactions an element requires from its environment to complete an interaction it provides.

• An element can have multiple interfaces. Each interface contains a separate collection of resources that have a related logical purpose, or represent a role that the element could fill, and serves a different class of elements. Multiple interfaces provide a separation of concerns, which has obvious benefits. A user of the element, for example, might require only a subset of the functionality provided by the element. If the element has multiple interfaces, perhaps the developer's requirements line up nicely with one of the interfaces, meaning that the developer would have to learn only the interface that mattered to him or her rather than the complete set of resources provided by the element. Conversely, the provider of an element may want to grant users different access rights, such as read or write, to prevent resource contention or to implement a security policy. Multiple interfaces support different levels of access.

  Multiple interfaces also support evolution in open-market situations. If you put an element in the commercial market and the element's interface changes, you can't recall and fix everything that uses the old version. So you can support evolution by keeping the old one but adding the new interface.

• An element can interact with more than one actor through the same interface. Document any limits on the number of actors that can interact with an element via a particular interface. For example, Web servers often restrict the number of simultaneously open HTTP connections.
• Sometimes, it's useful to have interface types, as well as interface instances. Like all types, an interface type is a template for a set of instances. Some notations support this concept, which we noted in some of the view examples in the C&C viewtype.

  Many times, all the interfaces you're designing will include a standard set of resources, such as an initialization program; a set of standard exception conditions, such as failing to have called the initialization program; a standard way to handle exceptions, such as invoking a named error handler; or a standard statement of semantics, such as persistence of stored information. It is convenient to write these standard interface "parts" as an interface type. Sometimes, an element has multiple interfaces that are identical: A component that merges two input streams might be designed with two separate but identical interfaces. It is convenient to write these identical interfaces as an interface type. An interface type can be documented in the architecture's beyond view documentation.