Exercise Sheet 3a: Lets Interface!

The aims of this exercise are to:

practice writing some recursive methods
practice creating and using an interface
become familiar with javadoc
see how Xcode builds work "behind the scenes" and modify a build file so that your code is automatically documented

Most of the material in this exercise sheet will be used again in later exercise sheets. If you do not finish it during the scheduled lab it is important that you continue working through it in your own time (or other labs) during the week.

1. Writing Recursive Methods

In the DSA lectures we saw an example of a class RMaths.java for doing mathematics recursively, based on increment and decrement only. We also saw a test program RMathsTest.

Create a project called RMathsTest. Download the file RMaths.java and place it in the src directory.
Extend the RMaths file with recursive definitions for power(x,y) which returns the value of x^y (x raised to the power of y), and factorial(x) which returns the value of x! (x factorial).
Test your program by putting some print statements in the main method of the test file RMathsTest.java.
What is (a) 3⁵ and (b) 5! ?

2. Writing and Implementing Interfaces

Create a new Xcode Ant-based Jar project called LockTest.
An interface specifies what methods must be in a class, without saying how those methods should be implemented. It is written as follows:
```
  public interface MyInterface {

    public returnType myFirstMethod (argumentType argumentName,...);

    public returnType mySecondMethod (...);   

     ...

  }
```
Notice that it has the same layout as a class file, but with the keyword interface instead of class, no member variables, and no code associated with the methods.
Right click on LockTest under Groups & Files and choose Add | New file. Choose "Java class" under "Pure Java" and click Next. After Location click Choose, then select the src directory. Name the file Lock.java then press Finish.
Open an editor for the file Lock.java and change the keyword "class" to "interface". Then complete an interface for the combination lock in Question 1 of Prac Sheet 2 (see the unit web page under "Practice Classes"). The three methods should return true if the operation succeeded (for example, if the lock opened with the combination passed to it), and false otherwise.
Build the project to ensure your interface compiles.
Write two different implementations of your interface. An implementation is a normal class file with the additional keyword implements followed by the interface name. For example:
```
  // my implementation of a Lock using integers to store the combination

  public class LockInt implements Lock {
  ...
  }
```
The first implementation (LockInt) should store the combination as an integer between 000 and 999 inclusive. The second implementation (LockString) should store the combination as a String. In both cases the member variables should be private (obviously you don't want anyone looking at the combination!) Also, regardless of how the combination is stored, it must be passed to the methods as an int. (To store it as a String it must be converted. Look at the Java API for methods to do this.)
Compile both classes. In LockTest.java write a small test program to ensure that both implementations work.
A reference (variable) of an interface type can "hold" an object of any class that implements that interface. For example, consider the following portion of a test program:
```
  Lock myLock;
  myLock = new LockInt(345,true);
  myLock.changeCombo(345,777);
  if (myLock.open(777)) System.out.println("Hey, I'm in!");
```
Notice that the only part of the program that refers to the specific implementation is the assignment in the second line. From then on we only use public methods available in the interface, regardless of which implementation we have picked. Try the above code, then change the second line to:
```
  myLock = new LockString(345,true);
```
You should find that the rest of the program still works correctly.
This is a powerful feature of object-oriented programming, and all of our data structures will be implemented in this way.

3. Programming Conventions

When you work as a programmer you will be required to follow the programming conventions specified by that company. This provides the company with uniformity across different coders and makes the systems easier to maintain.

Similarly, as mentioned in lectures, all code submitted for assessment in the programming test and exam for this unit must comply with the Java Programming Conventions for the unit. (Code that does not follow the conventions will lose marks.) If you have not read these yet you should do so now.

4. Using `javadoc`

As described in the DAT Notes and the document Java Programming Conventions all code submitted on the course must be documented using Java's automatic documentation facility, javadoc. Fully document your Lock interface now.
Open a shell (Terminal window) and change to your LockTest project directory. Using the shell (mkdir), or the Finder, create a new subdirectory called doc to store your documentation.
You can run javadoc on a single class by entering a command of the form:
```
  javadoc -d doc src/Lock.java
```
This says to run javadoc (the automatic documentation generator) on the file Lock.java in the src directory and direct the output to the directory doc.
Notice that all unix commands refer to files and directories relative to the current working directory (which you can check with the pwd command).
Try this now, then open (using Finder) the file index.html in the doc directory. You should see documentation for the interface you have written.
It is more usual to run javadoc on all the files in the directory (or, once you have packages, on all your packages) as javadoc will create indices, lists of packages, etc, giving a complete linked hierarchical view of all your code, just as it does for the Java API.
You can run javadoc on a list of files by putting the names one after another, or using Unix `wildcard' characters like "*". Try:
```
  javadoc -d doc src/*.java
```
javadoc will create index and contents ("packages") files for all the files listed in the command.
Try this now and again open the index.html file. You should see the documentation for your interface, and any other classes you have in the directory (in this case LockTest), just as it appears in the Java API. Try the "Tree" and "Index" options at the top of the page.

5. *DIY Challenge

As mentioned in the lectures, as well as learning specifically about topics such as data structures or even Xcode, we'd like to give you the opportunity to become"multilingual" computing professionals and give you exposure to a range of operating systems, languages, open source software and public domain protocols, and an understanding of how things work "behind the scenes". An example of this is the build system used by Ant-based projects in Xcode.

As mentioned in lectures, when you press the "Build" key in Xcode, it uses the open source ant program from the Apache Ant Project to compile your classes, set classpaths, construct the jar archive, put the build products in the right directories, etc.

To see where this program resides on your machine, open a shell window and enter:

  $ which ant

Then have a look at the Ant program's man page.

The Ant program in turn uses the xml standard protocol for instructions as to what you want it to do. These instructions are contained in the file build.xml in your project. Have a look at this file and see if you can "read" what it does. Each task in the file has a "target" that can be called. When you press "Build" Xcode calls the "jar" target, which in turn depends on (and hence calls) the "complile" target. See if you can see what they do.

To get a better idea of what the commands in build.xml do, and what additional commands are at your disposal, look at the manual for Ant at the above web location.

Returning to your Lock project, you don't want to have to leave the project and run javadoc in a separate shell each time you edit the code. Rather, you would like it to automatically refresh the documentation as you develop your code. Your task therefore is to edit the build.xml file so that your javadoc documentation is automatically generated and placed in the doc directory each time you build your code.

6. More Practice

Try implementing solutions to the other exercises in Prac Sheets 1 and 2.



	Exercise Sheet 3a: Lets Interface! The aims of this exercise are to: practice writing some recursive methods practice creating and using an interface become familiar with `javadoc` see how Xcode builds work "behind the scenes" and modify a build file so that your code is automatically documented Most of the material in this exercise sheet will be used again in later exercise sheets. If you do not finish it during the scheduled lab it is important that you continue working through it in your own time (or other labs) during the week. 1. Writing Recursive Methods In the DSA lectures we saw an example of a class `RMaths.java` for doing mathematics recursively, based on `increment` and `decrement` only. We also saw a test program `RMathsTest`. Create a project called `RMathsTest`. Download the file `RMaths.java` and place it in the `src` directory. Extend the RMaths file with recursive definitions for `power(x,y)` which returns the value of `x^y (x` raised to the power of `y`), and `factorial(x)` which returns the value of `x!` (`x` factorial). Test your program by putting some print statements in the `main` method of the test file `RMathsTest.java`. What is (a) 3⁵ and (b) 5! ? 2. Writing and Implementing Interfaces Create a new Xcode Ant-based Jar project called `LockTest`. An interface specifies what methods must be in a class, without saying how those methods should be implemented. It is written as follows: public interface MyInterface { public returnType myFirstMethod (argumentType argumentName,...); public returnType mySecondMethod (...); ... } Notice that it has the same layout as a class file, but with the keyword `interface` instead of `class`, no member variables, and no code associated with the methods. Right click on LockTest under Groups & Files and choose Add \| New file. Choose "Java class" under "Pure Java" and click Next. After Location click Choose, then select the `src` directory. Name the file `Lock.java` then press Finish. Open an editor for the file `Lock.java` and change the keyword "class" to "interface". Then complete an interface for the combination lock in Question 1 of Prac Sheet 2 (see the unit web page under "Practice Classes"). The three methods should return `true` if the operation succeeded (for example, if the lock opened with the combination passed to it), and `false` otherwise. Build the project to ensure your interface compiles. Write two different implementations of your interface. An implementation is a normal class file with the additional keyword `implements` followed by the interface name. For example: // my implementation of a Lock using integers to store the combination public class LockInt implements Lock { ... } The first implementation (`LockInt`) should store the combination as an integer between 000 and 999 inclusive. The second implementation (`LockString`) should store the combination as a `String`. In both cases the member variables should be private (obviously you don't want anyone looking at the combination!) Also, regardless of how the combination is stored, it must be passed to the methods as an `int`. (To store it as a `String` it must be converted. Look at the Java API for methods to do this.) Compile both classes. In `LockTest.java` write a small test program to ensure that both implementations work. A reference (variable) of an interface type can "hold" an object of any class that implements that interface. For example, consider the following portion of a test program: Lock myLock; myLock = new LockInt(345,true); myLock.changeCombo(345,777); if (myLock.open(777)) System.out.println("Hey, I'm in!"); Notice that the only part of the program that refers to the specific implementation is the assignment in the second line. From then on we only use public methods available in the interface, regardless of which implementation we have picked. Try the above code, then change the second line to: myLock = new LockString(345,true); You should find that the rest of the program still works correctly. This is a powerful feature of object-oriented programming, and all of our data structures will be implemented in this way. 3. Programming Conventions When you work as a programmer you will be required to follow the programming conventions specified by that company. This provides the company with uniformity across different coders and makes the systems easier to maintain. Similarly, as mentioned in lectures, all code submitted for assessment in the programming test and exam for this unit must comply with the Java Programming Conventions for the unit. (Code that does not follow the conventions will lose marks.) If you have not read these yet you should do so now. 4. Using `javadoc` As described in the DAT Notes and the document Java Programming Conventions all code submitted on the course must be documented using Java's automatic documentation facility, `javadoc`. Fully document your `Lock` interface now. Open a shell (Terminal window) and change to your `LockTest` project directory. Using the shell (mkdir), or the Finder, create a new subdirectory called `doc` to store your documentation. You can run `javadoc` on a single class by entering a command of the form: javadoc -d doc src/Lock.java This says to run `javadoc` (the automatic documentation generator) on the file `Lock.java` in the `src` directory and direct the output to the directory `doc`. Notice that all unix commands refer to files and directories relative to the current working directory (which you can check with the `pwd` command). Try this now, then open (using Finder) the file `index.html` in the `doc` directory. You should see documentation for the interface you have written. It is more usual to run `javadoc` on all the files in the directory (or, once you have packages, on all your packages) as `javadoc` will create indices, lists of packages, etc, giving a complete linked hierarchical view of all your code, just as it does for the Java API. You can run `javadoc` on a list of files by putting the names one after another, or using Unix `wildcard' characters like "``". Try: javadoc -d doc src/.java `javadoc` will create index and contents ("packages") files for all the files listed in the command. Try this now and again open the `index.html` file. You should see the documentation for your interface, and any other classes you have in the directory (in this case `LockTest`), just as it appears in the Java API. Try the "Tree" and "Index" options at the top of the page. 5. *DIY Challenge As mentioned in the lectures, as well as learning specifically about topics such as data structures or even Xcode, we'd like to give you the opportunity to become"multilingual" computing professionals and give you exposure to a range of operating systems, languages, open source software and public domain protocols, and an understanding of how things work "behind the scenes". An example of this is the build system used by Ant-based projects in Xcode. As mentioned in lectures, when you press the "Build" key in Xcode, it uses the open source `ant` program from the Apache Ant Project to compile your classes, set classpaths, construct the jar archive, put the build products in the right directories, etc. To see where this program resides on your machine, open a shell window and enter: $ which ant Then have a look at the Ant program's man page. The Ant program in turn uses the `xml` standard protocol for instructions as to what you want it to do. These instructions are contained in the file `build.xml` in your project. Have a look at this file and see if you can "read" what it does. Each task in the file has a "target" that can be called. When you press "Build" Xcode calls the "jar" target, which in turn depends on (and hence calls) the "complile" target. See if you can see what they do. To get a better idea of what the commands in `build.xml` do, and what additional commands are at your disposal, look at the manual for Ant at the above web location. Returning to your Lock project, you don't want to have to leave the project and run javadoc in a separate shell each time you edit the code. Rather, you would like it to automatically refresh the documentation as you develop your code. Your task therefore is to edit the `build.xml` file so that your javadoc documentation is automatically generated and placed in the `doc` directory each time you build your code. 6. More Practice Try implementing solutions to the other exercises in Prac Sheets 1 and 2.



	Copyright © 2006 Cara MacNish, School of Computer Science & Software Engineering, UWA.