ISpec: A Compositional Approach
to Interface Specification
Hans Jonkers
Philips
Research
HJ031120-1
ISpec
© Koninklijke Philips Electronics N.V. 2003
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
Philips
Research
HJ031120-2
ISpec
© Koninklijke Philips Electronics N.V. 2003
Component Technology
• Component (Szyperski):
– “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
Philips
Research
HJ031120-3
ISpec
© Koninklijke Philips Electronics N.V. 2003
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
Philips
Research
HJ031120-4
ISpec
© Koninklijke Philips Electronics N.V. 2003
Main Features of ISpec
•
•
•
•
•
•
Philips
Research
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
HJ031120-5
ISpec
© Koninklijke Philips Electronics N.V. 2003
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.
Philips
Research
HJ031120-6
ISpec
© Koninklijke Philips Electronics N.V. 2003
Specification as a Balancing Act
formal
operational
specification
declarative
specification
informal
underspecification
Philips
Research
HJ031120-7
overspecification
ISpec
© Koninklijke Philips Electronics N.V. 2003
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
Philips
Research
HJ031120-8
ISpec
© Koninklijke Philips Electronics N.V. 2003
Interface Suites
interface suite: a collection of mutually related interfaces
providing access to coherent functionality
Example: Microsoft COM connection point interface suite
IConnectionPointContainer
ConnectableObject
ConnectionPointUser
creates
IEnumConnectionPoints
ConnectionPointEnumerator
enumerates
1..*
IConnectionPoint
ConnectionPoint
creates
IEnumConnections
ConnectionEnumerator
Philips
Research
HJ031120-9
ISpec
© Koninklijke Philips Electronics N.V. 2003
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
Philips
Research
HJ031120-10
ISpec
© Koninklijke Philips Electronics N.V. 2003
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
Philips
Research
HJ031120-11
ISpec
© Koninklijke Philips Electronics N.V. 2003
Observer Interface-Role Model
IAttach
Subject
Observer
IUpdate
Concrete
Subject
Philips
Research
HJ031120-12
IState
Concrete
Observer
ISpec
© Koninklijke Philips Electronics N.V. 2003
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.
Philips
Research
HJ031120-13
ISpec
© Koninklijke Philips Electronics N.V. 2003
AnalogAudioDecoder IR-Model
AnalogAudio
Connection
Manager
AnalogAudio
Source
AnalogAudio
Decoder
IAnalogAudioSelection
IAnalogAudioDecodeNotify
IAnalogAudioDecode
IPinObjects
PinObjects
Provider
AnalogAudio
Client
IPinObjects
PinObjects
Client
AnalogAudio
ProgramSelector
1..*
Philips
Research
HJ031120-14
ISpec
© Koninklijke Philips Electronics N.V. 2003
AnalogAudio
Sink
IR Model: UML Notations
Role P
specializes relation
Role Q
requires relation
requires relation
interface
interface
provides relation
optional provides relation
Role R
stream
Role S
input relation
output relation
logical component
Philips
Research
HJ031120-15
stream
ISpec
© Koninklijke Philips Electronics N.V. 2003
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
Philips
Research
HJ031120-16
ISpec
© Koninklijke Philips Electronics N.V. 2003
API Specifications as Contracts
identifies the
functionality
... CONTRACT
IP
Role P
IR
identifies
the interfaces
identifies the roles
Role R
IQ
Role Q
defines the
terms and concepts
defines the rights and
obligations of roles
Signatures
Role P:
Role Q:
Role R:
Philips
Research
HJ031120-17
ISpec
© Koninklijke Philips Electronics N.V. 2003
Implementing = “Signing” the Contract (1)
CONTRACT
Implementation
IP
Role P
plays
IP
Class A
IR
IB
Role R
IQ
Role Q
plays
IQ
Class B
Signatures
implementer of A signs here
Role P:
implementer of B signs here
Role Q:
role R player should sign here
Role R:
Philips
Research
HJ031120-18
ISpec
© Koninklijke Philips Electronics N.V. 2003
Implementing = “Signing” the Contract (2)
CONTRACT
Implementation
IP
Role P
plays
IR
IP
IQ
Role R
IQ
Role Q
Class C
plays
Signatures
implementer of C signs here
Role P:
and here
Role Q:
role R player should sign here
Role R:
Philips
Research
HJ031120-19
ISpec
© Koninklijke Philips Electronics N.V. 2003
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.
Philips
Research
HJ031120-20
ISpec
© Koninklijke Philips Electronics N.V. 2003
Playing Roles
• An object may play multiple roles
• A role may be played by multiple objects
Class A
Philips
Research
HJ031120-21
Role P
Role Q
Class B
Class C
ISpec
© Koninklijke Philips Electronics N.V. 2003
Role R
ISpec Contract Structure
CONTRACT
interface-role
diagram
roles & interfaces (signature)
specializes
abstract-model
diagram
terms & concepts (vocabulary)
augment
semantic
constraints
Philips
Research
HJ031120-22
semantic rights & obligations (behaviour)
ISpec
© Koninklijke Philips Electronics N.V. 2003
Observer I-Spec
interface-role diagram
abstract-model diagram
semantic constraints
IAttach
IAttach
Subject
Subject
Observer
0..*
attach(obs : Observer)
detach(obs : Observer)
observers
Observer
notify()
IUpdate
IUpdate
update()
IState
Concrete
Subject
ConcreteSubject
IState
Concrete
Observer
getState() : State
state : State
ConcreteObserver
state : State
changeState(new : State)
subject
1
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 }
.....
Philips
Research
HJ031120-23
ISpec
© Koninklijke Philips Electronics N.V. 2003
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.
should behave
"in the same way" as
implementation
model
Essential notion: observable behaviour
Philips
Research
HJ031120-24
ISpec
© Koninklijke Philips Electronics N.V. 2003
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.
Philips
Research
HJ031120-25
ISpec
© Koninklijke Philips Electronics N.V. 2003
Impressionistic versus
Expressionistic Modeling
class
diagram
use case
diagram
collaboration
diagram
class
diagram
state
diagram
Model ?
sequence
diagram
use case
diagram
activity
diagram
collaboration
diagram
deployment
diagram
state
diagram
Model
sequence
diagram
component
diagram
deployment
diagram
component
diagram
ISpec
Philips
Research
HJ031120-26
ISpec
© Koninklijke Philips Electronics N.V. 2003
activity
diagram
Abstract Model Diagram
The abstract model diagram is
defined by specializing the interfacerole diagram, i.e. by
• associating attributes and relations
with roles
• introducing auxiliary roles and
methods where appropriate
CONTRACT
interface-role
diagram
specializes
abstract-model
diagram
augment
semantic
constraints
It defines the vocabulary of an i-spec
Philips
Research
HJ031120-27
ISpec
© Koninklijke Philips Electronics N.V. 2003
Observer Abstract Model Diagram
IAttach
Subject
0..*
attach(obs : Observer)
detach(obs : Observer)
observers
Observer
notify()
IUpdate
update()
IState
ConcreteSubject
getState() : State
state : State
state : State
changeState(new : State)
subject
Philips
Research
HJ031120-28
ConcreteObserver
1
ISpec
© Koninklijke Philips Electronics N.V. 2003
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
Philips
Research
HJ031120-29
ISpec
© Koninklijke Philips Electronics N.V. 2003
Method Behaviour
time
t1
client
server
delegate1
method call
method body
entry
t2
out-call1
interaction point
out-call2
method body
exit
t3
t4
Philips
Research
HJ031120-30
method return
ISpec
© Koninklijke Philips Electronics N.V. 2003
delegate2
Behavioral Aspects of Methods
Behavioral aspects:
• initial state
• final state
• modification rights
• out-calls
• interaction
• threading
• activation
• timing
Philips
Research
HJ031120-31
How to specify:
 precondition
 postcondition
 action clause
 Thread class
 activation tables
 clock
ISpec
© Koninklijke Philips Electronics N.V. 2003
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
Philips
Research
HJ031120-32
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
ISpec
© Koninklijke Philips Electronics N.V. 2003
Example
Method void increment()
Precondition
• x0
Action
• modify x
• y.foo()
Postcondition
• x = x’ + 1
Philips
Research
HJ031120-33
ISpec
© Koninklijke Philips Electronics N.V. 2003
changes value of x
in unspecified way
out-call
refers to ‘old’
value of x
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”)
Philips
Research
HJ031120-34
ISpec
© Koninklijke Philips Electronics N.V. 2003
S
CONTRACT
CONTRACT
S1
CONTRACT
....
Sn
delta-spec
Composing the Observer Spec
CONTRACT
CONTRACT
IAttach
Subject
attach(obs : Observer)
detach(obs : Observer)
observers
0..*
Observer
notify()
IUpdate
update()
IState
ConcreteSubject
state : State
getState() : State
ConcreteObserver
state : State
changeState(new : State)
subject
Philips
Research
1
HJ031120-35
ISpec
© Koninklijke Philips Electronics N.V. 2003
In delta-spec of
ConcreteObserver:
• update() should
call getState() so
as to update state
Composing the AA Decoder Spec
CONTRACT
CONTRACT
AnalogAudio
Connection
Manager
AnalogAudio
Source
AnalogAudio
Decoder
IAnalogAudioSelection
IPinObjects
PinObjects
Provider
IAnalogAudioDecode
IAnalogAudioDecodeNotify
AnalogAudio
Client
IPinObjects
PinObjects
Client
AnalogAudio
ProgramSelector
1..*
Philips
Research
HJ031120-36
ISpec
© Koninklijke Philips Electronics N.V. 2003
AnalogAudio
Sink
Interface Suite Hierarchy
Platform Instance1
Interface Suite
based on
Platform Instance2
Interface Suite
Logical Component1
Interface Suite
Platform Instance3
Interface Suite
Logical Component2
Interface Suite
tmIUnknown
Interface Suite
Platform Instance4
Interface Suite
Logical Component3
Interface Suite
Pin Objects
Interface Suite
Philips
Research
HJ031120-37
Logical Component4
Interface Suite
Notification
Interface Suite
Basic Types
ISpec
© Koninklijke Philips Electronics N.V. 2003
Platform Instance5
Interface Suite
Platform
Instance
Platform
Framework
Generic /
Parameterized
Base
Document Structure
Interface Specification Document
1
1
1
0..n
the contractual
stuff
0..1
0..1
0..1
Philips
Research
HJ031120-38
Main Purpose
Base Documents
list the external interface suites used
Conceptual View
explain the concepts
Specification View
define the semantics
Technical View
map to the technology
Application Notes
provide hints for interface users
Implementation Notes
provide hints for interface providers
Glossary
provide an alphabetical list of terms
ISpec
© Koninklijke Philips Electronics N.V. 2003
Specification Templates
Operation Specification
Role Specification
1
1
0..1
0..n
0..n
0..n
0..n
0..n
0..n
Philips
Research
Role Name
1
Role Description
0..n
Role Responsibility Specification
Role Parent Specification
1
0..n
Attribute Specification
0..1
Role Invariant Specification
0..n
Operation Signature
Operation Qualifier
Operation Description
Parameter Specification
Result Specification
Effect Specification
Role Constructor Specification
Operation Specification
Role Activation Specification
HJ031120-39
ISpec
© Koninklijke Philips Electronics N.V. 2003
Effect Specification
0..1
0..1
0..1
0..1
0..1
Effect Name
Effect Description
Precondition Specification
Action Specification
Postcondition Specification
More on ISpec
General:
Hans Jonkers, ISpec: Towards Practical and
Sound Interface Specifications, IFM 2000.
Compositionality:
Hans Jonkers, Interface-Centric Architecture
Descriptions, WICSA 2001.
Philips
Research
HJ031120-40
ISpec
© Koninklijke Philips Electronics N.V. 2003