ISpec: A Compositional Approach to Interface Specification Hans Jonkers HJ031120-1 ISpec

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 HJ031120-2 ISpec

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 HJ031120-3 ISpec

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 HJ031120-4 ISpec

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 HJ031120-5 ISpec

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. HJ031120-6 ISpec

Specification as a Balancing Act HJ031120-7 ISpec

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 HJ031120-8 ISpec

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

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 HJ031120-10 ISpec

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 HJ031120-11 ISpec

Observer Interface-Role Model HJ031120-12 ISpec

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. HJ031120-13 ISpec

AnalogAudioDecoder IR-Model HJ031120-14 ISpec

IR Model: UML Notations HJ031120-15 ISpec

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 HJ031120-16 ISpec

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 HJ031120-17 ISpec

Implementing = “Signing” the Contract (1) HJ031120-18 ISpec

Implementing = “Signing” the Contract (2) HJ031120-19 ISpec

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. HJ031120-20 ISpec

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

ISpec Contract Structure HJ031120-22 ISpec

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 } ..... HJ031120-23 ISpec

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 HJ031120-24 ISpec

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. HJ031120-25 ISpec

Impressionistic versus Expressionistic Modeling ISpec HJ031120-26 ISpec

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 HJ031120-27 ISpec

Observer Abstract Model Diagram HJ031120-28 ISpec

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 HJ031120-29 ISpec

Method Behaviour HJ031120-30 ISpec

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 HJ031120-31 ISpec

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 HJ031120-32 ISpec

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 HJ031120-33 ISpec

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 HJ031120-34 ISpec

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

Composing the AA Decoder Spec HJ031120-36 ISpec

Interface Suite Hierarchy HJ031120-37 ISpec

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 HJ031120-38 ISpec

Specification Templates HJ031120-39 ISpec

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