Architecture = Components + Interfaces

Architecture = Components + Interfaces

The ARCs view architecture as a project's major components, the major interfaces between them, the interfaces to other projects, and all customer-visible interfaces.

Project teams describe their architecture to the ARC using both an architectural block diagram and an interface table. Ideally, a code or brief name relates interfaces between these two representations.

Interfaces

The ARC definition of "interface" is broad -- any syntax or semantics that another project (or a human) could depend on. It is not limited to APIs nor limited to customer-visible project boundaries. Some common kinds of interfaces are:

1. Libraries (APIs and SPIs, both functions and header files)
2. Command Line Utilities (applications or configuration or administration tools)
3. Graphical User Interfaces (GUIs)
4. Character User Interfaces (CUIs)
5. Command line Interpreter languages
6. Input/output file formats
7. Resource & configuration file names and formats
8. Databases (and their schemas)
9. Protocols or inter-component messages
10. Log files
11. Solaris package names
12. Java package names
13. Daemons
14. URLs
15. Windows EXEs, DLLs, VxDs, and registry IDs

Interface Stability Classifications

Each interface is assigned a stability/commitment classification from the Interface Taxonomy document as a key part of the architecture review.

The primary motivations for enumerating and classifying interfaces are to correctly set customer expectations, use language that is consistently understood within Sun, and determine the release level and conditions for making a future incompatible change. The following table summarizes the important classifications for Open (that is, customer-visible) interfaces.

"Public" Interface Stability Classifications

As you can see, the stability level determines whether a specification of the interface's syntax and semantics (such as a manpage) must be submitted to and reviewed by the ARC. A project can't be approved until the interfaces are enumerated and assigned stability classifications and -- where appropriate -- a specification of the syntax and semantics is submitted and reviewed. Get help from your case owner in completing the interface table.

For a Standard interface, a pointer to the specification (with version number or date) is usually sufficient. For Internet RFCs, include the RFC's status. Some standards lack bindings to a specific programming language; if you've chosen syntax, arguments, names, or numbers, they're not Standard (but are probably Public or Evolving). Also document any differences between the specification and the implementation -- implementation-specific details, unimplemented features, extensions, requirements, assumptions.

For a Stable interface, a reasonably-brief specification must be submitted with the case materials, and reviewed by the committee. Customer documentation is also required.

"Evolving" and "Unstable" interfaces also require a specification be submitted and reviewed. Customer documentation is also expected. Customer documentation should include attributes (See the attributes(5) manpage's Interface Stability section) describing the risk that in a future release the interface may be changed or dropped.

For an "Imported" interface, the goal is to specify what aspects of the interface must not change, in order to avoid breaking your implementation. That is, the ARCs look at the case that exported the interfaces you are importing and raises concerns if the exported stability level is insufficient for safe reuse.

Some interfaces (e.g., ToolTalk, a filename used) have one commitment level, but the actual messages transmitted (or file contents or format) may have a different stability classification.

The following table summarizes the Private interface classifications, for which no documentation is published (and we do not want others depending on or reimplementing the interface). We still assign a stability classification, to express the intended scope of an interface (who can use it) and what types of releases can introduce incompatibilities. In general, the more exposed an interface is, the more difficult it is to coordinate incompatible change, and therefore the less frequently we expect it to occur.

"Private" Interface Stability Classifications

Non-ARC Documents (whitepapers, developer guides...) that include descriptions and specifications of Private interfaces should include this warning:

A Private interface is an interface provided by a component (or a subset of a component) intended only for use by that component. A Private interface might still be visible to or accessible by other components. Because the use of interfaces private to another component carries great stability risks, such reuse is not recommended.

Publication of these documents do not of themselves constitute a commitment to implement, deliver in any product, or support the use of any interface described therein. See attributes(5) and the Interface Taxonomy for more information about interface stability.

Committed Private is an odd case, in that we don't expect customers to notice incompatibilities, even though we don't document the interface for them. This is used for files or protocols that must cross system (and hence, product-release boundaries); we don't generally expect customers to upgrade all their machines simultaneously. For a "Committed Private" interface, the ARC will at least assure that the interface can satisfy its purpose and support evolution so that "normal use" will be sufficiently seamless between invocations, between hosts, and across releases.

For a "Contracted Private" interfaces, the specification already agreed between the parties should be reviewed by the ARC. The ARC will at least assure that the interface can satisfy its purpose and support evolution in the way described in the contract. A "Contract Private" interface (between projects) requires a architectural dependency contract be submitted and reviewed.