CS102: APIs, Java.util, Javadoc

Keep in mind the following items as you do Lab 1:

You build up a class hierarchy by creating subclasses using the extends keyword.

For example:

class Foo extends Bar{... }

Subclasses inherit all parent menbers (variables and methods), plus they can

-define new instance variables

-define new methods

-override existing methods, but still refer to the parents method using super, for example:

If Bar defines int myMethod(int x, int y), in Foo we can write:

int myMethod(int x, int y) { area x * y; super.myMethod(x,y); }

-define new constructers, calling the parents constructer as the first line, for example:

public Foo(String s) { super(s,3); ... }

An interface defines method names with return types and parameter lists, but no method bodies

A class may implement multiple interfaces, but can extend only one class

class Foo extends Bar implements Baz,Bam{ //must define each method for all interfaces!! (The compiler will check) }

An interface name can be used whenever a type is called for (such as in variable declaration, parameter lists and return types) and the compiler will check that whatever is assigned there actually implements the given interface.

An interface has no constucter and can't be instantisted

An abstract class is like a cross between an interface and a class. - It really is a class, but it can't be instantiated and some of its methods may lack bodies.

Its used in a class hierarchy to capture common functionality, but it isn't complete so it can't stand on its own.

- For example, ResizableObject in cs101.canvas is abstract. Its subclasses inherit its methods, but you can't instantiate it (can't say new ResizableObject(...). And this makes sense because what would it look like?

Multiple Constructers: In designing a package, it is often useful to provide multiple constructers so that objects can be created using different parameter lists.

For maximum code reuse, one constructor needs to be able to call another. Java supports that idea with the keyword this.

For example, you can optionally specify a background color when you create a cs101Canvas. This is completed as follows:

public class CS101Canvas{ public CS101Canvas(Color background){ this.background = background; .... } public CS101Canvas(){ this(Color.white);//no need to duplicate code! } }

APIs and java.util

Let's explore the class hierarchy of an example package, java.util.
The API (Application Programming Interface) for this package can be found at java.util

`java.util`

In the java.util class hierarchy diagram from Flanagan (Figure 30-1), note:

some classes from other packages

classes, abstract classes, final classes and interfaces look different

inheritance is shown with solid line

implementations of interfaces are shown with a dotted line

Vector

Let's take a closer look at Vector. A Vector is like an array, but the size can grow over time.

`new Vector()`	creates a vector with no elements
`addElement(Object x)`	adds x to the end of the vector
`insertElementAt(Object x, int index)`	puts x at specified location
`Object elementAt(int index)`	returns element at that location
`int size()`	returns current size of vector
`Object firstElement()`	returns firt element
`Object lastElement()`	returns last element
`int indexOf(Object x)`	returns the first index of x in the vector

And there are many more useful methods...

Stack

Stack is a sublcass of Vector that implements push, pop and peek.

java.util.Hashtable

Hashtable implements a mapping from objects to objects in a different way. You will learn about hashing in CS241.

`new Hashtable()`	creates an empty hashtable
`void put(Object x, Object y)`	makes x map to y
`boolean containsKey(Object x)`	retruns true if x is in the domain (list of keys)
`boolean contains(Object y)`	returns true if y is in range
`Object get(Object x)`	returns the object x maps to

java.util.Enumeration

Both Hashtable and Vector have a method Enumeration elements() which returns an "iterator" object theat can be used to step through all the elements of the data structure. Its methods are.

boolean hasMoreElements(); boolean nextElement();

You can't reset or go back, but you can create another Enumeration by calling the elements() method again.

Example:

If h is a Hashtable, you could say:

Enumeration enumerator = h.elements(); while( enumerator.hasMoreElements() ){ System.out.println(enumerator.nextElement());

}

External Documentation and Javadoc

When you need to deal with lots of classes in lots of packages, it's important to have well organized external documentation that describes all the classes and there methods.

Java provides support for generating external documentation for package API in the from of html web pages.

You insert special comments in your java file. Then you run the javadoc program and it creates all the html files automatically. (It acts like a documentaion compiler)

See the Hashtable API and java source code for Hashtable for an example.