Docs

Docs

Dr Andy Evans

The Java Packages

We've now seen most of the core language.
Some of this is actually in the package java.lang, for example, the System and Math Classes. These you don't have to import - java.lang is always there for you.
The rest of Java is in packages that do specific stuff.
We'll spend the rest of the course looking at packages you can use.

Example

	
import java.io.*;
public class Write {
    public Write() {
		FileWriter f = null;
		try {
		    f = new FileWriter (someFile);
		} catch (IOException ioe) {
		    ioe.printStackTrace();
		}
		f.write("Hello World");
		f.close();
	}  
	public static void main (String args[]) {
		new Write();
    }
}

Main packages

java.io (file reading/writing)
java.awt and javax.swing (windows applications)
java.applet (web applications)
java.net (network communication)
java.util and java.lang (bits and pieces)
But, how do we know how to use these packages and classes?

Documentation

We've seen that we should comment our code for developers, using // comments.
But that relies on seeing our code.
Better to supply API (Application Programming Interface) documentation that says what each class and method does.
One of the great things about Java is that comments can (and should) be written so that they can be automatically turned into documents about the programs.
You do this with the 'javadoc' program.

The Docs

Each class in the core language has a webpage that lists its variables and methods, along with examples of use.

Two comment types

Comments you don't want to put in the documentation start // After this you can't write code on the same line, just comments E.g.,
```
	
// End of Class.
}
	
// This bit of code calculates horror
// on a rating of one to ten.
```
Comments you want in the documentation should be associated with a block or object and be laid out thus...
```
	
/**
 * This is a class for working out 
 * how long we've been sat here.
*/
```

The documentation

The documentation comes out as webpages.
This means that if you can write HTML you can format your documentation.
The 'docs' (as we pros like to call them) list:
- the methods, what you pass to them and get out of them,
- any important variables,
- other info.
- They're available for all the core classes and interfaces.

Generics

Only thing you won't recognise in the docs is the use of angle brackets, thus:
```
	
Class Vector<E>
add(E e)
```

Or

	
containsAll(Collection<?> c)
addAll(Collection<? extends E> c)

These mean the class stores java.lang.Object type objects, but can be forced to be more specific to reduce potential casting errors.

Example

These storage objects can be parameterized. i.e. they can be given a specific type other than Object.
```
	
Vector<String> v = new Vector<String>();
```
You can also declare these in Method parameters...
```
	
void myMethod(Vector<String> v) {
```
You can build your own parameterizable types that take in Classes of a particular type...

	
class ClassName<T extends OptionalClass> {
private Vector<T> items = new Vector<T>();
    void add(T item) {   
		items.add(item);   
    }
    
    T get(int index){
		return items.get(index);  
    } 
}

Docs

Find your class or package, and click on the link.

Docs examples