Preliminary Design

Component Specification

Gerson Sunyé

https://sunye-g.univ-nantes.io

Gerson Sunyé gerson.sunye@univ-nantes.fr

Introduction

  • Preliminary Design is the first step of software design.

  • During this phase, a high-level design concept that meets the requirement specification is created.

  • The concept is expressed as a set of components (or subsystems) with clear interfaces.

What’s an Interface?

  • An interface is a set of Operations that are provided (implemented) by a component.

  • It may represent different things:

    • An Interface in Java, Go, Swift, Python, etc.

    • A REST API

    • A GraphQL API

    • A (Web)Socket protocol

Diagram

Preliminary Design Goals

  • Establish the system boundaries

    • Define what the system will and will not do

  • Define system and component interfaces.

  • Define component scope and responsibilities.

  • Specify desired component operations (its functionalities).

Define component scope and responsibilities

A Risk Game represented as two components
Figure 1. A Risk Game represented as two components
Who is responsible for:

  • validating movements?

  • keeping information about the game board?

  • rolling dices?

Typical Deliverables

  • Component Diagram, representing the system divided in subsystems/components

  • Precise specification of interfaces:

    • Operations, their signatures, and their pre and post conditions.

  • Interaction diagrams:

  • State Machine diagrams.

Components

  • A component is a coherent package of software that can be independently developed and delivered as a unit.

  • Main goal: improve cohesion and reduce coupling

dictionary component
Figure 2. UML Component

Provided and Required Interfaces

A component has an explicit and well-specified interfaces of the: 

  • Provided services:

    • the functionalities it implements

  • Services expected from other components:

    • the functionalities it uses

  • Components use these interfaces and only these interfaces to communicate with each other.


component interfaces
Figure 3. UML Component: Provided and Required Interfaces

Composition

  • Components can be combined with other components to provide and use services.

  • Components are substitutable: one component can replace another at design time or at runtime, if the successor component meets the requirements of the initial one.

Component based Software Engineering example2
Figure 4. A simple example of UML components (by Cmendes at English Wikipedia)

Ports assemble Interfaces

  • A port represents an interaction point between a component and its environment. 

  • The nature of the interactions is specified by interfaces. 

component ports

Benefits of Components

Component based architectures promote: 

  • Reusability and reliability.

  • Maintainability, modularity,  testability, flexibility, extensibility. 

  • Portability. 

Design Process

Design Process Steps

  1. Adopt the domain model as the initial class model. 

  2. Define the boundaries: 

    1. consider the system as a single component 

    2. specify the system behavior that would meet the requirements. 

  3. Decompose components recursively:

    1. approaches: structural and behavioral 

  4. Add technical components (database, user interface, middleware, etc.). 

  5. Use interactions to validate component interfaces. 

  6. Use state machines to specify classes. 

Adopt the domain model as the initial class model.

Risk Domain Model
Figure 5. Risk Domain Model

Adopt the domain model as the initial class model.

  • 1-1 correspondence often not possible *

  • A model that gives the best most adapted solution is often different from one that clearly explains what the object does.

Domain Model Partition

  • The domain model is the most important part of the system

  • It contains the domain entities and rules

Diagram

Add Technical components

  • Typical components: Presentation, Persistence, Network, etc.

Diagram

Decompose Components Recursively

Diagram

  • Component GUI implements a Web UI using the Angular framework and communicates using WebSockets.

  • Weaknesses: hard to test, technology dependent.

Decomposing the GUI Component (v1)

  • Applying the Humble Object Pattern[1]

Diagram
1. The Humber Dialog Box, Michael Feathers

Decomposing the GUI Component (v2)

  • Applying the Single Responsibility principle[1]

Diagram
1. Single Responsibility Principle, Robert C. Martin

Decomposing the Domain Component

  • Applying the Single Responsibility principle (again)

Diagram

Component Interface Specification

Diagram

  • Weaknesses: only one interface for different usages

Diagram

Component Interface Specification

  • Applying the Interface Segregation Principle[1]

Diagram
1. Interface Segregation Principle, Robert C. Martin

Component Interface Specification

Diagram

Interface Specification

Diagram
Diagram

Source code organization

Diagram

Parameter Type Specification (1/3)

Parameters using internal classes
Figure 6. Parameters using internal classes

Consequences: content coupling () between the clients and the Risk Server component.

Consequences on the source code

Diagram

Parameter Type Specification (2/3)

Parameters using primitive types
Figure 7. Parameters using primitive types

Consequences: data coupling (), but worse performance

Consequences on the source code

Diagram

Parameter Type Specification (3/3)

Parameters using Datatypes
Figure 8. Parameters using Datatypes

Consequences: trade-off between couping and performance. Stamp coupling ().

Consequences on the source code

Diagram

Operation Specification (1/4)

  • One attribute → One operation

Diagram

Affected quality factors: performance, maintainability, evolutivity, testability.

Interactions

Diagram

Operation Specification (2/4)

  • One class → One operation

Diagram

Affected quality factors: performance, maintainability, evolutivity, testability.

Interactions

Diagram

Operation Specification (3/4)

  • One class → One operation

Diagram

Affected quality factors: performance, maintainability, evolutivity, testability.

Interactions

Diagram

Operation Specification (4/4)

  • Several classes → One operation

Diagram

Interactions

Diagram

Parameter Types

Diagram
The operations promote errors related to parameter inversion
Diagram
The use of basic types allows value validation before calling the operation. However, the clients must know basic types.

Precise Specification of Operations

modifyPlayer(id:String, name:String, phone: String)

pre: name.size() > 0 and (...)

pre: name.notEmpty() and (...)

pre: self.players->exists(id = id) and (...)

Execution Mode

Signals
Figure 9. Signals
Synchronous Operations
Figure 10. Synchronous Operations

Interface Validation

Using Interaction Diagrams

User Creation (v1)

Diagram

User Creation (v2)

Diagram

Game Creation

Conclusion

Component partitioning requires several iterations:

  • It’s hard to find the adequate partitioning at first time.

  • Design experience is required.

  • Interfaces should be designed to be stable.

Additional  Readings

Design patterns: