The Fortress Language Specification - CiteSeerX

should specify all the information that is traditionally provided for the published APIs of libraries in other languages.
The syntax of an API definition is identical to the syntax of a component definition, except that:
1. An API definition begins with the special reserved word api rather than component . As with components,
the identifiers associated with APIs that are not included in the Fortress standard libraries are prefixed with the
reverse of the URL of the development team.
2. An API does not include export declarations. (However, it does include import declarations, which name
the other APIs used in the API definition.)
3. Only declarations (but not definitions!) are included in an API definition except test and property declarations. A
method or field declaration may include the modifier abstract . (Whether a declaration includes the modifier
abstract has a significant effect on its meaning, as discussed below).
For the sake of simplicity, every identifier reference in an API definition must refer either to a declaration in a used
API (i.e., an API named in an import declaration, or the Fortress core APIs, which are implicitly imported), or to a
declaration in the API itself. In this way, APIs differ from signatures in most module systems: they are not parametric
in their external dependencies.
Every API has a unique name that consists of a user-provided identifier. As with components, API equivalence is
determined nominally. Every API also includes a vendor name, the name of the fortress it is compiled on, and a
timestamp.
Component and API names exist in separate namespaces. For convenience, a compiler can also produce an API
directly from a project with the same name as the component it is derived from. Such an API includes matching
declarations of the component. All declarations in the component appear in the API.
A component must include, for every API A it exports, matching definitions for all the declarations in A. A matching
definition of a declaration d is a definition d ′ with the same name as d that includes definitions for all declarations
other than the methods or fields declared abstract in d. The header and type of d ′ must be the same as the header
and type of d. d ′ may include additional definitions not declared in d.
For example, consider the APIs Fortress.IO, Fortress.Security, and Fortress.Crypto, with declarations similar
to those in their respective Java packages. These APIs are interdependent. For example, both PublicKey in
Fortress.Security and SecretKey in Fortress.Crypto extend the trait Fortress.IO.Serializable and the trait CipherSpi
in Fortress.Crypto has methods that return values of type AlgorithmParameters in Fortress.Security. So the API
Fortress.Crypto must import Fortress.IO and Fortress.Security as follows:
api Fortress.Crypto
import Fortress.IO
import Fortress.Security
. . .
end
22.4 Tests in Components and APIs
A component may include definitions of tests, as described in Chapter 19. These definitions are allowed to refer to
both test and non-test code defined in the same component or declared in APIs imported by the component.
An API may also include definitions of tests. These definitions may refer to all declarations in the API as well as in
any APIs it imports. Tests defined in APIs should be thought of as “executable documentation” that partially specifies
the required behavior of the declared entities.
See Section 22.7 for an explanation of how tests defined in components and APIs are executed.
166