1. CS288 Assignment

2. UniS 2 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.

3. UniS 3 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.

4. UniS 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. UniS 5 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

6. UniS 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.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... You will see lots of output like this

7. UniS 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. UniS 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. This is a javadoc comment. Notice how the * symbol is used within the comment No space between javadoc comment and the method header

9. UniS 9 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.

10. UniS 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/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.

11. UniS 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 reward students for demonstrating they understand the course material. We will not deduct marks for trivial errors.

12. UniS 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 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. mouseClicked mouseDragged mouseEntered mouseExited mouseMoved mousePressed mouseReleased

13. UniS 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. UniS 14 Part 1 Tips, the main method /** * 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. * * 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. * * 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) { 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. The symbol is syntax that makes a paragraph break appear in the final web page Note this only required 155 words.

15. UniS 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. UniS 16 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.

17. UniS 17 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.

18. UniS 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): :Circles toolBar: JToolBar setFloatable(true) circles: Vecor > area: Dimension > 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 affect some other significant object are illustrated. You can use PowerPoint for this or any other drawing package you wish. >

19. UniS 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 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.

20. UniS 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.