UQ Students should read the Disclaimer & Warning
Note: This page dates from 2005, and is kept for historical purposes.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>COMP2801 - Assignment 2 - Software Documentation</title>
<style>
<!--
.wider li {
padding: 1ex;
}
tr {
text-align: left;
}
table li {
padding: 0;
margin: 0;
}
table ul {
list-style: none;
}
table p {
margin: 0;
}
.centre {
text-align: center;
}
.figure {
font-weight: bold;
text-align: center;
margin-top: 0px;
}
-->
</style>
</head>
<body>
<h1>COMP2801 – Assignment Two – Software Documentation</h1>
<p>I achieved eighteen out of a possible twenty marks. </p>
<p> </p>
<hr />
<p> </p>
<p class="centre"><img src="COMP2801-assignment-2-files/image001.png" alt="Umlet logo" width="155" height="114" /></p>
<h1 class="centre">Software Documentation Project</h1>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p class="centre"><strong>Project Team</strong></p>
<p class="centre">Stephen Gordon<br />
Stephen Jenks<br />
Ned Martin<br />
Lachlan Smith</p>
<p class="centre">Tuesday 8am Group A</p>
<hr />
<h2>Table of Contents</h2>
<div class="centre">
<table style="margin:auto" cellspacing="0" cellpadding="0">
<tr>
<td> <ul>
<li><strong>1.0 Introduction</strong></li>
<li><strong>2.0 Structure Overview</strong>
<ul>
<li><strong>2.1 </strong>Package layout</li>
<li><strong>2.2 </strong>Class listing</li>
<li><strong>2.3 </strong>External libraries</li>
</ul>
</li>
<li><strong>3.0 Class Documentation</strong>
<ul>
<li><strong>3.1 </strong>com.umlet.control Package</li>
<li><strong>3.2 </strong>com.umlet.control.io Package</li>
</ul>
</li>
<li><strong>4.0 Build Evidence</strong></li>
<li><strong>5.0 Team Learning Journal</strong>
<ul>
<li><strong>5.1 </strong>Stephen Gordon</li>
<li><strong>5.2 </strong>Stephen Jenks</li>
<li><strong>5.3 </strong>Ned Martin</li>
<li><strong>5.4 </strong>Lachlan Smith</li>
</ul>
</li>
<li><strong>6.0 Extended Project Planning</strong></li>
<li><strong>6.1 </strong>Further Documentation</li>
<li><strong>6.2 </strong>Program Improvement</li>
<li><strong>6.3 </strong>Testing Guidelines</li>
<li><strong>7.0 References</strong></li>
<li><strong>8.0 Appendix A – UML Diagram</strong></li>
<li><strong>9.0 Appendix B – build.xml </strong></li>
</ul></td>
<td> <ul>
<li><strong>2</strong></li>
<li><strong>3</strong></li>
<li>3</li>
<li>3</li>
<li>5</li>
<li><strong>7</strong></li>
<li>15</li>
<li>15</li>
<li><strong>21</strong></li>
<li><strong>24</strong></li>
<li>24</li>
<li>25</li>
<li>26</li>
<li>30</li>
<li><strong>34</strong></li>
<li>34</li>
<li>34</li>
<li>35</li>
<li><strong>38</strong></li>
<li><strong>40</strong></li>
<li><strong>41</strong></li>
</ul></td>
</tr>
</table>
</div>
<hr />
<h2>1.0 Introduction</h2>
<p>This document is a compilation intended to provide an overview of the basic
design of the main control elements of the UMLet program and some of the implications
of its design. Also provided herein is an explanation of the build process for
UMLet which produces the final program from source. A plan for future documentation
and design pertaining to UMLet as well as journals detailing the documentation
and learning process have been included to provide readers with an insight into
both the creation of this piece and future works that may be undertaken.</p>
<p>UMLet is an open source program that can be used to create UML diagrams; it
uses a graphical user interface which while at first confusing is quite easy
to use once learnt. There is no existing user documentation for the tool, but
experimentation and perseverance allow the determined user to make efficient
use of it.</p>
<p class="centre"><img src="COMP2801-assignment-2-files/image002.png" alt="Umlet" /><br />
Figure 1.1</p>
<p>As shown in figure 1.1 the program once started displays a series of panels,
each with its own individual purpose. The three panels provide a drawing space,
a palette of common UML objects and a space for editing component properties
and text.</p>
<p>The program UMLet has no technical or even user level documentation, and the
source code itself is very sparsely documented. For this reason this report
is not built upon pre-existing specifications or designs commentaries, rather
from knowledge gained through the investigative process.</p>
<hr />
<h2>2.0 Structure
Overview</h2>
<h3>2.1 Package layout</h3>
<p>The source code is divided up into several packages each with an individual
task or group of tasks. The packages in UMLet are divided into three (3) main
streams, those being control, element and plug in. For the purposes of this
project the Plugin package was not examined at all as it is not required to
demonstrate the standalone program. Also note that while the Element package
will at times be mentioned herein it is not documented in this report as classes
within it simply define new objects for the UMLet drawing panel.</p>
<h3>2.2 Class listing</h3>
<p>A full list of all classes in the UMLet source code package can be found below,
classified by package, and including those classes that are not further documented
in this report.</p>
<ul>
<li>com.umlet.control
<ul>
<li>AddEntity</li>
<li>ChangeState</li>
<li>Clip</li>
<li>Command</li>
<li>Connector</li>
<li>ConnectorHandler</li>
<li>Constants</li>
<li>Controller</li>
<li>CreateInterface</li>
<li>InsertLinePoint</li>
<li>Macro</li>
<li>Move</li>
<li>MoveLinePoint</li>
<li>RemoveElement</li>
<li>RemoveLinePoint</li>
<li>Resize</li>
<li>Role</li>
<li>Selector</li>
<li>SelectorFrame</li>
<li>Umlet</li>
<li>UniversalListener</li>
<li>XMLContentHandler</li>
</ul>
</li>
<li>com.umlet.control.io
<ul>
<li>FileOp</li>
<li>GenEps</li>
<li>GenPdf</li>
<li>GenSvg</li>
<li>IntHashtable</li>
<li>UmletPluginHandler</li>
</ul>
</li>
<li>com.umlet.element.base
<ul>
<li>Actor</li>
<li>Class</li>
<li>Entity</li>
<li>Interface</li>
<li>Note</li>
<li>Package</li>
<li>Relation</li>
<li>UseCase</li>
</ul>
</li>
<li>com.umlet.element.custom
<ul>
<li> TemplateClass</li>
</ul>
</li>
<li> com.umlet.plugin
<ul>
<li> UmletPlugin</li>
</ul>
</li>
<li> com.umlet.plugin.editors
<ul>
<li> UmletEditor</li>
</ul>
</li>
<li> com.umlet.plugin.wizards
<ul>
<li> NewWizard</li>
</ul>
</li>
</ul>
<h3>2.3 External libraries</h3>
<p>UMLet makes use of a reasonably large set of libraries produced by third party
developers which are not included in the standard Java package from Sun. These
libraries and a very brief description of their function are listed below:</p>
<ul class="wider">
<li>Avalon<br />
<br />
Homepage: <a
href="http://avalon.apache.org/">http://avalon.apache.org/</a><br />
<br />
The Avalon project from the Apache Software Foundation (ASF) is “a component-orientated
programming project” (<a href="http://jakarta.apache.org/#avalon">http://jakarta.apache.org/#avalon</a>)
and provides a platform for development which concentrates on best design practices
in software development.<br />
</li>
<li>Batik <br />
<br />
Homepage: <a
href="http://xml.apache.org/batik/">http://xml.apache.org/batik/</a><br />
<br />
The Batik library from the ASF provides UMLet with the functionality
required to generate files in the Scalable Vector Graphics (SVG) format.<br />
</li>
<li>Crimson <br />
<br />
Homepage: <a
href="http://xml.apache.org/crimson/">http://xml.apache.org/crimson/</a><br />
<br />
Also from the ASF, Crimson is an XML parser which provides access to
data stored in XML files in a way that is independent of the actual parsing
engine itself.<br />
</li>
<li>EpsGraphics <br />
<br />
Homepage: <a
href="http://www.jibble.org/javadocs/epsgraphics/org/jibble/epsgraphics/EpsGraphics2D.html">http://www.jibble.org/javadocs/epsgraphics/org/jibble/epsgraphics/EpsGraphics2D.html</a><br />
<br />
The EPS Graphics library provides UMLet with the ability to save to the
Encapsulated PostScript format.<br />
</li>
<li>FOP <br />
<br />
Homepage: <a
href="http://xml.apache.org/#fop">http://xml.apache.org/#fop</a><br />
<br />
This is another library from the ASF and provides a way to convert data
from both XML and DOM structured formats to Adobe’s Portable Document Format
(PDF).<br />
</li>
<li>Xalan <br />
<br />
Homepage: <a
href="http://xml.apache.org/xalan-j/">http://xml.apache.org/xalan-j/</a><br />
<br />
The Xalan library from the ASF is able to transform XML documents into
HyperText Markup Language (HTML), text or XML formats. The xml-apis and xercesImpl
libraries, while included in separate archives, are used to facilitate much
of the functionality of the Xalan library and as such are included in this
entry.<br />
</li>
<li>JDOM <br />
<br />
Homepage: <a
href="http://www.jdom.org/">http://www.jdom.org/</a><br />
<br />
The JDOM library and what it can provide to UMLet is probably best described
by the mission goal stated on the project webpage:<br />
“To build a complete, Java-based solution for accessing, manipulating,
and outputting XML data from Java code.”
</li>
</ul>
<hr />
<h2>3.0 Class
Documentation</h2>
<h3>3.1 com.umlet.control Package</h3>
<p>This package provides the vast majority of UMLet’s actual functionality including
most, if not all, of the Graphical User Interface (GUI) classes and methods.
Each class in the package is documented herein with an appropriate description
and UML diagrams as appropriate.</p>
<h3>3.1.1 AddEntity</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The <em>AddEntity</em> class, which also extends the Command class, simply
adds or removes an Entity (created by the <em>CreateInterface</em> class above),
via its execute or undo methods respectively, to or from an instance of UMLet.</p>
<h3>3.1.2 ChangeState</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The <em>ChangeState</em> class – another class that extends the <em>Command</em> class,
changes the state of an <em>Entity</em> or <em>Command</em> within an UMLet
panel. <em>ChangeState</em>’s <em>execute</em> and <em>undo</em> methods set
the state of an <em>Entity</em> to a new or old state, respectively, and provide
getter methods to return this <em>Entity</em> and its new and old states.</p>
<h3>3.1.3 Clip</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image004.png" alt="UML diagram" width="497" height="402" /><br />Figure 2</p>
<p>The Singleton <em>Clip</em> class provides self-explanatory methods for copying
and pasting data from a system clipboard, which we won’t go into further.</p>
<h3>3.1.4 Command & Controller</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image006.png" alt="UML diagram" width="285" height="305" /><br />
Figure 3</p>
<p><em>NB: See Appendix B for broader UML diagram.</em></p>
<p>The <em>Controller </em>class, another Singleton class, executes <em>Command</em>s,
via the abstract <em>Command</em> class. Two methods are provided for executing <em>Command</em>s,
one of which allows for undo (and subsequent redo) operations, and one that
doesn’t. When using the former, the <em>Command</em>s are stored in a Vector
as they are executed, which the <em>undo</em> and <em>redo </em>methods iterate
through, executing or undoing the <em>Command</em>s as required – while the
latter simply executes its <em>Command</em> without storing it. These two methods
are called whenever a large variety of actions are to be performed in UMLet.</p>
<p>The abstract <em>Command</em> class defines the methods <em>execute </em>and <em>undo</em>,
which are called by the C<em>ontroller </em>class, along with a <em>mergeTo</em> method
(and its corresponding <em>isMergeableTo</em> method), which we will get to
in a moment.</p>
<h3>3.1.5 Connector</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image008.png" alt="UML diagram" width="473" height="321" /><br />Figure 4</p>
<p>The class <em>Connector</em>, as its name suggests, handles the connectors
between UML entities. An instance of this class is created by <em>ConnectorHandler</em> and
represents a connector between two entities, storing references to the two entities
it connects. It contains two methods, which respectively return the entities
at either end of the connector.</p>
<h3>3.1.6 ConnectorHandler</h3>
<p>The class <em>ConnectorHandler</em>, which is a Singleton class, contains
methods that add, remove, and manipulate connectors between entities. Most of
the methods are self-explanatory, accepting two entities and removing, adding,
or returning the connector between the two. One slightly more complex method, <em>getConnectorsByConnectedToEntity</em>,
returns a Vector containing all connectors connected to a given entity.</p>
<h3>3.1.7 Constants</h3>
<p class="centre"><img src="COMP2801-assignment-2-files/image010.png" alt="UML diagram" width="542" height="552" /><br />Figure 5 </p>
<p>The <em>Constants</em> class handles most of the drawing and writing methods
used to actually render the various <em>Entity’</em>s and <em>Connector</em>s
in the UMLet panel.</p>
<h3>3.1.8 CreateInterface</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The <em>CreateInterface</em> class extends <em>Command</em> and, not surprisingly,
creates an UMLet <em>Interface</em>. Its constructor creates this new <em>Interface</em>,
which inturn creates its super-type <em>Entity</em>, defined using various constants
from the <em>Constants</em> class, depending on the type of <em>Interface</em> being
created.</p>
<p><em>CreateInterface</em> then overrides the <em>execute</em> and <em>undo</em> methods
in its parent <em>Command</em> class, adding and removing an interface from
an UMLet instance, or panel, as required.</p>
<h3>3.1.9 InsertLinePoint.java & RemoveLinePoint.java</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The two classes <em>InsertLinePoint</em> and <em>RemoveLinePoint</em> are
almost identical. These two classes are concerned with the insertion and removal
of points into a Relation object, defined in the package <em>com.umlet.element.base</em>,
which contains a list of points, and this relation of points, make up a line.
Each point is made up of an x coordinate and a y coordinate and is defined in
the class Point of the <em>java.awt</em> package, the point objects are represented
in these classes by integer variables _x, and _y respectively, the points are
contained in a vector which is defined in the Vector class of the <em>java.util</em> package,
and accessed by the int variable _where that represents the index in the vector
of a particular line point. The difference between the two classes being that
they are used for opposing functions, both of the classes extend the abstract
class Command, and in particular both override the execute and undo methods
of their parent class. The <em>InsertLinePoint</em>’s execute method inserts
a line point into the Relation’s vector of line points and the undo method removes
the line point, whereas <em>RemoveLinePoint</em>’s execute method removes a
point from a given relation and undo reinserts the point.</p>
<h3>3.1.10 Macro</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The Macro class is a specialization of the Command class and overrides the <em>execute</em>, <em>undo</em>, <em>isMergableTo</em> and
the <em>mergeTo </em>methods. A <em>Macro</em> object has only one variable
and that is a Vector object defined in the <em>java.util</em> package, and the
vector contains Command objects. When the execute method is called a loop runs
through and calls each command separately, the undo method does the same but
in reverse. The <em>isMergableTo</em> method takes as an argument of a Command
object and compares it to the current object, if both are the same size and
both contain the same type of commands then the method returns true. The <em>mergeTo</em> method
unites the current object with the Macro object included as the arguments of
the <em>mergeTo</em> method by placing in a new <em>Macro</em> object all of
the combined <em>Command </em>objects one by one.</p>
<h3>3.1.11 Move</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The Move class is almost identical to the <em>MoveLinePoint</em> class in
functionality, it inherits from the Command class and overrides the methods
execute, undo, <em>isMergableTo</em> and <em>mergeTo</em>. The main difference
is that instead of moving a line point an object of the Entity class from the <em>com.umlet.element.base</em> is
moved. When a <em>Move</em> objects execute method is called an int value _x
and _y are passed to the current <em>Entity</em> object as parameters to the <em>Entity</em> object’s <em>changeLocation</em> method. <em>Move</em>’s
undo method is the same as its’ <em>execute</em> method except that the values
passed are the negations of _<em>x</em> and _<em>y</em>. The <em>isMergableTo</em> is
used to determine if a command is an instance of a <em>Move</em> object and
that it references the same <em>Entity</em> object. The <em>mergeTo</em> method
takes a <em>Move</em> object as an argument and adds the current <em>Move</em> object’s
x and y values to the argument’s x and y values and combines these and returns
them as one move on the current <em>Move</em> object’s <em>Entity</em> object.</p>
<h3>3.1.12 MoveLinePoint</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The class <em>MoveLinePoint</em> is a subclass of the Command class and overrides
the methods execute, undo,<em> isMergableTo</em> and <em>mergeTo</em>. The
method execute gets a point which is defined in the class <em>Point</em> from
the <em>java.awt</em> package, from a relation object containing line points
which is defined in the <em>com.umlet.element.base</em> package, and adds to
the x and y values of the point object _<em>diffx</em> and _<em>diffy</em>,
the values of _<em>diffx</em> and _<em>diffy</em> which are both integer values
and are how far the line point is to move from its original position. The method
undo does the same thing as execute but instead of adding _<em>diffx</em> and
_<em>diffy</em> it subtracts these values from a point’s x and y coordinates.
The <em>isMergableTo</em> method returns if a command is a <em>MoveLinePoint</em> instance
and if it is it returns true. The <em>mergeTo</em> method adds one instance
of a <em>MoveLinePoint</em> command to another <em>MoveLinePoint </em>command,
it does this by adding the current objects _<em>diffx</em> and _<em>diffy</em> values
with the merging <em>MoveLinePoints</em> _<em>diffx</em> and _<em>diffy</em> values,
once the values are added together a single <em>Command</em> object is returned.</p>
<h3>3.1.13 RemoveElement</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The <em>RemoveElement</em> class extends the <em>Command</em> class and overrides
the <em>execute</em> and <em>undo</em> methods. When a <em>RemoveElement</em> object
is created it is passed as a parameter an object of the Vector class, the Vector
class is defined in the <em>java.util</em> package. The vector contains a set
of <em>Entity</em> objects defined in <em>com.umlet.element.base</em> package,
when the execute method is called all <em>Entity</em> objects in the Vector
_entities are removed from the UMLet panel and a call is then made to the <em>Selector</em> class
to deselect all the <em>Entity</em> objects that were selected to be removed.
The undo method places the <em>Entity</em> objects back into the UMLet panel
and updates the panel with its repaint method.</p>
<h3>3.1.14 Resize</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The <em>Resize</em> class extends the <em>Command</em> class, and it overrides
the <em>execute</em>, <em>undo</em>, <em>isMergableTo</em> and <em>mergeTo</em> methods.
The method execute takes an integer that is represented by the value _<em>where</em>,
depending on this value different corners or sides of the current <em>Entity</em> object
are moved by changing the <em>Entity</em>’s size and/or location, this causes
resizing of the object. The undo method does the opposite of the execute method.
The <em>isMergableTo</em> method returns true if its given parameter is a <em>Resize</em> object.
The <em>mergeTo</em> method takes as its argument a <em>Resize</em> object and
adds its _<em>diffx</em> and _<em>diffy</em> values to the current objects _<em>diffx</em> and
_<em>diffy</em> values, this is then returned as one <em>Resize</em> object.</p>
<h3>3.1.15 Role</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image012.png" alt="UML diagram" width="277" height="317" /><br />Figure 6</p>
<p>The <em>Role</em> class extends the <em>Rectangle</em> class defined in the <em>java.awt</em> package,
a <em>Role</em> object is initialized with dimensions for creating a <em>Rectangle </em>object
and the String <em>a</em>.</p>
<h3>3.1.16 Selector</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image018.png" alt="UML diagram" width="485" height="421" /><br />Figure 7</p>
<p>The <em>Selector </em>class facilitates the use of a tool which is common
to many image manipulation programs and allows the selection of objects on the
drawing canvas. The provided methods allow the selection of single or multiple
entities and even the automatic selection of all entities on the panel. Also
provided are methods for de-selection of entities and the selection of all relationships
on the panel (as opposed to the all entities selection method which includes
everything). Interestingly a lot of this functionality is not actually utilized
by the UMLet interface or program at this time. The final thing to note is that
like many of the classes in the package, <em>Selector</em> is called/created
by an instance.</p>
<h3>3.1.17 SelectorFrame</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image016.png" alt="UML diagram" width="296" height="356" /><br />Figure 8</p>
<p>The <em>SelectorFrame</em> is an extremely basic class which extends the <em>JComponent</em> class
found in the standard Java libraries. Its’ only method is paint which accepts
a <em>Graphics</em> object as it’s only argument and draws a black box around
the selection area.</p>
<h3>3.1.18 Universal Listener</h3>
<p>Whenever the user makes some form of input into the UMLet program, the <em>UniversalListener </em>class
interprets the input and executes the appropriate action. The defining aspect
of <em>UniversalListener</em> is that it implements a number of listener interfaces;
as such, it is positioned to know about key events, mouse events, and window-related
events.</p>
<p>For instance, when a double-click occurs, the <em>mousePressed </em>method
will determine whether the double-click occurred upon an <em>Entity</em>, and
if so, it will do what UMLet does when the user double-clicks upon an <em>Entity</em> -
create a duplicate of it.</p>
<p>This event-driven system also includes menu selections, such that when the
user selects the "Undo" menu, the method <em>actionPerformed </em>is
invoked; this method determines from its parameter that the chosen menu option
was "Undo", and thus undertakes the process for undoing a user’s previous
action.</p>
<p>This class is clearly envisioned to be a “clearing house” for input, where
any kind of user interaction relevant to UMLet can be handled appropriately.
All methods are implemented, albeit sometimes without adding any code, and it
is easy to understand what each of the methods are for, and roughly what that
method is doing, without the benefit of comments. There are a relatively large
number of intra-package class dependencies, which is not surprising, considering
the range of duties this class is asked to perform.</p>
<h3>3.1.19 Umlet</h3>
<p><em>NB: See Appendix B for UML diagram.</em></p>
<p>The <em>Umlet</em> class is the main class for the UMLet application. It
contains the <em>main</em> method, which initializes the application and creates
a new document to which the user may begin to add UML.</p>
<p>The defining aspect of <em>Umlet</em> is that it is a singleton, meaning only
one instance of it may be created; once created, that instance can be readily
obtained from other classes. What this means is that, after the initialization
process, <em>Umlet</em> can sit back and wait for instructions from other classes
that are not necessarily subclasses of <em>Umlet</em>. Those classes obtain
the instance by calling <em>getInstance</em>, and then chain methods onto the
end of that: for example, <em>Umlet.getInstance().doSave()</em> can be called
from any class, and it will cause <em>Umlet </em>to save the current document.</p>
<p><em>Umle</em>t is in charge of a lot of methods that need to be accessible
from elsewhere in the application, generally methods at the application scope:
in particular, file and windowing–related methods. Smaller-scoped methods have
been consigned to other singleton classes like <em>Controller</em> and <em>Selector</em>,
whose scope is more specific. Looking through the code, it is clear that there
was a methodology used to decide ‘which method goes in what singleton class’,
but this is not always clear, and a total lack of useful comments in the code
makes comprehension somewhat of a challenge.</p>
<hr />
<h2>3.2 com.umlet.control.io Package</h2>
<p>The <em>com.umlet.control.io</em> package provides UMLet with the ability
to save to the file system of the machine on which it is running along with
some other functionality. Classes in this package allow saving to any of several
different file types including Portable Document Format (PDF) and Scalable Vector
Graphics (SVG). The package also provides a special data structure for use in
other parts of the UMLet software and a common interface for plug-in developers
to work from. Most of the code in the package is concise and well written but
there is little or no commenting to be found. Documentation for all classes
and interfaces in the package is provided below to alleviate this situation.</p>
<h3>3.2.1 FileOp</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image018.png" alt="UML diagram" width="485" height="421" /><br />Figure 9</p>
<p>When a user selects any of the save options available in the UMLet menu structure
the program uses an instance of the <em>FileOp</em> class to generate the appropriate
dialog box. The <em>FileOp</em> class makes use of the Java <em>filechooser</em> dialog
box as provided by the <em>javax.swing.filechooser</em> package. The instance
of <em>FileOp</em> then simply returns the filename selected by the user to
the calling class or null, it is then up to the calling class to call the actual
save routine to write data to disk. </p>
<p>As can be seen from the above diagram the class provides methods for the selection
and generation of filenames for use when saving JPG, SVG, PDF and EPS documents.
The other <em>save</em> and <em>open</em> filename methods are related to UMLet’s
own file format. Finally the <em>setSaveMenuItem()</em> method is used to toggle
the state of the ‘Save’ item in the UMLet menus to indicate to the user whether
the option is presently available or not.</p>
<p>The tasks accomplished by the <em>FileOp</em> class are all relatively simple
and as such the code is reasonably clear and concise. Unfortunately, like most
of the UMLet source package, there is little if any code commenting or documentation
to be found and that which does exist is relatively cryptic.</p>
<h3>3.2.2 IntHashTable, IntHashTableEntry, IntHashTableEnumerator</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image020.png" alt="UML diagram" width="570" height="360" /><br />Figure 10</p>
<p>This set of classes is used to provide UMLet with the use of an advanced data
structure called a hash table. To summarize the diagram above an <em>IntHashTable</em> stores
any number of <em>IntHashTableEntrys</em>, each of these entries stores an integer
and a Boolean flag. The software’s main visible use of this data structure is
to store rendering flags. </p>
<p>When a programmer is using one of these structures to store data they can
use an <em>IntHashTableEnumerator</em> to move through the entries in the table
in much the same way they would normally use an iterator to move through a linked
list or other data structure. It is however worth noting that this construct
only allows movement in one direction and therefore is slightly harder to reverse
than a doubly linked list, though it still retains most functionality. </p>
<p>The <em>IntHashTable</em> class itself provides functions to perform all of
the operations that are normally expected of an advanced data structure. This
includes methods for adding, removing, cloning and checking for entries as well
as methods to perform operations on the overall set such as checking the size
and whether or not certain keys exist. Using this set of classes makes storing
of integer hashes quite simple.</p>
<p>Unlike most of the code found in the UMLet packages the hash tables classes
are well commented and include appropriate information for the JavaDoc utility
to build documentation from. If it was necessary to extend or modify the classes
this would prove extremely helpful. As it stands however the hash table classes
appear to be fully functional, even though UMLet does not actually use most
of this functionality, and as such are unlikely to require modification for
further use in UMLet or any other Java program.</p>
<h3>3.2.3 GenEps, GenPdf, GenSvg</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image022.png" alt="UML diagram" width="483" height="417" /><br />Figure 11</p>
<p class="centre"><img src="COMP2801-assignment-2-files/image024.png" alt="UML diagram" width="552" height="374" /><br />
Figure 12
</p>
<p class="centre"><img src="COMP2801-assignment-2-files/image026.png" alt="UML diagram" width="554" height="320" /><br />
Figure 13</p>
<p>When a user chooses to save to any format apart from UMLet’s own XUF files
an instance of one of these classes is created. UMLet then calls the appropriate <em>createAndOutput*ToFile()</em> member
function which is expected to handle all tasks associated with building the
data displayed on the screen into the correct format and saving it to the file
system. If any errors are generated by these classes they are simply sent to
standard output rather than the standard error stream or a dialog box or other
piece of GUI functionality.</p>
<p>Interestingly, although the three classes share a number of common member
functions, the functionality is not grouped together under a common interface
or other object orientated programming construct. For the most part these classes
are relatively short with the exception of <em>GenPdf</em> which is required
to take more steps to generate data for storing in its associated file format.
All of these classes provide some source code documentation in the form of appropriate
commenting but in many cases it is still somewhat sketchy.</p>
<h3>3.2.4 UmletPluginHandler</h3>
<p class="centre"><img
src="COMP2801-assignment-2-files/image028.png" alt="UML diagram" width="252" height="164" /><br />Figure 14</p>
<p>The UMLet plug-in functionality is beyond the scope of this document as the
intention here is to examine UMLet as a standalone program, not as a plug-in
for the eclipse IDE. Despite this it is worth noting that an interface for a
plug-in handler is included in the <em>com.umlet.control.io</em> package and
that this allows the creation of custom plug-in handlers in a common way so
that the main UMLet program can access them without modification. This allows
plug in developers to build small re-distributable plug-in packages rather than
being forced to release a modified build of the entire UMLet package.</p>
<hr />
<h3>4.0 Build
Evidence</h3>
<p>The UMLet source code is included in the same archive as the compiled byte
code; a build file however is not included and as such has been created from
scratch. The following text is intended to provide a brief documentation of
the build file and its’ invocation. Further information is available by reading
the commented <em>build.xml</em> file which is provided as an appendix to this
document.</p>
<p>The provided build file for use with the ant build utility provides the following
targets:</p>
<ul class="wider">
<li><em>init<br />
<br />
</em>Creates the required directory structure in the <em>${build} </em>directory
(defaults to ’<em>./build</em>’, although generally the compilation process
would do this anyway in some situations it might be useful to only create the
structure without doing a full compile. Note that when this build target is
called a ’<em>clean</em>’ will automatically be performed.</li>
<li><em>clean<br />
<br />
</em>Removes all files in the <em>${build}</em> directory, this is done to
purge old class files and also to ensure that no attempt is made to include
an existing archive from an old build into that of a fresh build.</li>
<li><em>compile<br />
<br />
</em>When invoked with this target ant will to a complete build process which
will include first running the <em>clean</em> and <em>init</em> targets, compilation
of all java source files and the creation of an archive from which the complete
program may be run. Once the archive has been created the class and manifest
files are then deleted from the <em>${build}</em> tree. The process also copies
across all required external libraries that aren’t included with the Java Software
Development Kit.</li>
</ul>
<p>The output produced by running a compile should be similar to the following:</p>
<pre>s4054252@lichen:~/cvstest/new/Umlet3$ ant
Buildfile: build.xml
clean:
init:
[mkdir] Created dir: /students/11/s4054252/cvstest/new/Umlet3/build
[mkdir] Created dir: /students/11/s4054252/cvstest/new/Umlet3/build/com
[mkdir] Created dir: /students/11/s4054252/cvstest/new/Umlet3/build/com/umlet/control
[mkdir] Created dir: /students/11/s4054252/cvstest/new/Umlet3/build/com/umlet/elemet
compile:
[javac] Compiling 30 source files to /students/11/s4054252/cvstest/new/Umlet3/build
[javac] Compiling 16 source files to /students/11/s4054252/cvstest/new/Umlet3/build
[copy] Copying 1 file to /students/11/s4054252/cvstest/new/Umlet3/build/META-INF
[copy] Copying 1 file to /students/11/s4054252/cvstest/new/Umlet3/build
[jar] Building jar: /students/11/s4054252/cvstest/new/Umlet3/build/Umlet3.jar
[copy] Copying 9 files to /students/11/s4054252/cvstest/new/Umlet3/build/lib
[copy] Copying 3 files to /students/11/s4054252/cvstest/new/Umlet3/build
[delete] Deleting directory /students/11/s4054252/cvstest/new/Umlet3/build/com
[delete] Deleting directory /students/11/s4054252/cvstest/new/Umlet3/build/META-INF
BUILD SUCCESSFUL
Total time: 20 seconds
s4054252@lichen:~/cvstest/new/Umlet3$</pre>
<p>The directory structure in <em>${build} </em>after ant completes a full compile
should be similar to that shown in the following listing:</p>
<pre>-rwx------ 1 s4054252 students 21 Aug 20 22:49 Umlet.sh
-rw------- 1 s4054252 students 70848 Aug 20 22:49 Umlet3.jar
drwx------ 2 s4054252 students 96 Aug 20 22:49 icons
drwx------ 2 s4054252 students 8192 Aug 20 22:49 lib
-rw------- 1 s4054252 students 6447 Aug 20 22:49 palette.uxf
-rw------- 1 s4054252 students 1685 Aug 20 22:49 plugin.xml</pre>
<p>All of the listed build targets can created by simply changing to the directory
the <em>build.xml</em> file is in and running ant with the following syntax:</p>
<pre>ant [target]</pre>
<p>When no target is supplied the build script defaults to a full compilation
of UMLet. Once UMLet is compiled all that is required to execute the program
is to change to the <em>${build}</em> directory and run the included shell script:</p>
<pre>./Umlet.sh</pre>
<hr />
<h2>5.0 Team
Learning Journal</h2>
<h3>5.1 Stephen Gordon</h3>
<!--
<p>Software design theory is integral to the accomplishment of any significant
task in programming or software development. While without good design practices
it is possible to write working code projects written in this way tend to get
hard to manage quickly and the initial quick speed of development slows to a
crawl. This results from both the added difficulty of finding specific sections
of code as a poorly designed project grows and the continuous code re-writing
and re-structuring process which is forced as features need to be added to the
code base. Unfortunately what exactly defines ’good’ programming practice is
open to constant debate and revision, creating a somewhat moving target. Object-orientated
languages, specifically those like C# and Java, tend to promote many of the
key ideas that are often promoted as central to good programming design. For
the most part this is a result of the aforementioned languages essentially forcing
tasks such as allowing for code re-use and separating major program functionality.</p>
<p>As the code for the project documented in this report was written in the object-orientated
Java language it was quite a simple task to divide the documentation task between
group members by assigning different class or object files to each group member.
When it was necessary classes were documented in small groups to display clearly
the intertwining nature of the code, in all other cases classes were documented
individually. In all cases documentation consisted of a reasonably concise description
of the class and its’ purpose along with a UML diagram displaying appropriate
additional information. For consistency reasons all UML diagrams were later
completed using Visio.</p>
<p>During the project resources consulted included the UMLet homepage, Apache
Software Foundation (ASF) sites as well as the source code itself. The UMLet
homepage proved next to useless as little or no documentation is provided aside
from a mediocre Frequently Asked Questions (FAQ) file relating mostly to installation
procedures. Various ASF sites were consulted on multiple occasions to obtain
information relating to the various libraries UMLet relies on which are made
by the foundation. Luckily these sites generally proved to be extremely useful
with full and thorough documentation of all aspects of the various projects.
The level of detail found in the documentation on the ASF sites was in many
cases, well above that required for the purposes of this project. Obtaining
information from the source code was unfortunately not as easily facilitated
as for the most part there was little or no source code documentation of tangible
value to be found in the UMLet project. This however simply forced team members
to delve deeper in their search for a full understanding of the code and as
such this process, while time consuming, was more than likely worthwhile. </p>
<p>During the process of the project there were several mistakes made by the
team which while not large enough to prevent the task from being completed were
certainly less than helpful. An example of this is the way in which the groups’
software package was chosen, there is little doubt that if any team member had
investigated thoroughly and discovered the lack of a build file and source code
commenting it would have been extremely unlikely that UMLet would have been
chosen. It has also been noted that deadlines could and should have been used
more effectively in the process of this project. While at times deadlines were
set it is fair to say that no group member ever accomplished the given tasks
in the set time frame. Upon completion of this document and commencement of
the program enhancement stage it is more than likely that some group discussion
and reflection will occur in relation to this issue. Hopefully this will result
in a more rigid and forward thinking plan covering the entirety of the next
project.</p>
<p>At this stage of the course some additional knowledge has been acquired to
add to that held previously although not as much as might have been liked. A
large part of this additional knowledge gained was related to streamlining of
the build process using ANT and was obtained during the generation of a build
script for UMLet. Some useful knowledge has been obtained in the use of UML
diagrams to illustrate program semantics however once again this has not really
been picked up as well as might have been hoped.</p>
<p>Despite some hiccups the team appears to have accomplished it’s goals for
this assignment, the classes we set out to document have indeed been documented
and plans have been made for future projects based on this documentation. Overall
the only goal not accomplished was that of having a full draft written with
plenty of time to spare, unfortunately this however may in many ways simply
be a side effect of working in a group which cannot meet as often as might be
liked due to members’ conflicting weekly schedules.</p>
<p>While this course is providing good grounding for the kind of software design
and understanding required to extend existing programs it is possible that better
insights into the actual software design process might come from actually designing
and creating software. This however is of course a much larger undertaking and
as such could well be beyond the scope of a second year subject. All in all
however this project has been a definite learning experience although whether
it has been more beneficial to software development or project management knowledge
is still undecided.</p>
-->
<p>[Removed for privacy]</p>
<h3>5.2 Stephen Jenks</h3>
<!--
<p>The following information is a summary from the scraps of ideas within documents
and my head that I have written or thought about software design over the past
3 weeks. Initially I have been creating my programs with the ad-hoc approach,
but have found that over the course of this semester I am beginning to write
my programs differently, I am recognizing the value of understanding patterns
and I don’t think I could produce code without thinking about the design I will
incorporate into the program. I am not up to the stage of writing UML modeled
diagrams on paper following the factory method and then implementing this into
a large program, but I am trying to use a design while I am programming.</p>
<p>The theory of software design has helped me in the understanding of large
programs because it has allowed me to understand ways in which to divide the
program into smaller pieces that are more easily understood. These pieces when
assembled follow general patterns that are widely known and therefore make a
large program fit into a familiar structure, for someone who knows software
design methods. When the creation of a large software system is developed,
it usually goes though a process of requirements analysis, design, implementation
and then maintenance. By understanding the theory of design I am more easily
able to see from a model of a program how its different pieces interact.</p>
<p>There have been two basic strategies that I have used for the purpose of understanding
the code of our groups program. The first has been simple inspection, I have
grabbed a class and read it. While reading the class any objects that the class
is associated with, that do not belong to the standard java libraries, I search
for in the rest of the programs class list and try to understand what they do.
The second strategy I used was to reverse engineer the java files using Rational
Rose, from the diagram I obtained I was able to see associations between the
classes, once again not concerning myself with standard java libraries. Also
Rational Rose’s ability to allow you to look at code through its interface while
looking at how the classes combine was a much more efficient way of understanding
the documentation, compare this with opening the files up with an editor and
swapping between class files and trying to remember their connections to each
other.</p>
<p>Apart from using Rational Rose and various other Java Integrated Development
Environments (IDEs), used for the purpose of perusing the code, no other resource
was really used during this few weeks. The Internet was not used at all for
the purpose of gaining understanding of our groups program due to after initial
searches when looking for information to help with the first assignment it was
discovered there was very little helpful information. Also for this part of
the course the CVS has been used little by me. This is mainly because the code
has not been altered and therefore the java files that were taken out of the
CVS three weeks ago are no different to any java files in the CVS now, no new
versions have been created, also I haven’t used the CVS as a repository for
my journal upkeep or any other files associated with the writing of this assignment.
The only other resource used was Microsoft Visio, this was used to help me with
the drawing of UML elements.</p>
<p>During the course of this project the team hasn’t made any fundamental mistakes
in there understanding or execution of the task due to their understanding of
the course work, as far as I can tell. Our group has maintained enough contact
to discuss any difficulties that any particular person may have had, but at
each of these meetings little has needed to be discussed, as no one has really
had any difficulties, most of this type of contact has be brief. Perhaps this
in itself could be considered a mistake as possibly more time spent as a group
may have had the assignment completed sooner, but unless the assignment is not
submitted before the due date then this isn’t really a mistake.</p>
<p>Before this semester I did not know hat rational Rose existed, but I was aware
of UML and had had some small experience in using that particular modeling language
although I did not know it to the same degree as taught in this course. I would
like to say that I now understand everything that has been offered in the course
since the start of the semester, but this unfortunately is not true. I feel
it is good to reflect upon what you have learnt as this probably helps a bit
at exam time, one area I definitely know more about is the design mo0dels used
in software projects.</p>
<p>Our teams goals have been to document UMLet with the thought of providing
ourselves with an understanding how the program works to be able to find an
area were the program can be improved of extended, I feel we have achieved this.
Apart from the assignment specs to be completed, I think that the assignment
is attempting to give us experience at looking at real world code and to show
us some useful techniques employed by developers who are possibly outside of
a learning institution (perhaps not), also by seeing real world code we may
see some bad habits and poor excepted practice. Over the course of this assignment
there have been observed both good and poor techniques.</p>
<p>So far I have learnt the basics of creating code, usually written in java
but sometimes in other languages, they so far all seem to follow at least similar
semantics if not syntax. Object orientation has been an extension to this,
and software design has always gone with this hand in hand. This course has
yet again furthered my understanding of software design by giving the commonly
used design patterns and further understanding of UML to allow a simple way
for representing the design of a program. As for furthering my understanding
of design, perhaps being able to determine user needs and requirements and creating
a design from this analysis to discover give the user what they want, possibly
before they even know they want it.</p>
-->
<p>[Removed for privacy]</p>
<h3>5.3 Ned Martin</h3>
<p>Apparently, I’m supposed to have been keeping a “team learning journal”, but
I haven’t been so I’m currently in the same situation as the proverbial. To
rectify this situation, I have decided to paraphrase various parts of another
journal I have been keeping, interspersed with my own (occasionally accurate)
recollections, and attempt to formulate from this something that vaguely matches
the description of what a team journal should be.</p>
<p>First, a little about myself – I am Ned. Hear me roar. That done, I guess
I may as well begin at the beginning, way back in July – Thursday, 15th July,
to be precise.</p>
<p><em>Thursday 15 July – Sign On</em></p>
<p>I woke up at a horribly early hour, to sign on for my COMP2801. I’ve gone
from having an all but perfect timetable, to a pretty average timetable, to
a rather bad timetable with two eight o’clock starts and a five o’clock finish
on Friday – due to tutoring. Hopefully it’s worth it, and everything works out
ok. </p>
<p><em>Monday 26 July – First Lecture</em></p>
<p>The next COMP2801 thing of any import was the first lecture, which I attended
quite too bright and early one Monday morning. I believe I’ve dutifully attended
all lectures since, and found them instrumental in helping me understand UML,
along with the tutorials. This has been particularly handy, as I don’t have
any UML textbooks.</p>
<p><em>Tuesday 27 July – Practical 1</em></p>
<p>I woke up when my alarm went off, at six o’clock, and again eight minutes
later. Eight o’clock starts aren’t my favorite things. Nevertheless, I managed
to get to uni on time, and it wasn’t even that cold. I found the right room
for my practical, and formed a group with the three people sitting nearest me
– all of whom I happened to know, vaguely. I had been a little worried that
I’d end up being automatically assigned a group of dumb people – less intellectually
endowed people, I should say, or people who wouldn’t do any work, couldn’t speak
English, were intolerable, had multiple open wounds, etc. I just wasn’t quite
sure what people would go to an 8 AM practical, because, by my logic, no sane
person would intentionally sign up for something that early. Fortunately, though,
I think the group I’ve managed to get are reasonably intelligent, willing and
able to try, well versed in basic English and other associated communication
skills, including, but not limited to, the ability to write and talk in an understandable
manner, and so on, and so forth. In other words, I’m hopeful that I’m in a good
group.</p>
<p> We then proceeded to “bond”, by attempting to survive a plane crash
in snowy, sub-zero northern Canada, in a wooded area crisscrossed with creeks
and roughly 20 miles from the nearest town. Luckily, we had some vital survival
equipment, such as a lighter with no fluid, a ball of steel wool, and two dead
pilots. We had to individually rank these (and several other) items in order
of importance to our survival, and then do the same again but as a group. We
then compared our results to that of an “expert”, who, I suspect, would accidentally
kill himself (and several innocent bystanders) while trying to survive a trip
to the local supermarket. Nevertheless, we bonded, and, apart from one member
who took the whisky and headed towards town and certain death, and another member
who didn’t place enough importance on the lighter and froze to death, and myself
and another member who left the steel wool behind and not only froze to death
but were also unable to signal for help due to the unreflective properties of
Crisco shortening, we all survived. </p>
<p><em>Tuesday 3 August – Practical 2</em></p>
<p>Today, at the ungodly time of 8 AM, I learnt how to use ANT – which beats
learning how to use make files. I also learnt that I should follow instructions
exactly as given – as I had several problems and had to ask for help a few times,
and each time it was because I’d failed to read the instructions properly, or
had missed a step. So, I guess you could say today has been a productive day.</p>
<p><em>Tuesday 10 August – Practical 3</em></p>
<p>I had to tutor for another subject, and attend my eight o’clock group practical,
so didn’t want to be late. I had also stayed up most of the night, as usual,
so had to use my patent-pending psychological trick to wake up – setting the
computer’s alarm to play something loud five minutes after my alarm, so when
mine goes off, I have to get up to turn the computer’s one off before it goes
off and wakes everyone else, who will then kill me. It was very cold – one of
the coldest mornings so far, but I managed to attend my prac, and probably learnt
something there, although I can’t remember what it was.</p>
<p><em>Tuesday 17 August – Practical 4</em></p>
<p>We had a group meeting during our prac, which went quite well. We managed
to delegate tasks to ourselves in a way that seems to make everyone happy, without
really meaning to, while telling lots of doubtful jokes and stuff. It seems
Flash (Steve Gordon) is Mr. CVS, Stephen (Jenks) is Mr. PowerPoint Designer,
and Lachlan (Smith) and I are your presenters – with Lachlan being more comfortable
talking, and me being less comfortable talking, so I’m Mr. Click Things and
he’s the inimitable Dr Voice. It’s all going good. </p>
<p><em>Friday 20 August – Group Meeting</em></p>
<p>We had a group meeting today. I almost forgot about it, and because my tutoring
ran overtime, I was late. The meeting went for all of three minutes, during
which time we unanimously decided to have another group meeting at a later date,
due to lack of motivation and a dire lack of a lack of assignments in other
subjects. </p>
<p>I am so busy right now - it’s not good. I have an assignment due before 2
PM Monday, this one due during my two-hour eight o’clock practical on Tuesday
and another due on Friday. I also have a fourth assignment that I should be
doing, but I haven’t even looked at it so don’t know when it’s due. Then, on
top of that, there’s a few things relating to my tutoring that I have to do,
several little things around here I need to do, paperwork and computer stuff,
and I need to go shopping and do some washing.</p>
<p><em>Tuesday 24 August – Practical 5</em></p>
<p>I headed down to the labs, via the refectory where I bought a terrible pretending
pizza thing that was so bad I had to throw it out. After three quarters of our
group finished not preparing in the labs, we went up to the other lab and, after
the fourth quarter arrived we presented our program – “UMLet”, a Java based
UML drawing program, which I insist is pronounced as “omelet”. It was a ten-minute
presentation, during which Lachlan spoke and I cleverly manipulated our PowerPoint
slides and the actual program. This was followed by rapturous applause (or so
I insist on remembering), and then Stephen (the Gordon one) took a break from
losing sleep over Slashdot to demonstrate his immeasurable CVS skills – and
that was that. The rest of the groups ran through their presentations ranging
from one who had a simple script and read it out without any computer involvement
to one who had a fully scripted presentation with all four participating. We
were the only group who ran to time (or at least the only group who had a two-minute
warning given), and successfully covered all points on the criteria sheet with
a live demonstration of the program, so I’m hoping for marks. We might even
get an excellence and innovation mark for Stephen’s installation and run script.</p>
<p><em>Tuesday 31 August – Practical 6</em></p>
<p>Today’s practical was supposed to teach us how to use Rational Rose, but after
a quick perusal of that program, I’ve decided that “use” is not the appropriate
word – performing even the most basic tasks requires immense effort, although
perhaps it wouldn’t be so bad if I actually understood what I was trying to
do – something I must aim for. I did, however, learn how to create complex-looking
(and sometimes meaningful) UML diagrams from Java without expending too much
effort – something that’s very useful considering that’s part of what I have
to do for the next assignment. My only other exposure to UML had been through
Visio, while attempting to draw ER diagrams for an INFS assignment, I came across
some UML templates and had a bit of a play around, but I didn’t realize the
full depth and breadth, and the rich variety of diagrammatical styles possible.
Now I do. The tutorials on UML have been instrumental in aiding my understanding
as well, as I’ve found some aspects of UML, particularly the way it’s only semi-formal
and a lot of discretion is required to determine precisely how to model something,
quite confusing. </p>
<p><em>Tuesday 7 September – Practical 7</em></p>
<p>I pretended the world was round and that today was just another day, and headed
into university. I attended my prac, during which we planned how we are going
to try to do our assignment, and after that, I repressed all thoughts of assignments
for as long as possible. </p>
<p><em>Tuesday 14 September – Practical 8</em></p>
<p>Our original plan had us all completing our individual parts of assignment
two by today, and beginning the group parts. What actually happened, though,
was that I went to Sydney over the weekend and didn’t complete my part on time,
and we realized that some aspects of the individual work we’d assigned ourselves
is better done in a group environment. Basically, we each found that we had
to read half of the java files assigned to other group members in order to be
able to figure out what the code in our files did – so we’ve modified our schedule
a little. It is now more realistic and goes something like “finish everything
as fast as possible – definitely before the due date”.</p>
<p><em>Wednesday 15 September</em></p>
<p>So here am I, sitting down in the lab typing all this. Now that I’ve given
what is, I hope, an accurate overview of my experiences with COMP2801 so far,
I would like to reflect on what I’ve actually learnt so far, and how I’ve gone
about it.</p>
<p>UML – I had a vague idea about it, mostly garnered from using Visio to draw
diagrams during a previous INFS course. I’ve now learnt quite a lot about UML,
and can actually use Rational Rose – in a way.</p>
<p>Teamwork – This is the third teamwork-based assessment I’ve done here at UQ,
but the first where I’ve really learnt how to cooperate and trust others. I’ve
had to, as I haven’t had enough time to check work others are doing to see if
it matches my “standards”.</p>
<p>Java – I don’t really think I’ve learnt anything I didn’t already know about
Java and programming itself, everything has been straightforward code so far
and I believe I’m becoming adept at spotting situations that could benefit from
re-factoring. I have, however, had to struggle to understand and identify design
patterns, as I don’t find their discovery intuitive.</p>
<p>CVS – This course is the first time I’ve used CVS. I’d heard about it a lot
from various open-source places, but never actually had to use it myself. I
can’t say I’m overly impressed, it doesn’t seem to be much more than a glorified
versioning archive to me – but it’s handy to know how to use it should I ever
need to.</p>
<p>ANT – Having only used make files before, ANT came as a nice surprise. It’s
quite powerful, relatively easy to learn, and uses XML for that up-to-the-minute
effect. I didn’t have much input into the ANT build file used by our team, but
the ANT practical helped.</p>
<h3>5.4 Lachlan Smith</h3>
<!-- <p><em>Tuesday 10am:</em></p>
<p>The weekly prac. This is the first time we discussed the assignment as a
group.</p>
<p>Ned has summarized the information from the assignment spec, and has set out
a draft table of contents. As this assignment is a team effort, the need to
have a "top down" style of development is important; having an abstract
view of how the final document will be structured, allows us to efficiently
divide tasks evenly among the four team members.</p>
<p>Stephen G has identified the various UMLet classes. Each group member will
take a roughly even number of the classes and document it in the manner required
by the assignment spec.</p>
<p>We will collaborate via the email, and the plan is to have all of the classes
specified by next Tuesday’s prac, so that we can then concentrate on consolidating
all of our endeavors into one document and making sure it is presented neatly,
as well as finishing off the lower priority tasks such as the plan.</p>
<p>Each team member will keep an individual journal, and these will be consolidated
into one team journal once the rest of the assignment is complete.</p>
<p>I have come to realize that there are many different ways to illustrate a
Java class in UML. Whether or not to specify things like return types, parameter
types, visibility. I asked Doug whether there was a particular UML ’style guide’
I could adhere to; his advice was, rather than to stick to a particular style
guide (there is apparently no real authoritative style guide for UML - it is
envisioned as being a very flexible language), simply to choose one that meets
our needs, and be consistent.</p>
<p><em>Wednesday 10:45am:</em></p>
<p>Came into GPS room 109 to actually start using Rational Rose. I went through
the Rose prac to reacquaint myself with how to reverse engineer Java classes.</p>
<p>I had made the decision in yesterday’s prac to do the reverse engineering
in Rose, but to do the actual diagrams in Visio. I have an idea of the style
I would like the finished UML diagrams to be in, and I’m not a fan of the Rose
UML style. I pointed out to the team members that Rose cannot save to any other
format than Rose, and the diagrams would have to be pasted into the assignment
document in raster format, rather than the more aesthetically pleasing vector
format.</p>
<p>Therefore, the approach I have taken is to reverse engineer in Rose, and then
to take Visio’s diagram and redraw it manually in Visio.</p>
<p>When reverse engineering in Rose, one other important ’style’ aspect came
to my attention - whether or not to draw the ’dependency’ (ie. dotted line)
arrow to classes referred to by the class that are not within UMLet, but part
of the standard Java distribution. For example, the Selector class refers to
several classes in the <em>java.awt</em>, <em>java.util</em> and <em>javax.swing</em> packages.</p>
<p>I have chosen to put these dependencies in, and draw a border around classes
belonging to the same package, whilst foreign classes and packages go outside
this border.</p>
<p>I realise that the other team members may have a different approach, for example,
they might not draw the dependencies as I have, or they might do aggregation,
operation descriptors, etc, slightly differently, keeping in mind that there
is no real standard way to do things. It is important for us to be consistent,
or we risk losing marks for poor presentation or quality, etc.</p>
<p>So, rather than to risk this, to take everyone’s work and draw it up in Visio,
making sure every diagram sticks to the same conventions.</p>
<p>The style I have chosen is primarily based upon the Braude textbook, but with
visibility and return types for operations.</p>
<p>Furthermore, Rose only finds the dependencies that occur within the return
or parameter types for the operations, and not any classes referred to within
the methods. I have chosen to illustrate those classes as dependencies as well,
this is a little extra work, but I feel it is more descriptive whilst not introducing
too much in the way of clutter.</p>
<p><em>Thursday 11:29am</em></p>
<p>Came down into GPS 109 to write the journal and make a little more progress
in diagramming and reverse engineering my share of classes. I did <em>Selector</em> and <em>SelectorFrame</em> yesterday,
and I am up to the "Umlet" class. Hmm - the Umlet class, in an application
called UMLet. I can tell without looking that this class is gunna be huge.</p>
<p><em>Thursday 6:00pm</em></p>
<p>The Umlet class is indeed huge. I am beginning to suspect that my UML diagram
style is going to create too much work. I am thinking of simplifying it somewhat.</p>
<p>One problem I have encountered is looking at classes and trying to determine
from which package they are. I’ve seen Eclipse used as an IDE, and it appears
to be good at things like telling you what package a certain class is from just
by pointing at it. This would sure beat the circuitous method I currently use
to get this information, but I’m not sure if I want to learn a new IDE this
far into the task.</p>
<p><em>Friday 10:00am</em></p>
<p>Today I took a break from the Umlet class (as yet unfinished) and started
on the next one in the list - <em>UniversalListener</em>. This is also a big
class - both in terms of the list of attributes and operations, and the number
of classes upon which it depends.</p>
<p>I intend to take the diagram to the tutorial this afternoon to get some advice
on how I should diagram monstrosities like Umlet and <em>UniversalListener</em>.
It is far too much work to comb the code, inside each method, looking for classes
and trying to find out</p>
<p>One idea I have is, instead of drawing a border around co-packaged classes
and to draw the dependency arrow to each one, I simply put the ’package’ icon
on my diagram, label it with the name of the package, eg. "<em>java.awt</em>",
and draw the dependency arrow to it.</p>
<p>But then, there is the case of packages that contain both loose dependencies
and rigid dependencies such as aggregations.</p>
<p>Stephen G has taken two of my classes off my hands, so that he may document
the entire "io" package. No objection here.</p>
<p><em>Friday 3:00pm</em></p>
<p>I decided not to get the advice from the tutorial, as I am going to be studying
for another course all weekend and I can get advice from Doug in the practical
on Tuesday morning. Any spare time I get will be divided between this and yet
another course in which I have pending assessment due.</p>
<p><em>Tuesday 10:00am</em></p>
<p>I spent some of the prac today redrawing some of the UML diagrams, and discussing
with Doug the Tutor whether I was on the right track with my diagrams, what
needed to be changed, what might be more effective, etc. He seemed fairly positive
and didn’t make any suggestions for change.</p>
<p>The ironic thing is, the way I am doing the diagrams now is quick and easy,
but deciding to do them this way involved a lot of trial and error - realising
that too much detail is bad, therefore simplifying without reducing the amount
of useful information.</p>
<p>Furthermore I have pretty much volunteered to do all the UML diagrams for
this assignment, in order that they are all consistent, looking great, et cetera.
As my method is "quick and easy" I expect this will not take a huge
amount of time. I figured that I would compile everyone’s best ideas from their
respective UML diagrams into one style that I could apply consistently.</p>
<p>As an example of an "idea", I had been drawing each class in its
own diagram. For the bigger classes, this was a space-saving exercise, as having
too much clutter would reduce the effectiveness of the diagram. But I was following
the one class per diagram rule steadfastly, even for the small classes.</p>
<p>Stephen J, on the other hand, drew a lot of smaller classes that inherited
from the Command class in the same diagram, with dependency arrows pointing
to Command, so that the importance of Command is made more obvious.</p>
<p>My idea of leaving out the private methods and attributes, except where they
help illustrate some design pattern or expound upon something said in the description
of the class, also appears to have survived.</p>
<p>My focus for the next four days is getting all the classes diagrammed in Visio,
and documenting the classes I was given, whilst allowing time for another course’s
assignment due the same day as this one.</p>
<p><em>Wednesday 2:52pm</em></p>
<p>Came in to uni to do some more of this assignment. The only real reason I
am coming in is to use Visio, and it appears this is available free to us on
the MSDNAA scheme, so I hope to take advantage of this and do more of it at
home.</p>
<p>Jervina (from another group studying UMLet) asked me about an aspect of the <em>UniversalListener</em> class,
which happens to be one of the classes I am documenting. I found that discussing
it helped me to understand the code a bit more. The code in question is difficult
to understand as it is riddled with things like:</p>
<p> if (RESIZE_DIRECTION == 12) { ... }</p>
<p>The method that sets RESIZE_DIRECTION is in another class, so one must do
a lot of backtracking to work out what "12" means. The ensuing backtracking
revealed that "12" means ’top right’, because 12 = binary 1100, where
the first bit indicates ’top’, the second bit is ’right’, the third ’bottom’,
and the fourth ’left’.</p>
<p>This is truly a missed opportunity for object orientation, and gives me some
ideas for re-factoring UMLet in assignment three.</p>
<p><em>Thursday 9:23pm</em></p>
<p>Today, I have been working on a UML diagram containing Command and the eleven
other classes that extend it. I have also been doing diagrams for all the other
classes that we chose to cover for this assignment. These are almost done.
The class diagrams I will be completing later tonight.</p>
-->
<p>[Removed for privacy]</p>
<hr />
<h2>6.0 Extended
Project Planning</h2>
<h3>6.1 Further Documentation</h3>
<p>As part of the creation of this document a large section of the UMLet program
code has been documented, namely both the <em>com.umlet.control</em> and <em>com.umlet.control.io</em> packages
which contain the core program functionality. For future extension of the program’s
capabilities it is quite likely that further code examination and documentation
will be required.</p>
<p>Although the <em>com.umlet.plugin</em> package was considered beyond the scope
of this document it may be necessary to examine its use to provide an extended
feature set and/or added functionality to the UMLet program. More likely to
be required is an examination of the single class in the <em>com.umlet.element.custom</em> package.
The reason for this is that extension of this class can allow the addition of
extra object representations to the UMLet palette which can be placed on the
drawing window. Using this functionality is possibly one of the better areas
to improve the program in as it provides immediate and obvious extra functionality
to the user.</p>
<p>Based on these facts the list of packages that are intended to be investigated
during the next stage of this project is as follows:</p>
<table cellspacing="0" cellpadding="0">
<tr>
<td style="width:284px"> <p><em>com.umlet.plugin</em></p></td>
<td style="width:284px"> <p>UmletPlugin</p></td>
</tr>
<tr>
<td style="width:284px"> <p><em>com.umlet.plugin.editors</em></p></td>
<td style="width:284px"> <p>UmletEditor</p></td>
</tr>
<tr>
<td style="width:284px"> <p><em>com.umlet.plugin.wizards</em></p></td>
<td style="width:284px"> <p>NewWizard</p></td>
</tr>
<tr>
<td style="width:284px"> <p><em>com.umlet.element.custom</em></p></td>
<td style="width:284px"> <p>TemplateClass</p></td>
</tr>
</table>
<h3>6.2 Program Improvement</h3>
<p>As part of the code documentation process undertaken by the team for this
section of the project an effort was made to attempt to find areas in which
UMLet could be improved either in terms of functionality or code structure.
It is planned that at least some of these improvements will be added to the
program via the code base currently stored in the Con-current Versioning System
(CVS) during the next stage of this project. The areas which the team has selected
to be candidates for improvement are listed below with a brief description of
the suggestions.</p>
<ul class="wider">
<li>Extending save & open functionality:<br />
<br />
Currently UMLet has the ability to save to the JPG, SVG, PDF and EPS
file formats as well as its own UXF format which it also has the ability to
load from. To extend this functionality it has been suggested that adding the
ability to save to additional formats might be necessary. Possible formats
include BMP and a HTML/MATHML combination format. It has also been suggested
that adding the ability to load from the SVG format would be of some benefit.</li>
<li>Additional UML objects & improvement of the palette:<br />
<br />
As part of the extension process it may prove possible and even in some
cases necessary to extend the UMLet palette to include more objects for using
in diagrams. Examples may include adding further UML representations or pre-created
‘templates’ that represent common class grouping structures. Even if such extension
of the palette is not undertaken it is highly probable that some cleaning up
of the palette layout and the overall UMLet window will be necessary.</li>
<li>Code re-factoring<br />
<br />
During the documentation process there were several instances where it
was found that code layout for a given class and/or package was rather poor.
An example of this would be the <em>com.umlet.control.io</em> package where
several of the classes for file output (<em>GenEps</em>, <em>GenPdf</em> and <em>GenSvg)</em> share
a very common structure. This however is not reflected in the code base as
all three (3) of the classes are completely separate and share neither a common
interface nor an abstract parent class. As such it has been decided that in
this and several other instances an attempt will be made to create a common
interface or parent class which can group code together in a way more conducive
to efficient programming.</li>
<li>On-line help<br />
<br />
Currently UMLet provides little or no user help system and as such the
user is very much left up to their own devices when they first come to use
the program. The proposed way to improve this situation is to add at the very
least a help item in the menus to go to an external documentation file. Additional
possibilities in this area include adding features like ‘tip of the day’ and
help pop-ups on certain mouse actions.</li>
<li>Code documentation<br />
<br />
As part of any or all of the listed extensions it is hoped that it might
be possible to provide full code commenting and documentation for the classes
which have been modified. It is also planned to write full and appropriate
JavaDoc comments for the changed classes and to generate online source documentation
using the appropriate tool from Sun.</li>
<li>Additional User Interface (UI) functionality<br />
<br />
The UMLet user interface is quite basic and as such it has been decided
that some improvements need to be made in this area. This may include additions
such as including a right click menu and/or additional main menu functionality
to reflect other added features.</li>
</ul>
<h3>6.3 Testing Guidelines</h3>
<p>As the team has now documented a large section of the UMLet program source
code and selected appropriate goals for extension it is now necessary to outline
a basic test strategy so that actual implementation of suggested features can
begin. The test plan outlined in this section of the document will be relatively
general as it is yet to be seen which features will actually be chosen for full
implementation and as such it is difficult to say exactly which classes will
require testing. </p>
<p>The tool used for the majority of the testing will be JUnit as it is better
suited to the testing of UMLet than a solution like roast. This is in large
part because roast for the most part is geared towards simple value and exception
checks whereas JUnit provides the ability to write more robust and extensive
tests. Also important is the fact that roast adds an extra step between writing
of a test driver and actual running of the test(s), this is due to the fact
that roast is a Perl program and as such must first parse its test scripts
and create appropriate drivers before they any tests are able to be run. This
is in contrast to JUnit test scripts/drivers which are written entirely in Java
and require no further pre-processing before being sent to the compiler. </p>
<p>Unfortunately, due to the Graphical User Interface (GUI) nature of the software
being tested, there are more than likely going to be large areas of the program
which will prove quite difficult to test using automated tests. When this occurs
it is planned to use the automated testing procedures as much as is possible
with integration testing methods, once this is complete it is then intended
that system testing will be applied. This will be done to attempt to catch errors
which may only occur when the program is run as a full GUI application.</p>
<p>For the reasons previously outlined it is difficult to confirm exactly which
classes are to require testing. As such areas which are candidates for extension
are listed below with short descriptions of the classes that are expected to
be tested if said feature is implemented and how this may be accomplished.</p>
<ul class="wider">
<li>Extending save & open functionality:<br />
<br />
If any alterations are made to the program’s functionality in this area
then it is likely that the <em>FileOp</em> class and any class responsible
for input/output of data to the file system. This may include classes like <em>GenSvg</em> if
they are modified. As the <em>FileOp </em>class and all of its methods accept
input only through the GUI interface it will be necessary to test this class
manually. Luckily it performs only relatively basic options relating to the
selection of filenames for data output. Building a test driver for the classes
which actually build the data files while possible will be challenging. The
challenge in this instance is mainly provided by the fact that an actual object
representing the graphics to be drawn is required as a parameter to some class
methods. Once this is overcome however an appropriate test driver can be built
to test the methods as most of them make reasonable use of exceptions to provide
feedback to a testing program.</li>
<li>Additional UML objects & improvement of the palette: <br />
<br />
Extensions to the palette will revolve around extending <em>TemplateClass</em>,
as such any new classes created on this base will require testing. Due to the
small nature of the class(es) involved and the amount of common code they will
share it should be quite feasible to build an automated testing mechanism for
this section of the code base, should it be necessary. Like those testing scenarios
mentioned above however this will require the creation or ‘faking’ of a graphics
object with which to work. In this case however it is less of a problem as
the object can just be loaded straight from file.</li>
<li>Code re-factoring<br />
<br />
Currently the only code tagged for major re-factoring is that in the <em>com.umlet.control.io</em> class,
the possible testing of which has already been discussed above. If re-factoring
is successful the major change to this procedure will hopefully be that it
will be possible to test all of the output classes with a common test driver
or suite.</li>
<li>On-line help<br />
<br />
The most likely feature of the on-line help concept to be implemented
is ‘tip of the day’ functionality. It is most likely that this will involve
some file I/O and at the very least a class to control tip loading and display.
This class will be designed in such a way as to make writing test scripts with
JUnit relatively easy. It is intended that this will be done by both using
exceptions correctly and providing methods to monitor the class’ status. Thanks
to this it should be possible to use a unit testing methodology for this class
as it should be able to be created in a manner separate to all other program
functionality.</li>
<li>Code documentation<br />
<br />
For obvious reasons this is not something that will be tested with an
automated tool. Rather the updated classes will simply be run through the JavaDoc
program to generate code documentation in Hyper-Text Markup Language (HTML)
format.</li>
<li>Additional User Interface (UI) functionality<br />
<br />
As this is possibly the broadest area of possible feature expansion it
is also the hardest to predict testing strategies for. For the most part extensions
in this area will be tested via a system wide test plan as almost all feature
addition will be through code that is intrinsically tied to GUI input and output
functionality. Despite this an effort will be made to implement integration
testing, possibly through the creation of a ‘fake’ GUI application to provide
all of the required functionality to test the class(es).</li>
</ul>
<hr />
<h2>7.0 References</h2>
<ul>
<li>The Apache Software Foundation:
<ul>
<li><em>Avalon </em>(<a href="http://avalon.apache.org/">http://avalon.apache.org/</a>, <a href="http://jakarta.apache.org/#avalon">http://jakarta.apache.org/#avalon</a>)
15-09-2004</li>
<li><em>Batik </em>(<a href="http://xml.apache.org/batik/">http://xml.apache.org/batik/</a>)
15-09-2004</li>
<li><em>Crimson </em>(<a href="http://xml.apache.org/crimson/">http://xml.apache.org/crimson/</a>)
15-09-2004</li>
<li><em>FOP</em> (<a href="http://xml.apache.org/#fop">http://xml.apache.org/#fop</a>)
15-09-2004</li>
<li><em>Xalan </em>(<a href="http://xml.apache.org/xalan-j/">http://xml.apache.org/xalan-j/</a>)
15-09-2004</li>
</ul>
</li>
<li>EPSGraphics (<a href="http://www.jibble.org/javadocs/epsgraphics/">http://www.jibble.org/javadocs/epsgraphics/</a>)
15-09-2004</li>
<li>JDOM (<a href="http://www.jdom.org/">http://www.jdom.org/</a>) 15-09-2004</li>
</ul>
<hr />
<h2>8.0 Appendix
A – UML Diagram for the Command class</h2>
<p class="centre"><img
src="COMP2801-assignment-2-files/image030.png" alt="UML diagram" width="623" height="365" /></p>
<hr />
<h2>9.0 Appendix B – UML Diagram for the Umlet class</h2>
<p class="centre"><img
src="COMP2801-assignment-2-files/image032.png" alt="UML diagram" width="513" height="802" /> </p>
<hr />
<h2>10.0 Appendix C – build.xml</h2>
<pre><?xml version="1.0"?>
<project name="test" default="compile" basedir=".">
<property name="src" value="." />
<property name="build" value="build" />
<!—
Make sure the compiler knows where to find all classes this depends on
-->
<property name="libpath" value=".:lib/crimson.jar:lib/fop.jar:
lib/xalan-2.3.1.jar:lib/xml-apis.jar:lib/batik.jar:
lib/epsgraphics.jar:lib/jdom.jar:lib/xercesImpl-2.0.1.jar:
lib/avalon-framework-cvs-20020315" />
<!—
Prepare the build directory structure for compilation, note the use of clean,
this has to be used to prevent un-necessary files ending up in the jar file.
-->
<target name="init" depends="clean">
<mkdir dir="${build}" />
<mkdir dir="${build}/com" />
<mkdir dir="${build}/com/umlet/control" />
<mkdir dir="${build}/com/umlet/element" />
</target>
<target name="compile" depends="init">
<!—
Compile the UMLet Java code, we list these two directories seperately rather
than just using ${src}/com so that we don’t inadvertantly try to build the plugin
classes.
-->
<javac srcdir="${src}/com/umlet/control" destdir="${build}" classpath="${libpath}" />
<javac srcdir="${src}/com/umlet/element" destdir="${build}" classpath="${libpath}" />
<!—
Put the manifest file for Umlet3.jar into the build directory
-->
<copy file="META-INF/MANIFEST.MF" tofile="${build}/META-INF/MANIFEST.MF" />
<!-- Copy across the script for running UMLet3 -->
<copy file="shell/Umlet.sh" tofile="${build}/Umlet.sh" />
<chmod file="${build}/Umlet.sh" perm="u+x" />
<!-- Build the jar file using the newly compiled program -->
<jar manifest="${build}/META-INF/MANIFEST.MF" destfile="${build}/Umlet3.jar" basedir="${build}" />
<!—
Copy across the libraries which are distributed with UMLet.
-->
<copy todir="${build}/lib">
<fileset dir="./lib">
<filename name="**/*.jar" />
</fileset>
</copy>
<!—
Copy across the files which Umlet will run without, but not very well, basically
the icons and a few other minor things.
-->
<copy todir="${build}">
<fileset dir="./base">
<filename name="**/*" />
</fileset>
</copy>
<!—
Delete the class files as they are now in the JAR archive.
-->
<delete dir="${build}/com" />
<delete dir="${build}/META-INF" />
</target>
<target name="clean">
<!—
Simply delete the build directory and all it’s contents.
-->
<delete dir="${build}" />
</target>
</project>
</pre>
<p>26-Oct-2004</p>
</body>
</html>