Transcript Document

CS288 Assignment
Contents
• Getting the source code from the web site
• Short introduction to the javadoc tool
• The assignment marking scheme, and what to
submit
• The assignment itself (starts on page 12)
Read the WHOLE of this document before you
begin the assignment.
UniS
2
First get these files
Goto the course web site:
http://www.computing.surrey.ac.uk/courses/cs288/Examples/CirclesDemo
Download 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/cs288/Examples/CirclesDemo/images/
into your images folder that you just created.
UniS
3
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.
UniS
4
JavaDoc
Visit these links to find out about a useful tool called JavaDoc:
• http://www.computing.surrey.ac.uk/courses/cs288/Java_Documentation/docs/tooldocs/windows/javadoc.html - documentingclasses
• http://www.computing.surrey.ac.uk/courses/cs288/Java_Documentation/docs/tooldocs/windows/javadoc.html - 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
UniS
5
JavaDoc output
You will see
lots of output
like this
UniS
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.html...
Generating JavaDoc\index-all.html...
Generating 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...
6
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.
UniS
7
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 a javadoc comment.
Notice how the * symbol is
used within the comment
/**
* This is where we can add documentation for
* createPopupMenu that will be picked up by the
* Java Doc tool when it creates the webpage
*/
No space between javadoc
public void createPopupMenu() {
comment and the method header
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.
UniS
8
Method createPopupMenu documentation.
Now click on the METHOD link at the top of the Circles.html page:
Note the comments we added with the special javadoc
comment syntax now appear in the method summary.
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.
UniS
9
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/cs288/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.
UniS
10
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 reward
students for demonstrating they understand the course
material. We will not deduct marks for trivial errors.
UniS
11
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
mouseClicked
addButtons
mouseDragged
createPopupMenu
mouseEntered
main
mouseExited
makeNavigationButton
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.
UniS
12
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.
UniS
13
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
The <p> symbol is syntax that
* interpreter during run time. Note it is static,
makes a paragraph break
* which makes it a class method, not an instance method.appear in the final web page
* <p>
* 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.
* <p>
* 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
Note this only
* with components and add the necessary functionality
* to make things happen when mouse events are triggered.
required 155
*/
words.
public static void main(String[] args) {
UniS
14
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
UniS
15
Part 1 Tips, the main method
In the Method Summary section only the first sentence of the
documentation we added is shown. To see all the documentation we have to
click on the method name.
UniS
16
The assignment, part 2
Draw a class diagram for the Circles class. You can use PowerPoint for
this 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.
UniS
17
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):
:Circles
toolBar:
JToolBar
circles:
Vecor
area:
Dimension
<<creates>>
<<creates>>
<<creates>>
Diagram so far comes from this
code in the constructor:
setFloatable(true)
You can use PowerPoint for this or any other
drawing package you wish.
UniS
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 affect
some other significant object are
illustrated.
18
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 call
arrow. 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.
UniS
19
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.
UniS
20