The Bugbox Project - Introduction, Requirements and UML Analysis
Diagrams and notation in the Unified Modelling Language (UML) of Booch, Jacobson and Rumbaugh are used for this worked example. The UML diagrams on this page were created with Rational Rose. For more information or downloads for Rose please visit the Rose website.
I came up with the Bugbox sample because I wanted a single small project which I could develop through various versions using different technologies. The intention is that each version meets the same requirements - with greater or lesser efficiency - but between them they will demonstrate a number of software principles. The principles I want to demonstrate are: UML analysis and design; implementation using C++; multi-threading; COM components; database transactions; Microsoft Transaction Server; and COM+.
An entomologist requires that the motion of insects inside an enclosed rectangular area be simulated. A simplified model of insect motion is to be implemented, specifically: each insect attempts continually to move forward, occasionally adjusting its bearing randomly, until it encounters an obstacle. Whilst obstructed, the insect rotates where it stands until its way forward is no longer blocked. The four walls of the enclosure are always considered obstacles, but the entomologist is at any time able to control whether the simulation does or does not consider insects themselves to be obstacles. Initially the enclosure contains no insects. The entomologist may, repeatedly and at any time, either: cause an insect to be introduced into the enclosure; kill all extant insects; or resize the boundaries of the enclosure.
The two most important nouns in the requirements are insect and enclosure, but for the sake of alliteration let's rename them to bug and box (hence the name of the project). Nouns generally represent classes and they can be obtained directly from the text of the requirements, or from use cases. Here's a diagram showing the use cases required from the system. Use cases simply illustrate the consumers of the system (known as actors) and the services which the system is meant to provide to them. Some use cases use others (note that 'observe bugs' uses 'calculate motion of a bug').
Our entomologist is an actor, and all the things which the requirements specify s/he must be able to do appear as use cases. Let's consider those nouns again - bug and box - and turn them into classes. The use cases showed some interaction between the entomologist and the system we are building, but what is the relationsip between our bug and box? And what attributes and operations do they have?
Here's a first-cut class diagram. A class diagram is intended to capture the static nature of a system - that is, the actual and potential relationships between classes of objects; what the classes are and what they do, without regard for the processes which accomplish their functionality.
A Box has one property: the current bounds of its rectangle. Its SetBounds operation supplies the means by which those bounds are resized. A Bug has properties named location and bearing, and its operations are Walk and Rotate. Each instance of the Box class aggregates a number of Bug objects by value. I have modelled a value, or composite, aggregation because the Bugs exist relative to the Box and any translation of the Box's location will be inherited by the Bugs.
Let's now look in more detail at the 'calculate motion of a bug' use case. Even though it isn't used directly by an actor, intuitively it seems like a very important piece of functionality. Here is the use case expanded into an (object) sequence diagram.
Calculate motion of a Bug.
Here we are beginning to map out the functional interaction between objects. Most of the use cases are trivial. For instance, if the 'observe bugs' use case was shown as a sequence diagram, it would show a Box periodically looping through all the Bugs belonging to it and sending them a message to calculate their motion. That motion calculation is the sequence shown above. Drawing the sequence diagram has illustrated how drawing different diagram types giving orthogonal views of the same system leads to an iterative process of analysis. Specifically, when I drew the initial class diagram I failed to predict the need for the Box::IsLocationVacant method which the sequence diagram has brought to light. Now the class diagram can be updated. The orthogonal support between diagrams of different types gives the analyst supporting evidence that the analysis is correct. You will also notice on this revised class diagram that I have made the relationship between the two classes navigable in both directions so that a Box knows its Bugs and a Bug can access the Box it lives in.
Static and functional types of diagram have been shown so far. A state transition diagram (STD) provides a dynamic view of a class. A class's properties determine its possible states. Each independent property contributes a dimension to the state-space of any object of the class. Not all classes have a sufficient number of, or interesting enough, states to merit a diagram. For instance, the states a Box can take involve simply the number of Bugs it contains and its current dimensions and those don't sound like useful states to model. When discussing the Bug class, on the other hand, the requirements used the phrase 'whilst obstructed'. This suggests a state and is the sort of expression to watch for when looking for states. The STD for the Bug class might look this this:
I think sufficient analysis has now been done for this simple system. It's worth stressing that the purpose of the logical stage is to study the abstract nature of a system: its functioning parts, the relationships between them, their processes and, provided abstraction can be maintained, their algorithms. The logical analysis of a system gives the theory of that system; that essence which all practical implementation of the system have in common. Theory has its application in practice; logical analysis/design has its application in physical implementation. Differences between implementations involve such things as programming language, data structures, operating system, and hardware, ideally none of which are concerns of the application/business domain requirements. During the logical stage of analysis, if you find yourself considering any such physical matter then you will know you have gone astray. Keeping the logical stage fimly theoretical keep open your implementation choices.
If logical means what is required, then physical means how to make it run on a computer system. You will recall that the purpose of this sample is to show several different ways in which a system can be implemented. More is said about this on the page dedicated to each choice of physical implementation. These can be reached from the Other Samples home page. But before that, here's our first taste of design with a screenshot of how the finished application will look:
A final word of warning. Some people like to mock up screenshots and present them in early drafts of the logical analysis documentation. They know that a screenshot is no more logical than a line of code, but they also know that an illustration speaks volumes. This is reasonably harmless provided that care is taken to prevent screenshots from influencing the remaining logical analysis work to agree with them. The first job of the analyst is to make sure that the requirements contain everything which is relevant and nothing more. The next job is to make sure that the logical stage considers everything in the requirements and nothing more. In almost all cases that rules out screenshots.