How to Document the Architecture of Your Application Using UML and More

How to Represent your Software Architecture Using UML and More

1

© 2010 Carnegie Mellon University

How to Document the Architecture of Your ApplicationUsing UML and More

SPLASH 2013 – Indianapolis

October 30, 2013

Paulo Merson

2© 2010 Carnegie Mellon University

I created this diagram14 years ago

The design may be OK

But the design description is bad and by the end of this talk I’ll have told you why!

You cando better than this!


2


Before we start the powerpoint poisoning…

How many of you work in industry with software development?

How many are familiar with basic UML?


Goals of this talk:

• Tell you what information about an architecture should be captured

• Discuss UML and other notations and guidelines for architecture representation


3


Agenda

Introduction

Multi-View Architecture

• Module Views

• Runtime Views

• Deployment Views

• Data Model

Behavior Documentation

Software Interface Documentation

Template for an Architecture Document

Outroduction


Motivation for Software Architecture (1)

The problem

???

Implementation

Requirements


4


Motivation for Software Architecture (2)

The role of software architecture

Implementation

Requirements

Architecture


What is Software Architecture?

The software architecture of a computing system is the set of structures needed to reason about the system, which comprise software elements, relations among them, and properties of both.1

1 P. Clements et al, Documenting Software Architectures: Views and Beyond, 2nd Edition. Addison-Wesley, 2010.


5


Why document the architecture?

In the software life cycle we:

• Create an architecture

o Using architectural patterns, design patterns, experience

• Evaluate the architecture

o Using ATAM for example

• Refine, update and refactor the architecture along the way

• Use the architecture to guide implementation

• (Try to) enforce the architecture during implementation andthroughout maintenance

Architecture documentation is a key artifact in all these

activities


Architecture, design, architectural design

Architecture is design,but not all design is architectural

A better separation is:

• architectural design

• non-architectural design

The architect draws the line between the two

What’s the difference between

architecture and

design?


6


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction


Views (1)

A software architecture is composed of many structures

• Code units, their decomposition and dependencies

• Processes and how they interact

• How software is deployed on hardware

• Many others

A view is the representation of a structure

Views are also known as viewpoints or

perspectives


7


Views (2)

Not all system elements, some of them

A view constrains the types of elements and the types of relations that can be represented in that view

A view is a representation of a set of system elements and relationships among them. 1



What views are available?

Kruchten’s 4+1:• Logical view

• Process view

• Development view

• Physical view

• “Plus one” view

RM-ODP:• Enterprise viewpoint

• Information viewpoint

• Computational viewpoint

• Engineering viewpoint

• Technology viewpoint

Rozansky and Woods• Functional viewpoint

• Information viewpoint

• Concurrency viewpoint

• Development viewpoint

• Deployment viewpoint

• Operational viewpoint

Philips CAFCR• Customer view

• Application view

• Functional view

• Conceptual view

• Realization view

TOGAF:• Business architecture views

• Data architecture views

• Application architecture views

• Technology architecture views

Siemens Four Views model: • Conceptual view

• Module interconnection view

• Execution view

• Code view

Garland and Anthony• Conceptual and analysis viewpoints

• Logical design viewpoints

• Environment/physical viewpoints


8


What is the “right” set of views?

It depends!

Choose what views to create (and what views do spend more time on) based on:

• The structures inherent to that software system

• The stakeholders of the documentation and what do they use it for


Exercise: list typical stakeholders of the architec ture of a software system in an IT department

Software architect

. . .


9


What kinds of views are common?

An architect usually considers 4 perspectives of the system:

1. How is it structured as a set of code units?

Module Views

2. How is it structured as a set of elements that have runtime presence?

Runtime Views

3. How are artifacts organized in the file system and how is the system deployed to hardware?

Deployment Views

4. What are the data entities and their relationships?

Data Model


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction


10


Module Views

Show structure of the system in terms of units of implementation

Elements : modules, i.e. implementation units

Relations :

• A is part of B : part-whole relation among modules

• A depends on B : dependency relation among modules

• A is a B : specialization/generalization relation among modules, or interface realization


UML relations between modules

“Is part of”

Package contains subpackages or classes

“Depends on”

Dependency can be <<use>>, <<refine>>, <<instantiate>>, etc.

“Is a”

Generalization andinterface realization

UML has other standard relations, and you can specialize

any of them with stereotypes


11


Module view example – Adventure Builder application

Showing module usage dependency

Disclaimer about examples:• no need to understand the

design• are real hence not perfect

• not the latest version• diagram can’t tell everything


Module view example – refinement of workflowmanager


12


Layered architecture of the OSGi framework

What two ambiguities exist in this diagram?


Layered view with arrows showing allowed to use relation


13


What are module views good for?

Construction—they are the blueprints for the code

Budgeting, work assignment, tracking

Modifiability and impact analysis

Education of new developers


Layers: stack of boxes and concentric rings

Are these layered designs

equivalent?


14


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction


Runtime Views

Also known as Component and Connector (C&C) views

Show structure of the system when it’s executing

Elements :

• Components that have runtime presence (e.g., processes, threads, EJBs, Servlets, ASP.NET components, service agents)

• Data stores

• Complex connectors (e.g., queues, pipes)

Relations :

• Interaction mechanisms vary based on runtime platforms

• Architect should differentiate:

o Local from remote calls

o Synchronous from asynchronous invocation

The runtime view is clearly the most

suitable for showing SOA architectures


15


Informal notation

Adapted from Adventure Builder Application http://java.sun.com/developer/releases/adventure/

Runtime View example – Adventure Builder application


Informal notation


Runtime View example – OPC refinement (1)


16


Runtime View example – OPC refinement (2)

Component (subtype of

class)

Delegation connector


Assembly connector

Required interface

Provided interface

Port

Stereotype indicate type of

component


Peer-to-Peer runtime view example


17


Architectural styles for runtime views

P. Clements et al, Documenting Software Architectures: Views and Beyond, 2nd Edition. Addison-Wesley, 2010.


What are runtime views good for?

Education—starting point to show how the system works

Explaining:

• How components interact at runtime

• What components are replicated

• What components access data stores

Analysis of runtime properties

• Performance

• Security

• Reliability


18


Runtime View – Duke’s Bank – not so good example

BankAdmin

customer_account_xref

next_tx_id

next_customer_id

next_account_id

No key!What’s the green box?

Same arrow for different interactions

Missing elements and

relations

Incorrect interaction

Inconsistent naming

Original diagram of Duke’s Bank Application from Sun J2EE 1.3 tutorial (w/ our amendment)http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/Ebank2.html


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction


19


Deployment Views

Show the hardware infrastructure of the production environment, along with deployment files and components allocated to them

Elements :

• Processing and communication nodes (e.g., server machine, router)

• Deployment artifacts

• Components

Relations :

• Interaction mechanisms between hardware elements are usually communication channels

• A deployment artifact may contain other artifacts and is deployed tohardware elements

• Components are allocated to hardware elements and deployment artifacts


Deployment View example – Adventure Builder (1)

Informal notation


20


Deployment View example – Adventure Builder (2)


Deployment View example – ATIA


21


Deployment View showing installation files


What are deployment views good for?

Planning purchasing options

Assessing:

• Availability

• Performance (e.g., throughput, bandwidth utilization)

• Security

• Reliability

Education and stakeholder communication

Defining deployment and operation procedures

Auditing runtime failures

Designing “automatic updates” feature


22


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction


Data Model

Shows structure of data manipulated in the software system

Elements : data entities (persisted domain elements)

Relations :

• 1:1, 1:n and n:n relationships

• Generalization/specialization

• AggregationData modeling is more common in

information systems


23


Data Model example – Pet Shop .NET application


What is the data model good for?

Blueprint for:

• physical database

• XML schemas

Input to normalization

Assess performance in data-centric systems

• Merged entities; derived attributes

• Indexes; lock type and granularity

Useful reference for developers of data access code

Modifiability impact analysis

database

schemas


24


Check your understanding

Mark true or false:

[ ] 1) A software architecture consists of multiple structures, which are documented as views.

[ ] 2) A module is a runtime element whereas a component is an implementation unit.

[ ] 3) An architecture document must contain at least a module view, a runtime view, a deployment view, and a data model.

[ ] 4) The diagram below shows a layered architecture.


Check your understanding (cont.)

Mark true or false:




25


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction



Diagrams we see in the views are usually structural diagrams

Structural diagrams show all potential interactions among elements

Behavioral diagrams describe specific patterns of interaction—the system’s response to stimuli

Behavioral diagrams complement structural

diagrams


26


Notations for behavior documentation

UML

• sequence diagram

• communication diagram

• activity diagram

• timing diagram

• state machine diagram

Non UML

• BPMN and alike

• SDL

• informal overlay on structural diagrams

Examples follow…


Sequence diagram – simple example


27


Sequence diagram – more interesting example

duration constraint

Interaction use (reference)

loop

alternative traces


UML sequence diagram notation bits

Frames

Self call

Reentrant call


28


Activity diagram example (1)

Activity diagram for a simple dive computer


Activity diagram example (2)

Activity diagram for processing a purchase order(Adventure Builder)


29


BPMN diagram example

BPMN diagram for processing a purchase order


State machine diagram – simple example

State machine diagram for a vehicle’s cruise control system


30


State machine diagram – more interesting example

State machine for a car stereo with AM/FM tuner and CD player


State machine diagrams – simple, powerful and yet misused and underutilized

Boxes in a state diagram are states, not components or modules;arrows are transitions, not connectors or calls

The diagram may model states of

• part of or the entire system,

• a component or module,

• a collection of components of modules, or

• even an attribute of a component/module

Be clear as to what is the scope of your state machine diagram

By definition, a state machine diagram should show

• All possible states

• All possible transitions out of any given state

Beware of the state explosion problem


31


Example of informal overlay on structural diagram


What is behavior documentation good for? (1)

Explain how does the design in a structural diagram work

• In what order do modules/components interact?

• What’s the response time for a given transaction?

• What’s the startup and shutdown procedure?

• What’s the life cycle of a given software element?

• What components execute in parallel?

• What happens when specific stimulus arrive at the system?


32


What is behavior documentation good for? (2)

Perform different kinds of (formal) analyses

• Safety and liveness properties verification

— Safety: “something bad never happens”

o Example: thrust reverser cannot be activated during takeoff

— Liveness: “something good eventually happens”

o Example: OS process eventually gets CPU time (no starvation)

• Can the system ever deadlock?

• What trace leads to deadlock?


Exercise

Create a state machine diagram for your laptop wireless connection.

Make whatever assumptions you need to make the problem simpler.

connectedconnecting connectionsare available

connected,but no Internet

access

not connected


33


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction


Software interface

An interface is a boundary across which two elements meet and interact or communicate with each other.1


Is the interface of a component or module part of the software architecture?


34


Principles about interfaces (1)

All software elements have interfaces

The interface of an element is different from its implementation

• Indeed, different elements may implement the same interface

An element may have multiple interfaces. Examples:

• To handle different groups of users,

• When 2+ versions of the same interface are available at the same time


Principles about interfaces (2)

Many callers can interact with the same interface at the same time

• Any concurrent access restrictions should be documented

Interfaces can be extended through generalization

Elements provide interfaces and may require interfaces


35


How to document a software interface

How far we document depends on the needs of the stakeholders

Often interface documentation focuses too much on syntax, and overlooks quality

attributes and rationale


Should we show interfaces in design diagrams?

Jazz for Service Management architecture

http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.psc.doc_1.1.0/oview/psc_c_arch.html


36


Interfaces in UML


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction


37


Software architecture documentation

How do we document a view?

How do we document everything else beyond the views?


The value of templates

Reader can easily navigate and find information

Writer can record information as soon as it’s known

Writer doesn’t have to think about:

• what pieces of information should be documented

• what’s the best organization for the document

Helps to evaluate documents for completeness and consistency

Document doesn’t necessarily mean paper

or Word document


38


Documenting a view (1)

1. Primary Presentation

• Is usually graphical

• Shows elements and relations among them

• Should include a key that explains the notation

— Indicate the meaning of each symbol. Don’t forget the lines!

— Try to use consistent notation across diagrams

• May identify elements that are “external”

Many times, the primary presentation is all you

get.It’s not enough!



2. Element Catalog

• Explains elements depicted in the primary presentation

• It’s usually just a list of element names and textual descriptions

• May contain interface specifications

• May contain behavior documentation


39



3. Context Diagram

• Shows what’s in and what’s out of the system (or the part of the system the view is focusing on)

• Common notation:

— System in the middle

— External entitiesaround

— Arrows indicating interactions



4. Variability Guide

• Describe variability mechanisms, such as:

— Substitution of an element with another that has the same interface

— Optional inclusion (e.g., plug-ins, add-ons)

— Component replication

— Parameterization (build-time flags, config files, etc.)

• What should be documented:

— what can vary and the effect of the variation

— binding time (compile, build, install, start, or run time)

— how to exercise each variation/configuration


40



5. Architecture Background

• Rationale for design decisions (including relevant rejected alternatives)

• Results of analysis, prototypes and experiments

• Assumptions and constraints affecting this view

• Known patterns used in the design

6. Related Views

• Pointer to parent view and children views


Outline of a documented view

This template can be used for any kind of view


41


Software Architecture Document (1)

1. Documentation Roadmap

• Shows how documentation is organized

• Has reference to template used

• Includes scenarios for different stakeholders to use the documentation

2. System Overview

• Description of the system and its purpose

• May point to overview elsewhere in the overall system documentation



3. Views

• 3.1

• 3.2

• 3.3…


42



4. Mapping Between Views

• Tables showing how elements in one view map to elements in another view

Example from Adventure BuilderOnly relevant mappings

are documented



5. Rationale

• Rationale for cross-view design decisions (including rejected alternatives)

• Results of architecture evaluation (e.g., ATAM report)

6. Mapping Requirements to Architecture

• Shows how each requirement is satisfied by one or more elements of the architecture, or an architectural approach

7. Glossary and Acronym List

• May point to a larger glossary elsewhere


43


Outline of a Software Architecture Document


Agenda

Introduction


• Module Views

• Runtime Views


• Data Model




Outroduction


44


Code is king!

Code is king!

But often architecture is a much-needed advisor to the king


Important takeaways

Describe the architecture in multiple views

Documentation should not appeal to reader’s intuition

• Always use a key or indicate the diagram notation

• Don’t forget the lines

• Use different symbols for different types of elements and relations

Define and use a template for architecture documentation

Choose notation based on the reader

• UML is not always the best notation

Indicate what patterns you’re using


45


What else is important?

Record rationale for design decisions

Select views to be documented (or documented in detail) based on:

• Stakeholders’ needs

• What structures are inherent to the system

Use view refinement

Combine views as appropriate

Document variability

Create context diagrams

Enforce the architecture


For more information

“Documenting Software Architectures: Views and Beyond, 2nd Edition”

https://wiki.sei.cmu.edu/sad/ (for an example)

sei.cmu.edu/architecture


46


Questions – Now or LaterPaulo [email protected]

Suggestions:

• I use an Agile process. Should I care about all this?

• What if I follow RUP? What about the 4+1 views?

• Can you show more real world examples?

• Can I document my architecture using a wiki?

• Is UML a formal language?

• What is the difference between contract, interface, and port?


Backup slides


47


A possible solution to the state machine exercise


Module View example – Adventure Builder application (1)

Showing only module decomposition

Disclaimer about examples:• no need to understand the

design• are real hence not perfect

• not the latest version• diagram can’t tell everything


48


High-level module view – Duke’s Bank (1)

Is this a layered design?

Showing only module decomposition


High-level module view – Duke’s Bank (2)

Showing module usage dependency

Reconstructed from Duke’s Bank Application—Sun J2EE 1.3 tutorial


49


UML for runtime viewsComponent (as subtype of class)Port (which can have multiple instances)Required and provided interface (optionally connected through ports)Assembly connectorInternal structure for classesDelegation connector


1 to 5 instances of this port (suggesting

it can take up to 5 requests at a time)

Only 1 instance of

this port

Port Required interface

Provided interface

ComponentAssembly connector



soapatterns.org notation


Runtime View Example – OPC

Refinement (3)


50


Runtime View Example – Duke’s Bank (1)

Informal notation



Runtime View Example – Duke’s Bank (2)



51


Runtime View Example – Gnutella P2P

Peer-to-peer example


Deployment View Example – Deployment Files –Duke’s Bank

Informal notation


52


Deployment View Example – Duke’s Bank


Deployment View Example – Deployment Files –Duke’s Bank

The

se a

re th

e tw

oto

p-le

vel a

rtifa

cts

<<manifest>> indicates the component is

inside the artifact

<<manifest>> may also indicate that

an artifact is inside another


53


Timing Diagram Example

Successful commit transaction in 2PC with two participants


V&B Views and 4+1 Views Imprecise Mapping

Logical view

• Module views showing generalization and usage dependencies

Process view

• Runtime views in general

Development view

• Deployment view focusing on structure of files and folders

• High-level module view showing layers

Physical view

• Deployment view focusing on the hardware infrastructure

“Plus one” view

• Rational of design decisions

• Mapping to requirements

• Behavior documentation showing important traces (using sequence and activity diagrams for example)


54


What about UML associations?


Aspects in the architecture


55


Dependency Structure Matrix (DSM)


Layered View with Concentric Rings Example


56


Data-centric Runtime View Example


Data Model UML Example – Duke’s Bank


57


Layered View in UML


UML 2.2 Diagrams

How to Document the Architecture of Your Application Using UML and More

Documents

Transcript of How to Document the Architecture of Your Application Using UML and More