1. ISpec: A Compositional Approach to Interface Specification
Hans Jonkers HJ
ISpec

2. Introduction
ISpec:
an incremental, structured, compositional approach to Interface Specification
Focus:
interfaces in the context of component technology
Rationale:
increasing use of component technology in Philips PDs
importance of interfaces in product family architectures
no ready-made practical and sound approach available HJ
ISpec

3. Component Technology Component (Szyperski): Component technologies:
“A software component is a unit of composition with contractually specified interfaces and explicit context dependencies only. A software component can be deployed independently and is subject to composition by third parties.”
Component technologies:
Provide the “wiring technology” for components
Examples: COM(+), .NET, J2EE, CORBA, Koala
ISpec focuses on “COM/.NET-like” components HJ
ISpec

4. Main Objectives Provide an approach to interface specification that
provides a considerable improvement on the current quality of interface specifications
is practically feasible and acceptable to industrial software engineers
fits in with main-stream O-O modeling techniques (UML)
avoids the YASL syndrom HJ
ISpec

5. Main Features of ISpec multiple levels of detail and formality
a contractual view of interfaces
a model-based style of specification
restricted use of object-oriented modeling (UML)
template-based construction of specifications
interface specifications as composable entities HJ
ISpec

6. Usage of ISpec
Large-scale investments in writing proper interface specifications pay off in case of long-lived interfaces (APIs) only.
Usage of ISpec in Philips:
Medical Systems: specification of MIP interfaces (Medical Imaging Platform)
Semiconductors: specification of DVP interfaces (Digital Video Platform)
In both cases customized versions of ISpec are used. HJ
ISpec

7. Specification as a Balancing ActHJ
ISpec

8. Unit of Specification Possible choices: Interface
Group of interfaces associated with the same HW/SW implementation unit (“physical component”)
Group of interfaces associated with the same functional unit (“logical component”)
interface suite HJ
ISpec

9. Interface Suites
interface suite: a collection of mutually related interfaces providing access to coherent functionality
Example: Microsoft COM connection point interface suite HJ
ISpec

10. Contractual View ISpec specifications are based on a contractual view:
The specification of an interface suite, is considered a contract between the providers and users of the interfaces in the suite.
The contract identifies, among other things:
The functionality defined by the suite
The interfaces contained in the suite
The contractual parties, represented by roles
The relations between roles and interfaces (“provides”, “requires”) and between roles (“specializes”)
The terms and concepts associated with the suite
The rights and obligations associated with the roles HJ
ISpec

11. Interface-Role Model
The interface-role model takes a central place in an ISpec specification.
It is an enhanced UML class diagram summarizing the main ingredients of the contract:
the roles
the interfaces associated with roles
the provides and requires relation between roles and interfaces
the specializes relation between roles HJ
ISpec

12. Observer Interface-Role ModelHJ
ISpec

13. Contractual Interpretation
An implementer that signs for one or more roles in an i-spec S
has the right to use an interface I defined in S if and only if he has signed for a role that requires I.
has the right to provide an interface I defined in S if and only if he has signed for a role R that provides I.
has the obligation to provide all interfaces provided by the roles he signed for. HJ
ISpec

14. AnalogAudioDecoder IR-ModelHJ
ISpec

15. IR Model: UML NotationsHJ
ISpec

16. Why Roles?
We need some way to refer to the providers and users of interfaces without referring to implementation entities
Roles embody the relations between interfaces
Roles help in structuring the functionality
Roles are placeholders for specifying behavior; interfaces act as the ‘windows’ on this behavior
Roles support the construction of a specification as a contract HJ
ISpec

17. API Specifications as Contracts
identifies the
functionality
identifies the interfaces
identifies the roles
defines the terms and concepts
defines the rights and obligations of roles HJ
ISpec

18. Implementing = “Signing” the Contract (1)HJ
ISpec

19. Implementing = “Signing” the Contract (2)HJ
ISpec

20. Implementing Roles The implementer of a role
should guarantee that all obligations of the role are satisfied
may rely on the obligations of other roles being satisfied
An implementation of an interface defined by an
i-spec is an implementation of the role providing
the interface. HJ
ISpec

21. Playing Roles An object may play multiple roles
A role may be played by multiple objects HJ
ISpec

22. ISpec Contract StructureHJ
ISpec

23. Observer I-Spec interface-role diagram abstract-model diagram
semantic constraints
attach
Signature
void attach( Observer obs )
Summary
Registers an observer.
Parameters
obs: the observer to be registered.
Return value
None
Precondition
true
Action
modify observers
Postcondition
observers = observers’  { obs }
..... HJ
ISpec

24. Model-Based Specification
Specifying a system by means of an abstract model amounts to defining an “abstract implementation” of the system.
An implementation conforms to the specification if it behaves “in the same way” as the abstract model.
Essential notion: observable behaviour HJ
ISpec

25. Observable Behaviour
An implementation conforms to a model-based specification if its observable behaviour is consistent with that of the model.
This requires a proper definition of which parts of the behaviour of a model are observable.
General definition:
The observable behaviour of a model consists of the interactions that can be observed at the external software and hardware interfaces of roles.
Consequence: Defining observable behaviour may require explicit hardware modelling. HJ
ISpec

26. Impressionistic versus Expressionistic Modeling
ISpec HJ
ISpec

27. Abstract Model Diagram
The abstract model diagram is
defined by specializing the interface-
role diagram, i.e. by
associating attributes and relations with roles
introducing auxiliary roles and methods where appropriate
It defines the vocabulary of an i-spec HJ
ISpec

28. Observer Abstract Model DiagramHJ
ISpec

29. Specifying Behaviour
Behaviour is specified in terms of the vocabulary defined by the abstract model diagram
Attributes associate state with roles
Elementary actions:
state transitions
method calls
method returns
Behaviour is phrased in terms of rights and obligations associated with roles
Only observable behaviour is relevant HJ
ISpec

30. Method Behaviour HJ
ISpec

31. Behavioral Aspects of Methods
initial state
final state
modification rights
out-calls
interaction
threading
activation
timing
How to specify:
 precondition
 postcondition
 action clause
 Thread class
 activation tables
 clock HJ
ISpec

32. Extended Pre & Post Specs
An extended pre- and post-condition specification has an additional action clause providing an abstract operational description of the method.
Method Specification
Method f(...)
Precondition P
Action A
Postcondition Q
Contractual Interpretation
if the caller guarantees condition P is true immediately before the call
then the callee
will perform action A and
guarantees that condition Q is true immediately after the call HJ
ISpec

33. Example Method void increment() Precondition x  0 Action modify x
y.foo()
Postcondition
x = x’ + 1
changes value of x in unspecified way
out-call
refers to ‘old’ value of x HJ
ISpec

34. Composing Specifications
Unit of interface specification: interface suite
Interface suite is specified in separate document: s-doc
An s-doc S may be based on s-docs S1, ..., Sn implying that
S includes the texts of S1, ..., Sn
additions of S to S1, ..., Sn are conservative (“Closed World Assumption”)
delta-spec HJ
ISpec

35. Composing the Observer Spec
In delta-spec of
ConcreteObserver:
update() should call getState() so as to update state HJ
ISpec

36. Composing the AA Decoder SpecHJ
ISpec

37. Interface Suite HierarchyHJ
ISpec

38. Document Structure Main Purpose
list the external interface suites used
explain the concepts
define the semantics
map to the technology
provide hints for interface users
provide hints for interface providers
provide an alphabetical list of terms
the contractual stuff HJ
ISpec

39. Specification TemplatesHJ
ISpec

40. More on ISpec
General:
Hans Jonkers, ISpec: Towards Practical and Sound Interface Specifications, IFM 2000.
Compositionality:
Hans Jonkers, Interface-Centric Architecture Descriptions, WICSA 2001. HJ
ISpec