mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-12-18 14:32:23 +00:00
166 lines
9.7 KiB
HTML
166 lines
9.7 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<title>CUCC Expo Handbook: Troggle UML Class Diagrams</title>
|
||
<link rel="stylesheet" type="text/css" href="/css/main2.css" />
|
||
</head>
|
||
<body><style>body { background: #fff url(/images/style/bg-system.png) repeat-x 0 0 }</style>
|
||
<h2 id="tophead">CUCC Expo Handbook - Troggle UML Class Diagrams</h2>
|
||
<h1>Troggle UML Class Diagrams</h1>
|
||
<style>figure {font-weight: bold; font-size: small; font-family: sans-serif;font-variant-caps: small-caps;}</style>
|
||
|
||
<p>This shows the major "things" in troggle and how they relate to each other.
|
||
<p>So <strong>a survex (SVX) file</strong> is dated to a particular day during the expedition and usually has between 1 and 3 people associated with it.
|
||
<p>A <strong>Logbook entry</strong> has several people involved and may relate to a cave. It will be dated to a day during the expedition.
|
||
|
||
<p>Although the volume of data in troggle is small, the complexity is significantly intricate that "modern" (i.e. from the mid 1990s) system design tools are compact and useful.
|
||
|
||
<div class="centre">
|
||
<figure>
|
||
<a href="https://yuml.me/mkay2100/edit/Troggle-2"><img alt="Troggle UML Class Diagram" src="../i/trogclass-2.jpg" ></a>
|
||
<br><figcaption>Class Diagram - Essential Level (simplified)</figcaption>
|
||
</figure>
|
||
</div>
|
||
|
||
|
||
|
||
<h3>Design Diagrams</h3>
|
||
<p>Analysis of expo and design of troggle is done using <a href="#cookanddaniels">three levels</a>:
|
||
<style>
|
||
li {padding-left: 0;margin-left: 0;line-height:160%;}
|
||
ul, ol {padding-inline-start: 1em;}
|
||
</style>
|
||
<ol>
|
||
<li>The '<strong>essential</strong>' or 'real-world' level.
|
||
<li>The '<strong>specification</strong>' level.
|
||
<li>The '<strong>implementation</strong>' level.
|
||
</ol>
|
||
<p>As anyone reading this has probably been on expo and you might think that we can skip the <strong>real-world level</strong>. Not so: the multiplicities and cardinalities (the number of participants in the association) of the relationships between the different cave survey artefacts can be surprising. See the diagram above: a Wallet can be associated with more than one Survex file, and a Survex File can be associated with more than one Wallet.
|
||
<p>The <strong>specification level</strong> is where the action is.
|
||
This is where we decide which aspects of the real world <em>we will ignore</em> and what <em>extra concepts</em> we need to make things work.
|
||
<p>So <em>we ignore</em> who is resident at top-camp (even though today we record this religiously because of the tax implications for the GastHof at base). We <em>do</em> need to track the in-computer associations between survex files: the <var>*include</var> tree, what directories they live in, what wallet-directory they relate to, and all the individual survex blocks of survey measurements within each survex file.
|
||
|
||
<p>We only need <strong>implementation-level</strong> diagrams for tiny, tricky issues. Python is very clear so serves as its own implementation specification. However Django does need some explanation even to a competent python programmer if they have not used it before.
|
||
|
||
<p>For a fundamental background to system specification the classic work of <a href="/expofiles/documents/designing-object-systems.pdf">Cook and Daniels</a> (online PDF, 400 pages) cannot easily be improved upon (start reading at page 10, second paragraph).
|
||
|
||
|
||
<h3>Class Diagrams</h3>
|
||
<p>A Class Diagram is one the the basic types of structural diagram (as opposed to behavioral diagrams) used to understand complex systems.
|
||
<ul>
|
||
<li><a href="https://en.wikipedia.org/wiki/Class_diagram">wikipedia:Class diagram</a>
|
||
<li><a href="https://www.tutorialspoint.com/uml/uml_class_diagram.htm">UML - Class Diagram</a>
|
||
</ul>
|
||
<p>
|
||
The purpose of class diagram is to model the static view of an application: the unchanging structure.
|
||
|
||
<h3>Other UML Diagrams documenting Expo systems</h3>
|
||
<p>Class diagrams describe structure, but there are useful diagrams that describe <em>behaviour</em> too. Not much of our process is complicated enough to need them though.
|
||
<p>The <a href="life-wallet.html">wallet lifecycle</a> is a "<a href="https://en.wikipedia.org/wiki/Interaction_overview_diagram">interaction</a>" diagram showing the states and transitions between the states for a plastic wallet holding original caving notes and the software equivalent directory. The <a href="seq-wallet.html">wallet process</a> is a "<a href="https://en.wikipedia.org/wiki/Sequence_diagram">sequence</a>" diagram showing which actors (people) interact with a wallet during its lifecycle: inserting pages from the waterproof notebook, taking the notes and sketches and scanning the, processing the survey data to produce centreline plots etc.
|
||
<p>The hand-drawn sketch title "Packages" on the <a href="../troggle/trogarch.html">troggle architecture</a> page is a UML "deployment" diagram.
|
||
<p>See <a href="https://www.martinfowler.com/tags/uml.html">Fowlers pages on UML</a> for more examples of UML in use.
|
||
|
||
<h3>Online free class diagram editor</h3>
|
||
<p>The Class diagram on this page was created online using the YUML free software at <a href="https://yuml.me/mkay2100/edit/Troggle-1">https://yuml.me//</a>.
|
||
Or there is a <a href="https://marketplace.visualstudio.com/items?itemName=JaimeOlivares.yuml">yUML extension</a> to VScode which can generate the diagram within VScode.
|
||
<p>
|
||
You can edit your own version to revise this when it becomes outdated. <br>This is the entire source code that generates the diagram:
|
||
<pre><code style ="font-size:x-small">
|
||
// Troggle Class Diagram (update 2023-01-30)
|
||
// -----------------------------------------
|
||
|
||
// Chain elements like this
|
||
[SVX file{bg:lightblue}]<>-wallet 1..*>[Wallet{bg:red}]++-1..*>[Scanned Note]
|
||
[Wallet]++-1..*>[Scanned CentreLine]
|
||
|
||
[Scanned CentreLine]++-1..*>[Drawing{bg:turquoise}]
|
||
|
||
[People{bg:wheat}]<->[LogBook Entry{bg:violet}]
|
||
|
||
[People]1..3<->[SVX file]
|
||
|
||
[Cave{bg:cyan}]->[LogBook Entry]
|
||
|
||
[Cave]->[SVX file]
|
||
|
||
// note:
|
||
[Cave]-.-[Drawing{bg:turquoise}]
|
||
|
||
[Expedition{bg:green}]1<>-1..*[LogBook Entry]
|
||
|
||
[SurvexBlock{bg:lightblue}]1<>-1..*[SVX file]
|
||
|
||
[SurvexBlock{bg:lightblue}]1<>-1..*[Wallet]
|
||
|
||
[SurvexBlock{bg:lightblue}]1..*<>-1[Cave]
|
||
|
||
[SurvexBlock{bg:lightblue}]1..*<>-1[Expedition]
|
||
|
||
[SurvexBlock{bg:lightblue}]1..*<>-1[SurvexBlock]
|
||
|
||
|
||
[PersonExpedition{bg:yellowgreen}]1->1[People{bg:wheat}]
|
||
|
||
[PersonExpedition{bg:yellowgreen}]1<-1[SurvexTeamMember{bg:yellowgreen}]
|
||
|
||
[PersonLogEntry{bg:orange}]->[LogBook Entry{bg:violet}]
|
||
|
||
[PersonLogEntry{bg:orange}]->[PersonExpedition]
|
||
|
||
[SurvexTeamMember{bg:yellowgreen}]1-.-1[People{bg:wheat}]
|
||
|
||
[SurvexTeamMember{bg:yellowgreen}]1<-1[SurvexBlock]
|
||
|
||
[Expedition]1..*<-1[PersonExpedition{bg:yellowgreen}]
|
||
|
||
</code></pre>
|
||
<h3 id="cookanddaniels">Cook & Daniels - Three Levels</h3>
|
||
<p>From <a href="/expofiles/documents/designing-object-systems.pdf">Cook and Daniels</a> (online PDF, 400 pages, pp10-11):
|
||
<div style="text-align: left; font-size: smaller; margin-left: 7%; margin-right:15%">
|
||
<p>
|
||
"In this book we present three kinds of object-oriented model. The first kind, which
|
||
we call <em>the essential model</em>, considers the model to be a description of some real or
|
||
imaginary situation, which may or may not contain software. We use the word
|
||
situation rather than system because ‘system’ has so many possible meanings including
|
||
the software we may be trying to build, and rather than world to emphasise that we are
|
||
considering purposeful systems situated in a context rather than trying to describe all of
|
||
some supposedly objective reality. <em>The purpose of building the essential model is to
|
||
understand and establish the facts about this situation.</em> The building blocks which we
|
||
use to build essential models are objects (actually object types) and events (actually
|
||
event types). An essential model is built by drawing annotated diagrams, and
|
||
interpreted as descriptions of sets, functions and sequences with meanings in the
|
||
situation being described.
|
||
<p>
|
||
In the second kind of model, called <em>the specification model</em>, we are concerned with
|
||
specifying software. To create a specification model it is necessary to establish <em>which
|
||
parts of the overall situation will be implemented in software</em>. In some cases this might
|
||
be a large part of the situation, whereas in others it might not be a part at all. The
|
||
activity of specifying exactly what is to be implemented in software is quite different
|
||
from the activity of establishing the facts about the overall situation; however both of
|
||
these activities would conventionally fall under the heading of ‘analysis’. Like
|
||
essential models, specification models deal with objects and events and are built by
|
||
drawing annotated diagrams. They are interpreted as a description of the abstract
|
||
stimulus–response behaviour of the software. The specification model describes
|
||
software at a high level of abstraction, and in particular says nothing about internal
|
||
sequencing or concurrency. An important part of building a specification model is the
|
||
allocation among object types of responsibility for aspects of software behaviour.
|
||
<p>
|
||
The third kind of model, <em>the implementation model</em>, is concerned with establishing
|
||
patterns of control flow within the software. In this model we take into account the
|
||
fact that computer programs have a limited number of well-defined flows of control,
|
||
which execute at a finite speed. The building blocks for implementation models are
|
||
objects and messages. Object interactions are described as messages sent from one
|
||
object to another, and the implementation model describes message sequencing and
|
||
concurrency control. Annotated diagrams are used again, although in the
|
||
implementation model our repertoire of diagrams is richer than for the other kinds of
|
||
model."
|
||
</div>
|
||
<hr />
|
||
Go to
|
||
<a href="seq-wallet.html">Sequence diagram for a new survey wallet</a><br>
|
||
Go to
|
||
<a href="life-wallet.html">Activity diagram for a new survey wallet</a>
|
||
<hr />
|
||
</body>
|
||
</html> |