CS288 Assignment

1
CS288 Assignment
2
Contents

• Getting the source code from the web site
• Short introduction to the javadoc tool
• The assignment marking scheme, and what tosubmit
• The assignment itself (starts on page 12)
• Read the WHOLE of this document before you
• begin the assignment.

3
First get these files
Goto the course web site http//www.computing.sur
rey.ac.uk/courses/cs288/Examples/CirclesDemo Down
load the file Circles.java (make sure you do not
change the case of the file name). Make a
subfolder called images in the folder where you
have stored the Circles.java file. Download the
files from the images directory on the web
site http//www.computing.surrey.ac.uk/courses/cs2
88/Examples/CirclesDemo/images/ into your images
folder that you just created.
4
Try Out the Code

• Compile Circles.java and run the code
• javac Circles.java java Circles
• What happens when you left-click with the mouse
  in the main area of the application?
• Try dragging a circle around the main component
  pane.
• What do the buttons labelled with icons do?
• After you have made a few circles, type some text
  into the text-field at the top of the
  application, and hit return. What has happened to
  the text labels for the circle shapes.

5
JavaDoc

• Visit these links to find out about a useful tool
  called JavaDoc
• http//www.computing.surrey.ac.uk/courses/cs288/Ja
  va_Documentation/docs/tooldocs/windows/javadoc.htm
  l - documentingclasses
• http//www.computing.surrey.ac.uk/courses/cs288/Ja
  va_Documentation/docs/tooldocs/windows/javadoc.htm
  l - documentationcomments
• Note you will be unable to complete this
  assignment until you are familiar
• with this tool.
• Open a command shell, then 'cd' to the folder
  where Circle.java lives.
• Try out this command
• javadoc -d JavaDoc Circles.java

6
JavaDoc output
Loading source file Circles.java... Constructing
Javadoc information... Standard Doclet version
1.4.2_02 Generating JavaDoc\constant-values.html..
. Building tree for all the packages and
classes... Building index for all the packages
and classes... Generating JavaDoc\overview-tree.ht
ml... Generating JavaDoc\index-all.html... Generat
ing JavaDoc\deprecated-list.html... Building
index for all classes... Generating
JavaDoc\allclasses-frame.html... Generating
JavaDoc\allclasses-noframe.html... Generating
JavaDoc\index.html... Generating
JavaDoc\packages.html... Generating
JavaDoc\Circles.html... Generating
JavaDoc\Circles.DrawingPane.html... Generating
JavaDoc\serialized-form.html... Generating
JavaDoc\package-list... Generating
JavaDoc\help-doc.html... Generating
JavaDoc\stylesheet.css...
You will see lots of output like this
7
JavaDoc Web Pages
Use a web browser to open the Circles.html file
that now exists in the new subfolder JavaDoc that
javadoc created. What do all the links do? E.g.
try FIELD and METHOD.
8
javadoc comments
Open Circles.java in an editor (e.g. Emacs) Find
the method createPopupMenu() Change the code so
that the it looks like / This is
where we can add documentation for
createPopupMenu that will be picked up by the
Java Doc tool when it creates the webpage
/ public void createPopupMenu() Note you
can cut and paste text from this presentation
if you download it directly to your PC (rather
than view it with Internet Explorer). Now rerun
javadoc -d JavaDoc Circles.java and reload the
Circles.html file that is generated.
9
Method createPopupMenu documentation.
Now click on the METHOD link at the top of the
Circles.html page
In fact only the first sentence (in this case the
whole thing) appears in the Method Summary
section. The Method Detail section contains the
full documentation.
10
Be familiar with the documentation
Make sure you have read all the relevant
documentation from the Java Tutorial web site,
including the javadoc documentation. In part 1
of the assignment you are expected to use the
online tutorial and documentation from the course
web site to find out about any classes you are
not familiar with. For a short description of
ALL Java classes see this link on the course web
site http//www.computing.surrey.ac.uk/courses/cs
288/Java_Documentation/docs/api/index.html Only
once you are familiar with how to navigate
through the online documentation should you
continue with the assignment.
11
The assignment, marking scheme

• The assignment is worth 40 of the entire course
  mark.
• I will mark the total assignment out of 40, so
  that each
• mark is worth 1 of the total mark available for
  the
• whole course.
• Part 1, 20 marks
• Part 2, 10 marks
• Part 3, 10 marks
• The assignment should be printed on A4 paper.
• Your name, and the course title MUST be on a
  cover
• page attached to the front of the assignment.
• The course title is CS288.
• The overall philosophy of the markers will be to
  rewardstudents for demonstrating they understand
  the coursematerial. We will not deduct marks for
  trivial errors.

12
The assignment, part 1
Add special javadoc comments to the Circles.java
file that explain what the constructor does and
what each of the methods do that are listed in
the Method Summary section of Circles.html. These
methods are
actionPerformed addButtons
createPopupMenu main
makeNavigationButton
mouseClicked mouseDragged
mouseEntered mouseExited
mouseMoved mousePressed
mouseReleased
When you are happy with the javadoc comments you
have added rerun the command javadoc -d
JavaDoc Circles.java Print out the Circles.html
file in the JavaDoc subfolder. That is your
answer to Part 1.
13
Part 1 Tips
Some of the methods in Circles.java, such as
mouseEntered, are empty.Obviously these method
do not do anything. So why bother to include it?
The answer is found from checking out what a
class must do when it implements an interface
class. In this case Circles.jave implements both
MouseListener and MouseMotionListener. Look
through the Java Tutorial on the course web site
to find out what is involved in implementing an
interface. See the "Learning the Java Language"
trail in the Java Tutorial for a link to tell you
about interfaces. Marks will be given for
clarity and succinctness, NOT length. When adding
comments imagine they are going to be read by a
fellow student on the course. After reading your
comments they will understand roughly how the
important parts of the code works. Do not use
more than 500 words to describe any single
method. For empty methods do not use more than
200 words. Warning The Circles.java code is
not nice clean code. You will have to ignore
redundant code that no longer has any effect. By
tracing through the code you can figure out what
is or is not redundant.
14
Part 1 Tips, the main method
To give you an idea of what I'm after here is
what I would write for the main method. The
source code contains this javadoc comment, so you
can also view it there.
/ This method is always present in a
Java application. It is the first method
to be invoked by the Java interpreter
during run time. Note it is static, which
makes it a class method, not an instance method.
ltpgt This application is a GUI,
therefore we should delay trying to create
the main JFrame until the right moment. To
do otherwise may cause the whole application to
deadlock. To achieve this we use the main
method to add a new task to the event
dispatcher that will make sure the GUI does not
interfere with the rest of the application
while it is initialised. ltpgt The
invokeLater method will add a new task to the
event dispatcher. In this case that will
cause the createAndShowGUI method to be
invoked at a suitable time. That
method will create and populate the GUI
with components and add the necessary
functionality to make things happen when
mouse events are triggered. / public
static void main(String args)
Note this only required 155 words.
15
Part 1 Tips, the main method
Now when we rerun javadoc and look at the Method
Detail part of the Circles.html page it looks
like this
16
Part 1 Tips, the main method
In the Method Summary section only the first
sentence of thedocumentation we added is shown.
To see all the documentation we have to click on
the method name.
17
The assignment, part 2
Draw a class diagram for the Circles class. You
can use PowerPoint forthis or any other drawing
package you wish. This must show

• All inner classes
• Any interfaces that are implemented
• Any classes that are extended
• Any important dependencies (e.g. JFrames, or
  Vector)

TIP look at lectures 7 and 8 for examples of
class diagrams of the general format and content
you should be considering in this case.
18
The assignment, part 3
Draw a sequence diagram that shows the important
interactions within the Circles constructor
method. Below is the start for such a
diagram(note it does not list all the object
life-lines you will need in your answer)
ltltcreatesgtgt
ltltcreatesgtgt
ltltcreatesgtgt
Diagram so far comes from this code in the
constructor area new Dimension(0,0) circles
new Vector() //Create the toolbar. JToolBar
toolBar new JToolBar("Still
draggable") addButtons(toolBar)
toolBar.setFloatable(true) Note how only lines
of code that affectsome other significant object
are illustrated.
setFloatable(true)
You can use PowerPoint for this or any other
drawing package you wish.
19
The assignment, part 3
TIP A sequence diagram shows an arrow when a
method is executed by some other object. So a
line of code in class b that says a.m(x), will be
illustrated as an arrow from the lifeline for
object a to the lifeline for object b with label
m(x). An interaction for this example is either
a creates arrow or a method callarrow. It is up
to you to decide what the important interactions
are. See lectures 7 and 8 for examples of the
kind of sequence diagrams that should be similar
to the one you will draw.
20
Plagiarism
Please note where I believe that a student has
copied inappropriately from someone else I
reserve the right to hold an oral exam of that
student in place of the assignment.

• The oral exam will consist of
• a one hour Power Point presentation by the
  student on the work contained in the student's
  assignment, explaining in detail every part of
  the work they have submitted
• in addition to the presentation there will then
  be exhaustive rigorous questioning covering all
  aspects of the course material and all aspects of
  the Java language and UML
• Marks for the oral exam will be at my discretion.