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.
An interface is a boundary across which two independent entities meet and interact or communicate with each other.
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.
An element's actors are the other elements, users, or systems with which it interacts.
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.
- 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.
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.
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.
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