How To Document The Architecture of Your Application Using UML and More

How to Represent your Software Architecture Using UML and More
How to Document the Architecture of Your Application Using UML and More
SPLASH 2013 Indianapolis October 30, 2013 Paulo Merson
2010 Carnegie Mellon University
You can do better than this!
I created this diagram 14 years ago The design may be OK But the design description is bad and by the end of this talk Ill have told you why!
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
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
Requirements
???
Implementation
Motivation for Software Architecture (2)

The role of software architecture
Requirements
Architecture
Implementation
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
P. Clements et al, Documenting Software Architectures: Views and Beyond, 2nd Edition. Addison-Wesley, 2010.
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 and throughout 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:

Whats the difference between architecture and design?
architectural design non-architectural design
The architect draws the line between the two
10
Agenda

11
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
Views are also known as viewpoints or perspectives
A view is the representation of a structure
12
Views (2)
A view is a representation of a set of system elements and relationships among them. 1

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
13
What views are available?

Kruchtens 4+1:
Logical view Process view Development view Physical view Plus one view
Rozansky and Woods

Functional viewpoint Information viewpoint Concurrency viewpoint Development viewpoint Deployment viewpoint Operational viewpoint
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
RM-ODP:
Enterprise viewpoint Information viewpoint Computational viewpoint Engineering viewpoint Technology viewpoint
Philips CAFCR
Customer view Application view Functional view Conceptual view Realization view
Garland and Anthony

Conceptual and analysis viewpoints Logical design viewpoints Environment/physical viewpoints
14
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
15
Exercise: list typical stakeholders of the architecture of a software system in an IT department

Software architect ...
16
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
17
Agenda

18
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
19
UML relations between modules
Is part of
Package contains subpackages or classes
Depends on
Dependency can be <<use>>, <<refine>>, <<instantiate>>, etc.
Is a
Generalization and interface realization
UML has other standard relations, and you can specialize any of them with stereotypes
20
10
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 cant tell everything
21
Module view example refinement of workflowmanager
22
11
Layered architecture of the OSGi framework

What two ambiguities exist in this diagram?
23
Layered view with arrows showing allowed to use relation
24
12
What are module views good for?
Constructionthey are the blueprints for the code Budgeting, work assignment, tracking Modifiability and impact analysis Education of new developers
25
Layers: stack of boxes and concentric rings
Are these layered designs equivalent?
26
13
Agenda

27
Runtime Views
Also known as Component and Connector (C&C) views Show structure of the system when its executing Elements:

The runtime view is clearly the most suitable for showing SOA architectures
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 o
Local from remote calls Synchronous from asynchronous invocation
28
14
Runtime View example Adventure Builder application
Informal notation
Adapted from Adventure Builder Application http://java.sun.com/developer/releases/adventure/

29
Runtime View example OPC refinement (1)

Informal notation
Adapted from Adventure Builder Application http://java.sun.com/develop er/releases/adventure/
30
15
Runtime View example OPC refinement (2)

Provided interface Delegation connector Stereotype indicate type of component Component (subtype of class)
Required interface
Delegation connector
Port
Assembly connector
31
Peer-to-Peer runtime view example
32
16
Architectural styles for runtime views
33
What are runtime views good for?

Educationstarting 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
34
17
Runtime View Dukes Bank not so good example

Whats the green box? No key!
next_account_id
Missing elements and relations
customer_account_xref
Same arrow for different interactions Bank Admin

next_customer_id
Inconsistent naming
next_tx_id
Incorrect interaction
Original diagram of Dukes Bank Application from Sun J2EE 1.3 tutorial (w/ our amendment) http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/Ebank2.html
35
Agenda

36
18
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 to hardware elements Components are allocated to hardware elements and deployment artifacts
37
Deployment View example Adventure Builder (1)
Informal notation
38
19
Deployment View example Adventure Builder (2)
39
Deployment View example ATIA
40
20
Deployment View showing installation files
41
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
42
21
Agenda

43
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 Aggregation

Data modeling is more common in information systems
44
22
Data Model example Pet Shop .NET application
45
What is the data model good for?

Blueprint for:

database
physical database XML schemas

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
46
23
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.
47
Check your understanding (cont.)

Mark true or false:
[ ] 5) The diagram below shows a layered architecture.
[ ] 6) The diagram below shows a layered architecture.
48
24
Agenda

49
Behavior Documentation
Diagrams we see in the views are usually structural diagrams Structural diagrams show all potential interactions among elements Behavioral diagrams describe specific patterns of interactionthe systems response to stimuli
Behavioral diagrams complement structural diagrams
50
25
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
51
Sequence diagram simple example
52
26
Sequence diagram more interesting example
duration constraint
Interaction use (reference)
loop
alternative traces
53
UML sequence diagram notation bits

Self call
Frames
Reentrant call
54
27
Activity diagram example (1)

Activity diagram for a simple dive computer
55
Activity diagram example (2)
Activity diagram for processing a purchase order

(Adventure Builder)
56
28
BPMN diagram example
BPMN diagram for processing a purchase order
57
State machine diagram simple example
State machine diagram for a vehicles cruise control system
58
29
State machine diagram more interesting example
State machine for a car stereo with AM/FM tuner and CD player
59
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
Beware of the state explosion problem
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
60
30
Example of informal overlay on structural diagram
61
What is behavior documentation good for? (1)

Explain how does the design in a structural diagram work

In what order do modules/components interact? Whats the response time for a given transaction? Whats the startup and shutdown procedure? Whats the life cycle of a given software element? What components execute in parallel? What happens when specific stimulus arrive at the system?
62
31
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?
63
Exercise
Create a state machine diagram for your laptop wireless connection.
connecting
connections are available
connected
connected, but no Internet access
not connected
Make whatever assumptions you need to make the problem simpler.
64
32
Agenda

65
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?
66
33
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
67
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
68
34
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
69
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
70
35
Interfaces in UML
71
Agenda

72
36
Software architecture documentation

How do we document a view?
How do we document everything else beyond the views?
73
The value of templates

Reader can easily navigate and find information Writer can record information as soon as its known Writer doesnt have to think about:

what pieces of information should be documented whats the best organization for the document
Helps to evaluate documents for completeness and consistency
Document doesnt necessarily mean paper or Word document
74
37
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. Dont 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. Its not enough!
75

2. Element Catalog

Explains elements depicted in the primary presentation Its usually just a list of element names and textual descriptions May contain interface specifications May contain behavior documentation
76
38

3. Context Diagram

Shows whats in and whats out of the system (or the part of the system the view is focusing on) Common notation:
System in the middle External entities around Arrows indicating interactions
77

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
78
39

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
79
Outline of a documented view
This template can be used for any kind of view
80
40
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
81

3. Views
3.1
3.2
3.3
82
41

4. Mapping Between Views
Tables showing how elements in one view map to elements in another view
Only relevant mappings are documented
Example from Adventure Builder
83

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
84
42
Outline of a Software Architecture Document
85
Agenda

86
43
Code is king!
Code is king!
But often architecture is a much-needed advisor to the king
87
Important takeaways
Describe the architecture in multiple views Documentation should not appeal to readers intuition

Always use a key or indicate the diagram notation Dont 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 youre using
88
44
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
89
For more information

Documenting Software Architectures: Views and Beyond, 2nd Edition
https://wiki.sei.cmu.edu/sad/ (for an example)
sei.cmu.edu/architecture
90
45
Questions Now or Later

Paulo Merson pmerson@acm.org
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?
91
Backup slides
92
46
A possible solution to the state machine exercise
93
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 cant tell everything
94
47
High-level module view Dukes Bank (1)
Showing only module decomposition
Is this a layered design?
95
High-level module view Dukes Bank (2)
Showing module usage dependency
Reconstructed from Dukes Bank ApplicationSun J2EE 1.3 tutorial
96
48
UML for runtime views

Component (as subtype of class) Port (which can have multiple instances) Required and provided interface (optionally connected through ports) Assembly connector Internal structure for classes Component Delegation connector Assembly
1 to 5 instances of this port (suggesting it can take up to 5 requests at a time) Delegation connector connector Delegation connector
Provided interface
Port
Required interface
Only 1 instance of this port
97
Runtime View Example OPC Refinement (3)
soapatterns.org notation
Adapted from Adventure Builder Application http://java.sun.com/developer/releases/adventure/

98
49
Runtime View Example Dukes Bank (1)
Informal notation
99
Runtime View Example Dukes Bank (2)

100
50
Runtime View Example Gnutella P2P
Peer-to-peer example
101
Deployment View Example Deployment Files Dukes Bank
Informal notation
102
51
Deployment View Example Dukes Bank
103
Deployment View Example Deployment Files Dukes Bank

<<manifest>> indicates the component is inside the artifact
These are the two top-level artifacts
<<manifest>> may also indicate that an artifact is inside another
104
52
Timing Diagram Example
Successful commit transaction in 2PC with two participants
105
V&B Views and 4+1 Views Imprecise Mapping

Logical view
Module views showing generalization and usage dependencies Runtime views in general Deployment view focusing on structure of files and folders High-level module view showing layers Deployment view focusing on the hardware infrastructure Rational of design decisions Mapping to requirements Behavior documentation showing important traces (using sequence and activity diagrams for example)
Process view
Development view

Physical view
Plus one view

106
53
What about UML associations?
107
Aspects in the architecture
108
54
Dependency Structure Matrix (DSM)
109
Layered View with Concentric Rings Example
110
55
Data-centric Runtime View Example
111
Data Model UML Example Dukes Bank
112
56
Layered View in UML
113
UML 2.2 Diagrams
114
57

How To Document The Architecture of Your Application Using UML and More

Uploaded by

Document Information

Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Description:

Copyright:

Available Formats

How To Document The Architecture of Your Application Using UML and More

Original Title:

Uploaded by

Description:

Copyright:

Available Formats

How to Represent your Software Architecture Using UML and More

SPLASH 2013 Indianapolis October 30, 2013 Paulo Merson

2010 Carnegie Mellon University

You can do better than this!

How to Represent your Software Architecture Using UML and More

Before we start the powerpoint poisoning

2010 Carnegie Mellon University

Goals of this talk:

2010 Carnegie Mellon University

How to Represent your Software Architecture Using UML and More

Module Views Runtime Views Deployment Views Data Model

2010 Carnegie Mellon University

Motivation for Software Architecture (1)

2010 Carnegie Mellon University

How to Represent your Software Architecture Using UML and More

Motivation for Software Architecture (2)

2010 Carnegie Mellon University

What is Software Architecture?

2010 Carnegie Mellon University

How to Represent your Software Architecture Using UML and More

Why document the architecture?

Using architectural patterns, design patterns, experience

Evaluate the architecture

Using ATAM for example

2010 Carnegie Mellon University

Architecture, design, architectural design

Architecture is design, but not all design is architectural

A better separation is:

Whats the difference between architecture and design?

architectural design non-architectural design

The architect draws the line between the two

2010 Carnegie Mellon University

How to Represent your Software Architecture Using UML and More

Module Views Runtime Views Deployment Views Data Model

2010 Carnegie Mellon University

A software architecture is composed of many structures

A view is the representation of a structure

2010 Carnegie Mellon University

How to Represent your Software Architecture Using UML and More

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

2010 Carnegie Mellon University

What views are available?

Rozansky and Woods

Siemens Four Views model:

Garland and Anthony

2010 Carnegie Mellon University

How to Represent your Software Architecture Using UML and More

What is the right set of views?

2010 Carnegie Mellon University

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

2010 Carnegie Mellon University

How to Represent your Software Architecture Using UML and More

What kinds of views are common?

hardware? Deployment Views

2010 Carnegie Mellon University

Module Views Runtime Views Deployment Views Data Model

2010 Carnegie Mellon University

How to Represent your Software Architecture Using UML and More

2010 Carnegie Mellon University