LearningJavaAPI

About this page

This page contains my notes from when I started to learn about the Java API as preparation for the SCJP.

The root class: `java.lang.Object`

All classes in Java are descendants of the root class Object even though they do not explicitly extend that class. Inheriting from Object provides a certain set of capabilities to all Java classes:

getClass method: Returns a Class object that represents the object's class at runtime. Great for introspection! :-)
equals method: Indicates whether two objects are "equal". The default implementation returns true only if the two objects being compared are the same instance. The meaning of "equality" depends on the objects' types: With primitive wrappers the case is pretty obvious, but what about java.io.File?
hashCode method: Returns a hash code value for the object. This is used mostly when an object is stored in a collection that uses hashing (e.g. Hashtable). Note: If equals() returns true for two objects, their hash code value must also be the same. If two objects are not equal, their hash code value may be different (but is not necessarily so).
clone method: Creates and returns a copy of this object.
toString method: Returns a string representation of the object.
notify method: TODO
wait method: TODO
finalize() method: This method is invoked just before an object is deleted by the Garbage Collector. It is therefore possible to override this method and implement code that performs some last-minute cleanup. In practice, it is not recommended to do this because there is no guarantee for any specific object that it will ever be garbage collected, so there is no guarantee that the code in finalize() will run, either. Note 1: It is possible that the actions taken in finalize() will prevent the object from being deleted. Note 2: finalize() is never called more than once per object. In other words, if finalize() is run and prevents the object from being deleted, and later on the object becomes eligible for deletion a second time, the GC will not run finalize() a second time.

Note: The API docs for java.lang.Object have additional interesting information not replicated here.

Strings

java.lang.String

Strings are not primitives, they are objects of type

java.lang.String

A String literal is a sequence of characters between double quotes:

String s = "Foo";

A few more notes about strings:

String objects are immutable
When a String object is created from a string literal, the JVM places the object into the so-called "String constant pool". If the same literal is encountered again, instead of creating a new object the JVM reuses the String object from the pool. Note: This does not happen if a String is created like this: new String("abc").

Examples for string handling

String s1 = "ab";             // New String object placed in the String constant pool
String s2 = "ab";             // Reuse String object from the String constant pool
String s3 = new String("ab"); // New String object, *NOT* placed in the String constant pool

assert(s1 == s2);             // == tests the object reference
assert(s1 != s3);
assert(s1.equals(s3));        // equals() tests the String content, not the object reference

String s4 = s1 + "cd";        // New String object contains "abcd"
s4 += "ef";                   // New String object contains "abcdef"; old String object "abcd" is lost
s4.concat("gh");              // No change to s4; new String object is created but lost immediately
String s5 = s4.concat("gh");  // New String object contains "abcdefgh"
String s6 = s5.toUpperCase(); // New String object contains "ABCDEFGH"
assert(s5.equalsIgnoreCase(s6));
String s7 = s6.toLowerCase(); // "abcdefgh"
s7 += "b";                    // "abcdefghb"
s7 = s7.replace('b', 'B');    // "aBcdefghB"

char c = s7.charAt(1);        // 'B'
int index = s7.indexOf(c);    // 1; search forward from beginning
index = s7.indexOf(c, 2);     // 8; search forward from index position 2
index = s7.lastIndexOf(c);    // 8; search backward from end
index = s7.lastIndexOf(c, 7); // 1; search backward from index position 7
index = s7.indexOf("cd");     // 2; searching also works for Strings

String s8 = s7.substring(5);      // "efghB"
String s9 = s7.substring(5, 6);   // "e"; ARGH! Who is the imbecile who declared that the 2nd parameter shall not be zero-based?
int length = s7.length();         // 9
assert(s5.startsWith("ab");
assert(s5.endsWith("gh");

String s10 = s7.toString()        // "aBcdefghB", duh! toString() is inherited from Object
String s11 = "   x   ".trim();    // "x"; removes leading *AND* trailing spaces

`java.lang.StringBuffer` and `java.lang.StringBuilder`

StringBuilder is new to Java 1.5. It has exactly the same API as the StringBuffer class, except StringBuilder is not thread safe.

Examples:

StringBuffer sb1 = new StringBuffer("ab");
sb1.append("cd");            // "abcd"
sb1.delete(1, 3);            // "ad"; ARGH! Again the imbecile is at work - the 2nd parameter is not zero-based!
sb1.insert(1, "bc");         // "abcd"
sb1.reverse();               // "dcba"
String s1 = sb1.toString();  // toString() is inherited from Object

// Each method returns a reference to the StringBuffer object, therefore we can use chaining like this. The
// method calls are the same as in the above example, the result therefore is "dcba".
StringBuffer sb2 = new StringBuffer("ab").append("cd").delete(1, 3).insert(1, "bc").reverse();

Generics

Generics are a new feature of Java 1.5. It works similar to templates in C++, e.g.

List<String> sList = new ArrayList<String>();
String s = "foo";
sList.add(s);
sList.add("bar");
sList.add(42);     // ERROR!
s = sList.get(0);  // no cast

Polymorphism examples:

class Foo
{
  void overload_1(List list) {}
  void overload_1(List<Object> list) {}   // ERROR! - Compiler cannot distinguish from overload above

  void method_2a(List list) {}
  void method_2b(List<Object> list) {}
  void method_2c(List<String> list) {}

  // This is "wildcard syntax". It instructs the compiler that the generic type
  // can be varied, but the method implementation must *NOT* add any objects
  // We are saying: "You can give us anything that IS-A Object; we will treat
  // it like that and will not attempt to add anything to the list that is not
  // an Object."
  void method_3a(List<? extends Object> list)
  {
    list.add(new Object());  // ERROR! - No objects must be added, even if they match the generic type
  }
  // Again the wildcard syntax, but unlike with the keyword "extends" this time
  // the compiler allows to add objects *IF* they are of the proper type.
  // We are saying: "You can give us a list with anything from String up until Object; we
  // might add something to the list, and if we do it will be a String (or any subtype thereof,
  // which of course is impossible since String is final)."
  void method_3b(List<? super String> list)
  {
    list.add(new String());     // OK
    list.add(new Object());     // ERROR! - Only objects of the subtype may be added
    list.add(new SubString());  // OK - SubString is a theoretical subclass of String
  }
  // Identical to List<? extends Object>
  void method_3c(List<?> list) {}
  // Use keywords "extends" and "super" even if the supertype or subtype is an interface
  void method_3d(List<? extends Serializable> list) {}
  void method_3d(List<? super Serializable> list) {}

  void doIt()
  {
    List<String> sList = new ArrayList<String>();  // OK - Normal polymorphism rules at work here: ArrayList is a subtype of List
    List<Object> oList = new ArrayList<Object>();
    ArrayList<String> sArray = new ArrayList<String>();

    method_2a(sList);  // OK - Works because of special backward compatibility
    method_2b(sList);  // ERROR! - If both parameter and argument use generics, the generic type *MUST* match
    method_2c(sArray); // OK - Again, normal polymorphism rules at work here

    method_3a(sList);  // OK - Works because of wildcard syntax
    method_3a(oList);  // ditto
    method_3b(sList);  // ditto
    method_3b(oList);  // ditto
  }
}

Declare new generic types and methods (instead of using premade collection types):

public class Foo<T1, T2>   // "T1" and "T2" can be any legal identifiers
{
  private List<T1> entryList;
  private T1 entry;
  private T1[] entryArray;
  private int i;             // can still use non-generic members
  private T2 somethingElse;

  public Foo(List<T1> list)
  {
    entryList = list;
    T1 entry = new T1();  // ERROR! - Instances cannot be created
  }
  public T1 getEntry()
  {
    return entryList.get(0);
  }
  public addEntry(T1 entry)
  {
    return entryList.add(entry);
  }
}

// Interfaces can also be defined using generics
public interface AnInterface<T> {}

// Define a generic method inside a normal class
public class Bar
{
  <T> void doIt(T entry) {}
  <T> T doWhat(T entry) { return entry; }
  <T> T doThat() { return new T(); }       // ERROR! - Instances cannot be created
  public <T> Bar(T entry) {}               // OK - A generic constructor (weird!)
  public <Bar> Bar(Bar entry) {}           // OK - But perverted: The parameter "entry" has the generic type, not type Bar
}

// Restrict the types that can be used. Note: "super" *CANNOT* be used!
public class Foo<T extends Serializable> {}
// ERROR! - Wildcard syntax doesn't make sense here!
public class Foo<? extends Serializable> {}

Collections

Overview

Collection interfaces and classes (all from `java.util`)
Type	Class or interface	Extends or implements	Collection flavour	Ordering	Remark
`Collection`	Interface	-
`List`	Interface	`Collection`			Access elements by index
`Queue`	Interface	`Collection`			Access elements at the front or end (typically FIFO)
`Set`	Interface	`Collection`			Elements must be unique (`equals()`)
`SortedSet`	Interface	`Set`
`NavigableSet`	Interface	`SortedSet`
`Map`	Interface	-			Key/value pairs, where the key must be unique (`equals()`)
`SortedMap`	Interface	`Map`
`NavigableMap`	Interface	`SortedMap`
`HashSet`	Class	`Set`	Set	Unordered
`LinkedHashSet`	Class	`HashSet`	Set	Ordered by insertion time	Like `HashSet` except for the ordering.
`TreeSet`	Class	`NavigableSet`	Set	Sorted	Like `HashSet` except for the sorting.
`HashMap`	Class	`Map`	Map	Unordered
`Hashtable`	Class	`Map`	Map	Unordered	Like `HashMap`, but access is synchronized and no null key/values are allowed
`LinkedHashMap`	Class	`HashMap`	Map	Ordered by insertion time	Like `HashMap` except for the ordering
`TreeMap`	Class	`NavigableMap`	Map	Sorted	Like `HashMap` except for the sorting
`ArrayList`	Class	`List`	List	Ordered by index	Like a regular array, but this one can change its size. List changes are not very fast.
`Vector`	Class	`List`	List	Ordered by index	Like `ArrayList`, but access is synchronized
`LinkedList`	Class	`List` and `Queue`	List	Ordered by index	Like `ArrayList`, but elements are doubly-linked. List changes are faster, but access is slower.
`PriorityQueue`	Class	`Queue`	Queue	Sorted	Sorting affects which elements are at the front or end of the queue. The head of this queue is the least element with respect to the specified ordering.
`Arrays`	Class	`Object`	Utility		Manipulate arrays. Most of the stuff in this class is static.
`Collections`	Class	`Object`	Utility		Manipulate collections. Most of the stuff in this class is static.

A few basic examples:

// List stuff
List<String> list1 = new ArrayList<String>();
String s = "foo";
list1.add("foo");                        // Append
list1.add(s, 0);                         // Insert at index position
System.out.println(list1.size());        // 2
System.out.println(list1.contains(42));  // false; works even though the argument is *NOT* a string!
System.out.println(list1.indexOf(42));   // -1 (or an index position if the element exists)
list1.get(0);                            // Access via index position
list1.remove("foo");                     // removes the first occurrence (i.e. the one with lowest index)
System.out.println(list1.size());        // 1
for (String sss : list1) {}              // for-each can also be used on collections (not only arrays)

List<Integer> list2 = new ArrayList<Integer>();
list2.add(42);  // Autoboxing adds an Integer

// Set stuff
HashSet<Integer> hashSet1 = new HashSet<Integer>();
assert(hashSet1.add(42));    // true if the element was added successfully
assert(! hashSet1.add(42));  // false if the element was not added (in this case because it already exists)

// Map stuff
HashMap<Integer, String> hashMap1 = new HashMap<Integer, String>();
Integer key1 = 42;
String value1 = "24";
hashMap1.put(key1, value1);                // Add entry to map; an old entry for the same key is replaced
hashMap1.containsKey(key1);
hashMap1.containsValue(value1);
hashMap1.get(key1);
String value2 = hashMap1.remove(key1);     // Removes an entry, returning the value that was associated with the key
hashMap1.remove("foo");                    // No exception, even though the key does not exist and is not an Integer
Set<Integer> keySet1 = hashMap1.keySet();  // The set contains all keys in the map

Iterators

Instead of using for-each, it is still possible to use iterators for List and Set:

List<Foo> fooList = new ArrayList<Foo>(); 
// populate list...

Iterator<Foo> it = fooList.iterator();  // Make an iterator; will traverse the collection in ASCENDING order
while (it.hasNext())
{
  Foo f = it.next();   // Cast not required because the iterator is declared with generics syntax
}

Converting between Lists and Arrays

Convert to List:

String[] sa = {"one", "two", "three", "four"}; 
List sList = Arrays.asList(sa);  // The list is connected to the array, i.e. changes to one will also affect the other!
sList.set(3, "six");             // Change List; this also changes the array
sa[1] = "five";                  // Change array; this also changes the List

// At this point, both the array and the List contain "one", "five", "three", "six"

Convert to array:

List<Integer> iList = new ArrayList<Integer>(); 
for (int x=0; x < 3; x++) { iList.add(x); }

Object[] oa1 = iList.toArray();                 // Create an Object array 
Integer[] ia1 = new Integer[3];
iList.toArray(ia1);                             // The array passed as an argument is filled with the list's element because
                                                // it is of sufficient capacity
Integer[] ia2 = new Integer[2];
iList.toArray(ia2);                             // The array passed as an argument is *NOT* of sufficient capacity -> the list's
                                                // element are filled into a *NEWLY CREATED* array -> since the return value is
                                                // not stored, the array is lost
ia2 = iList.toArray(ia2);                       // Same case, but this time the result is stored; ia2 now contains a *NEW* array
Integer[] ia3 = iList.toArray(new Integer[0]);  // Same case, but this time we don't even bother to pass an argument
Object[] oa2 = iList.toArray(new Object[0]);    // Functionally equivalent to the initial Object array example

Sorting and searching

Classes that implement the Comparable interface can be sorted inside a collection.

class Foo implements Comparable<Foo>
{
  String bar;
  String somethingCompletelyDifferent;
  String getBar() { return bar; }
  String getSomethingCompletelyDifferent() { return somethingCompletelyDifferent; }

  // <0 - thisObject < anotherObject
  // =0 - thisObject == anotherObject
  // >0 - thisObject > anotherObject
  int compareTo(Foo anotherObject)
  {
    // Delegate comparison to String
    return bar.compareTo(anotherObject.getBar());
  }
  public static void main(Strings[] args)
  {
    ArrayList<Foo> fooList = new ArrayList<Foo>();
    Foo[] fooArray = new Foo[42];
    // populate list and array
    Collections.sort(fooList);
    Arrays.sort(fooArray);
  }
}

Alternatively, a class may implement the interface Comparator:

class FooSort implements Comparable<Foo>
{
  // See above for the meaning of the return valuee
  public int compare(Foo one, Foo two)
  {
    return one.getSomethingCompletelyDifferent().compareTo(
      two.getSomethingCompletelyDifferent());
  }
  public static void main(Strings[] args)
  {
    ArrayList<Foo> fooList = new ArrayList<Foo>();
    Foo[] fooArray = new Foo[42];
    // populate list and array
    Collections.sort(fooList);                 // sort by foo
    Collections.sort(fooList, new FooSort());  // sort by somethingCompletelyDifferent
    Collections.reverse(fooList);              // reverse sort order (only works with List)
    Arrays.sort(fooArray);                     // sort by foo
    Arrays.sort(fooArray, new FooSort());      // sort by somethingCompletelyDifferent

    // Create a comparator object that reverses the natural ordering of Comparable objects,
    // i.e. the order imposed by compareTo() is reversed
    Comparator comp = Collections.reverseOrder();
    Collections.sort(fooList, comp);
    Arrays.sort(fooArray, comp);             // we can also use the comparator for arrays

    // Create a comparator object that reverses the ordering imposed by FooSort (or whatever
    // comparator is passed as an argument)
    comp = Collections.reverseOrder(new FooSort());
    comp = Collections.reverseOrder(comp);   // quite pointless: the same order as FooSort
  }
}

List collections can be searched using the binarySearch() method implemented both in the Arrays and Collections utility classes. The rules for searching are:

A successful search returns the index position within the list where the element was found
An unsuccessful search returns a negative number that indicates the index position where the element would be inserted to keep the collection properly sorted. To get the actual insert position: (-(insert position) - 1) (e.g. -3 is actually the insert position 2)
The collection must be sorted before a search is attempted
The search must be made in the same manner in which the sort was performed, i.e. if a Comparator was used for sorting, the same Comparator must be used for searching, or if the collection was sorted in natural order, the search must also be made in natural order

Examples for Arrays and Collections:

import java.util.Arrays;
import java.util.Collections;

Foo f = new Foo();

// Search arrays
int[] intArray = new int[3];  // Primitive array
Foo[] fooArray = new Foo[3];  // Object array
fooArray[0] = f;
Arrays.binarySearch(intArray, 42);
Arrays.binarySearch(fooArray, f);
Arrays.binarySearch(fooArray, f, new FooSort());  // Use a comparator for searching
// Search lists
List<Foo> fooList = new ArrayList<Foo>();
fooList.add(f);
Collections.binarySearch(fooList, f);

More bits and bytes:

Arrays.equals(intArray, intArray);  // Compare two entire arrays
Arrays.equals(fooArray, fooArray);
Arrays.toString(intArray);          // Create a string representation of an entire array
Arrays.toString(fooArray);

Default sort order rules for strings:

Digits
Spaces
Uppercase characters
Lowercase characters
Uppercase umlaut characters
Lowercase umlaut characters
For instance: "99" -> " f" -> "FF" -> "f " -> "ff" -> "ÄÄ" -> "ää"

`TreeSet` and `TreeMap`

TreeSet<Integer> set = new TreeSet<Integer>();
TreeMap<String, Integer> map = new TreeMap<String, Integer>();
// populate...

Integer i = 42;
set.descendingSet();  // Returns the set in reverse order
set.ceiling(i);       // Returns lowest element >= 42
set.higher(i);        // Returns lowest element >  42
set.floor(i);         // Returns highest element <= 42
set.lower(i);         // Returns highest element <  42
set.pollFirst();      // Returns first set element
set.pollLast();       // Returns last set element
String s = "42";
map.descendingMap();  // See above
map.ceilingKey(s);
map.higherKey(s);
map.floorKey(s);
map.lowerKey(s);
map.pollFirstEntry();
map.pollLastEntry();

Views (aka "backed collections"):

TreeSet<Integer> set = new TreeSet<Integer>();
TreeMap<String, Integer> map = new TreeMap<String, Integer>();
// populate...

boolean inclusive = true;
Integer i1 = 17;
Integer i2 = 42;
SortedSet<Integer> view1;
NavigableSet<Integer> view2;
view1 = set.headSet(i1);             // All elements from the beginning of the set, up to but excluding i1
view2 = set.headSet(i1, inclusive);  // ditto, but including i1
view1 = set.tailSet(i1);             // All elements starting with i1 (*INCLUSIVE*), up to the end of the set
view2 = set.tailSet(i1, inclusive);  // ditto
view1 = set.subSet(i1, i2);          // All elements starting with i1 (inclusive), up to but excluding i2
view2 = set.subSet(i1, inclusive,    // ditto, but including i2
                   i2, inclusive);
String s1 = "17";
String s2 = "42";
SortedMap<String, Integer> view3;
NavigableMap<String, Integer> view4;
view3 = map.headMap(s1);             // See above
view4 = map.headMap(s1, inclusive);
view3 = map.tailMap(s1);
view4 = map.tailMap(s1, inclusive);
view3 = map.subMap(s1, s2);
view4 = map.subMap(s1, inclusive, s2, inclusive);

// Assume set has the following elements: 1, 18, 24, 41, 128
// Assume view1 includes 18, 24, 41, with borders set to 17 and 42 (inclusive)
set.add(16);
set.add(17);
// set: 1, 16, 17, 18, 24, 41, 128
// view1: 17, 18, 24, 41
view1.add(42);
// set: 1, 16, 17, 18, 24, 41, 42, 128
// view1: 17, 18, 24, 41, 42

view1.add(43);        // RUNTIME ERROR! - Element added is outside the view's range

view1.remove(17);
// set: 1, 16, 18, 24, 41, 42, 128
// view1: 18, 24, 41, 42

`PriorityQueue`

PriorityQueue<Integer> pq = new PriorityQueue<Integer>();
pq.offer(3);  // Populate in arbitrary order
pq.offer(1);  // Other queue implementations may impose a size limit, in which case offer() returns
pq.offer(7);  // false if the element cannot be added

pq.size();    // 3
pq.peek();    // 1 (element with the least value in the ordering scheme, i.e. the highest priority)
pq.size();    // still 3
pq.poll();    // 1 (element with the highest priority)
pq.size();    // 2

pq.poll();    // 3
pq.poll();    // 7
pq.size();    // 0 (queue is empty)
pq.poll();    // null (if queue is empty)
pq.peek();    // null (same as poll())

File I/O

Overview

Class	Description	Extends
`java.io.File`	An abstract representation of a file or directory using the file/directory pathname. File/directory contents are handled by reader and writer classes.	Object
`java.io.FileReader`	Reads content from character files. Rather low-level access to single characters or an entire stream. Usually wrapped by higher-level objects such as `BufferedReader`.	Reader
`java.io.BufferedReader`	Makes lower-level classes such as `FileReader` more efficient and convenient to use.	Reader
`java.io.FileInputStream`	?	InputStream
`java.io.ObjectInputStream`	Read data from a stream and de-serialize an object	InputStream
`java.io.FileWriter`	Writes content to character files. Rather low-level access for writing single characters or an entire string. Usually wrapped by higher-level objects such as `BufferedWriter`.	Writer
`java.io.BufferedWriter`	Makes lower-level classes such as `FileWriter` more efficient and convenient to use.	Writer
`java.io.PrintWriter`	Prints formatted representations of objects to a text-output stream.	Writer
`java.io.FileOutputStream`	?	OutputStream
`java.io.ObjectOutputStream`	Serialize an object and write the data to a stream	OutputStream
`java.io.Console`	Java 1.6 convenience class to read from and write to the console.	?

`java.io.File`

import java.io.*;

try
{
  File file = new File("foo");  // The file or directory does not exist yet
  assert(! file.exists());

  boolean success = file.createNewFile();  // Try to create a file
  if (success)
  {
    assert(file.exists());
    assert(file.isFile());
    assert(! file.isDirectory());
    file.renameTo(new File("bar"));
    success = file.delete();
  }
  else
  {
    // do something
  }

  File dir = new File("foo");
  success = dir.mkdir();  // Try to create a directory
  if (success)
  {
    assert(dir.exists());
    assert(! dir.isFile());
    assert(dir.isDirectory());
    dir.renameTo(new File("bar"));

    // Create new file *inside* the directory
    File anotherFile = new File(dir, "foobar");
    anotherFile.createNewFile();

    // Returns both files and subdirectories inside the directory
    String[] contents = dir.list();
    for (String s : contents)
      System.out.println(s); 

    success = dir.delete();          // Will fail e.g. if directory is not empty
  }
  
}
catch(IOException e)
{
  // do stuff
}

`java.io.FileReader`, `java.io.FileWriter` and `java.io.PrintWriter`

import java.io.*;

try
{
  File file1 = new File("foo.txt");          // The files do not exist yet
  File file2 = new File("bar.txt");
  assert(! file1.exists());
  assert(! file2.exists());
  FileWriter fw =  new FileWriter(file1);    // Create the actual files at the same time as the writer objects. Note: The
  PrintWriter pw =  new PrintWriter(file2);  // parent directories must exist!
  assert(file1.exists());
  assert(file2.exists());

  // Very simple FileWriter
  fw.write("howdy\nfolks\n");  // OUCH! - Platform specific line separators
  fw.flush();                  // *ALWAYS* flush before closing
  fw.close();                  // *ALWAYS* close
  // Slightly more sophisticated PrintWriter
  pw.println("howdy");
  pw.println("folks");
  pw.flush();                  // *ALWAYS* flush before closing
  pw.close();                  // *ALWAYS* close

  FileReader fr =  new FileReader(file);
  char[] in = new char[50];           // OUCH! - Have to know the size *before* we read. We could read character
                                      // by character, but this would also not be very satisfying...
  int size = fr.read(in);             // Read the whole file
  System.out.print(size + " ");       // How many bytes have been read?
  for(char c : in)
    System.out.print(c);
  // NOTE! - no flush() required on a reader
  fr.close();                         // *ALWAYS* close
}
catch(IOException e)
{
  // do stuff
}

`java.io.BufferedReader` and `java.io.BufferedWriter`

import java.io.*;

try
{
  File file = new File("foo.txt");                // The file does not exist yet
  PrintWriter pw =  new PrintWriter(file);        // We still need the intermediate PrintWriter
  BufferedWriter bw =  new BufferedWriter(file);  // Wrap it with a high-level BufferedWriter

  // TODO: Is this really how BufferedWriter is used?
  bw.write("howdy");
  bw.newline();
  bw.write("folks");
  bw.newline();
  bw.flush();
  bw.close();

  FileReader fr =  new FileReader(file);        // We still need the intermediate FileReader
  BufferedReader br =  new BufferedReader(fr);  // Wrap it with a high-level BufferedReader
  String s;
  while((s = br.readLine()) != null)   // Read a single line. Note: The string does *NOT* contain the line separator
    System.out.println(s);
  // NOTE! - no flush() required on a reader
  br.close();
}
catch(IOException e)
{
  // do stuff
}

`java.io.Console`

import java.io.*;

Console c = System.console();
if (c == null)                  // Check that the environment actually has a console
  return;

// Get a String
String s = c.readLine("%s", "input: ");
// Write back the String input
c.format("output: %s \n", s); 

// Get a character array, not a String. Reason: A String might be placed in a pool somewhere in memory
// Note: Input is not echoed
char[] pw = c.readPassword("%s", "pw: ");
// Write back the character input
for(char ch: pw)
  c.format("%c ", ch);
c.format("\n");

Serialization

Rules:

Static variables are not included in the serialization process
Inside a serializable class, instance variables marked as transient are initialized to their default values when an object of the class is de-serialized (e.g. primitive values are set to 0, 0.0 etc., reference variables are null)
When an object is constructed by de-serializing it, its construction does not happen by running the normal cycle of constructors and/or init-blocks. Instead it works like this:
- The class hierarchy is examined starting with the root class Object
- Constructors and/or init-blocks are executed up to the last class that is not serializable
- The first class that implements Serializable will be constructed using the de-serialization mechanism
- Example: class A extends class B implements Serializable extends class C extends Object. Here constructors are run for classes Object and C, while from class B upwards no constructors are run. Class A inherits the serialization capability from B.
When serializing arrays and collections, all elements must be serializable, otherwise serialization will fail (probably with a runtime error)

import java.io.*;

class Foo implements Serializable
{
  int i = 42;  // Straightforward: The integer value in this variable gets serialized
}
class Bar  // Is *NOT* serializable
{
  int j = 17;
}
class Foobar implements Serializable
{
  Foo f = new Foo();            // Works only if Foo is also Serializable; if not we get a NotSerializableException!
  transient Bar b = new Bar();  // Exempt Bar from serialization. On de-serialization this will be null.

  // Optional callback method that is invoked on serialization
  private void writeObject(ObjectOutputStream oos)
  {
    try
    {
      // Order of serialization is important!
      oos.defaultWriteObject();  // First perform the normal serialization process
      oos.writeInt(b.j);         // Afterwards serialize additional state
    }
    catch(Exception e)
    {
      // handle exception
    }
  }
  // Optional callback method that is invoked on de-serialization
  private void readObject(ObjectInputStream ois)
  {
    try
    {
      // Order of de-serialization must match order of serialization!
      ois.defaultReadObject();  // First perform the normal de-serialization process
      b = new Bar();
      b.j = ois.readInt();      // Afterwards de-serialize additional state
    }
    catch(Exception e)
    {
      // handle exception
    }
  }
}

class SerializableTester
{
  void doIt()
  {
    try
    {
      Foobar fb = new Foobar();
      FileOutputStream fos = new FileOutputStream("testSer.ser");
      ObjectOutputStream oos = new ObjectOutputStream(fos);
      oos.writeObject(fb);
      oos.close();
    }
    catch (Exception e)
    {
      // do something
    }
    try
    {
      FileInputStream fis = new FileInputStream("testSer.ser");
      ObjectInputStream ois = new ObjectInputStream(fis);
      Foobar fb = (Foobar) ois.readObject();                           // Creates a new object
      ois.close();
    }
    catch (Exception e)
    {
      // do something
    }
  }
}

i18n

`java.util.Locale`

The java.util.Locale class is the basic block of internationalization (i18n). An instance of this class is often combined with other objects that are related to i18n such as java.util.Calendar.

How to create a locale object:

import java.util.*

String language = "de";   // Lower-case 2-letter ISO 639 language code
String country = "CH";    // Upper-case 2-letter ISO 3166 country code
Locale loc1 = new Locale(language);
Locale loc2 = new Locale(language, country);
String s1 = loc2.getDisplayCountry();   // Country name using the default locale (e.g. "Switzerland")
String s2 = loc2.getDisplayLanguage();  // Language name using the default locale (e.g. "German")
s1 = loc2.getDisplayCountry(loc2);      // "Schweiz"
s2 = loc2.getDisplayLanguage(loc2);     // "Deutsch"

// Working with the default locale
Locale defaultLocale = Locale.getDefault();
Locale.setDefault(loc2);

Dates and calendars

Important notes:

java.util.Date represents a single date/time. Internally it stores a single primitive long value. The value holds the number of milliseconds since the epoch (GMT 01.01.1970-00:00:00.000).
Large parts of the java.util.Date class API are deprecated. The class is still used to bridge between java.util.Calendar and java.text.DateFormat
java.util.Calendar is more "modern" than Date

Date & time operations, quick & dirty style:

import java.util.*

Date now = new Date();             // Get current date/time
Date d = new Date(1000000L);       // Get date/time 1 million milliseconds after the epoch
d.setTime(d.getTime() + 3600000);  // Add 1 hour
String s = d.toString();

Using Calendar:

import java.util.*

Date d = new Date(HUGE_NUMBER);         // Assume a number that refers to 07.12.2009, 17:00:00
Calendar c = Calendar.getInstance();    // Invoke factory method to get an instance that refers to NOW
                                        // and uses the default time zone and locale
c.setTime(d);                           // Set the calendar to a specific time (no longer NOW)
int dow = c.get(Calendar.DAY_OF_WEEK);  // Get value of calendar field "day of week"
c.add(Calendar.MONTH, 3);               // Add 3 months, including rollover of year; c now refers to 07.03.2010, 17:00:00
c.roll(Calendar.MONTH, 10);             // Add 10 months, without rollover of year; c now refers to 07.01.2010, 17:00:00
d = c.getTime();                        // Get a Date object that refers to the calendar's time value

Formatting dates & times for a specific locale:

import java.util.*
import java.text.*

Locale loc = new Locale(...);
int style = DateFormat.LONG;
DateFormat df = DateFormat.getDateInstance(style, loc);
Calendar c = Calendar.getInstance();    // Calendar object refers to NOW and uses default time zone and locale
Date d = c.getTime();
String s = df.format(d);                // Convert into a string that is formatted according to the proper style and locale

try
{
  d = df.parse(s);                      // Convert from string. We *LOSE* time information here because the
                                        // DateFormat object was created using getDateInstance()
  
  DateFormat df_withtime = DateFormat.getDateTimeInstance(style, loc);
  d = df_withtime.parse(s);             // Again, convert from string, but this time *RETAIN* time information
}
catch(ParseException e) { ... }

Numbers and Currency

Rather than DateFormat, we use NumberFormat for working with numbers:

import java.util.*
import java.text.*

float f1 = 123.456789f;
Locale loc = new Locale("de", "CH");
NumberFormat nf1 = NumberFormat.getInstance(loc);
NumberFormat nf2 = NumberFormat.getCurrencyInstance(loc);
String s1 = nf1.format(f1);  // "123.457", rounded to 3 fraction digits (the default for this locale)
String s2 = nf2.format(f1);  // "SFr. 123.46", rounded to 2 fraction digits (the currency default for this locale)
nf1.setMaximumFractionDigits(5);
s1 = nf1.format(f1);         // "123.45679", now rounded to 5 fraction digits

try
{
  nf1.setMaximumFractionDigits(2);
  Number n = nf1.parse(s1);            // Convert from string; n is 123.45679, because setMaximumFractionDigits() only has
                                       // an effect for formatting, not for parsing
  nf1.setParseIntegerOnly(true); 
  n = nf1.parse(s1);                   // n is now 123; this time all fractions are lost because setParseIntegerOnly() does
                                       // influence parsing (but not formatting)
}
catch(ParseException e) { ... }

Regexp, tokenizing, and formatting

Regexp

A few regexp expressions that I didn't know about yet:

\d: Any numeric digit. An alternative is [0-9]
\s: Any whitespace character
\w: Any word character (letters, digits and "_")
\b: Backspace
?, *, +: Greedy as usual
??, *?, +?: Non-greedy (= reluctant)

import java.util.regex.*

Pattern p1 = Pattern.compile(".*?xx");  // The pattern; note: uses non-greedy operator
Matcher m1 = p.matcher("yyxxxyxx");     // The string to match
while (m1.find())
{
  System.out.println(m1.start() + " " m1.group());   // Results in two lines: "0 yyxx" and "4 xyxx"
}

Tokenizing

Very basic tokenizing uses String.split():

String s = "ab,cd5b,6x,,z4";
String delimiter = ",";
String[] tokens = s.split(delimiter);  // Results in 5 tokens: "ab", "cd5b", "6x", "" (empty string), "z4"

java.util.Scanner is the mammoth tokenizer. It has the following advantages:

Possible sources: Files, streams, or strings
Tokenizing is performed within a loop so that you can exit the process at any point
Tokens can be converted to their appropriate primitive types automatically

An example:

String input = "1 true 34 hi";

Scanner s1 = new Scanner(input);   // Use default delimiter, which is whitespace
// hasNext(), hasNextInt(), etc. all test 1) if there is a next token, and 2) if the token matches
// the requested type. The methods themselves do not change the input stream.
while (s1.hasNext())
{
  // next(), nextInt(), etc. all get the next token. If there is no next token, or if it is not of
  // the requested type (e.g. an int), the function throws an exception
  String token = s1.next();        // Results in 4 tokens: "1", "true", "34", "hi"
} 

Scanner s2 = new Scanner(input);
s2.useDelimiter("\\s");            // Explicitly set whitespace as delimiter. Note: We could also specify a compiled regex Pattern.
while (s2.hasNext())
{ 
  if (s2.hasNextInt())
  {
    int i = s2.nextInt();          // Two tokens: "1", "34"
  }
  else if (s2.hasNextBoolean())
  {
    boolean b = s2.nextBoolean();  // One token: "true"
  }
  else
  {
    String s = s2.next();          // One token: "hi"
  } 
}

Formatting

Notes:

This chapter is about the format() and printf() methods in the java.io.PrintStream class
Both methods behave exactly the same way
They use the java.util.Formatter class behind the scenes; if in doubt, the class API has all the details
Specs for a format string

%[arg_index$][flags][width][.precision]conversion char

Flags
- "-" = Left justify
- "+" = Include the sign
- "0" = Pad with zeroes
- "," = Use locale-specific grouping separators (e.g. the "." for Swiss currency)
- "(" = Enclose negative numbers in parantheses

Examples:

System.out.printf("%2$d + %1$d", 123, 456);  // Result: "456 + 123"
System.out.format("%d", 12.3);               // ERROR! - Runtime exception

Threads

Basic stuff

Initial notes:

A thread in Java has two meanings:
1. An instance of class java.lang.Thread
2. A thread of execution
The thread that runs the main() method is the main thread
Each thread has its own call stack; each call stack lives in its own thread
There are two types of threads:
1. User threads: When all user threads have finished running, the JVM exits the application, even if one or more daemon threads are still running
2. Daemon threads: Threads of this type do not have an influence on when the JVM exits the application
A thread begins execution in its run() method (no arguments, return type void)
The run() method must be placed into a class that does one of the following:
1. Extend the class java.lang.Thread. This is not the recommended approach, unless the application needs more specialized thread-specific behaviour
2. Implement the interface java.lang.Runnable. This is the recommended approach; the implementing class can be more lightweight, and it also leaves the class free to extend something else
Thread state can be queried using Thread.getState(); possible values from the enum Thread.State are
- NEW: Thread object has been created but the thread has not been started yet. Thread is not yet alive.
- RUNNABLE: Thread is executing, or is ready to execute. Thread is alive.
- BLOCKED: Thread is blocked because a resource is not available (e.g. reading from a stream).
- WAITING
- TIMED_WAITING
- TERMINATED: Thread's target run() method has finished. Thread is dead, i.e. not alive anymore.
Every object in Java has a built-in lock that is acquired when a thread starts to execute code that is marked as synchronized. The built-in lock is recursive, i.e. calling a synchronized method from another synchronized method does not result in a deadlock

Examples:

class MyThread extends Thread
{
  public void run()
  {
    System.out.println("Job running in MyThread");
    System.out.println("Job is run by Thread " + Thread.currentThread().getName());
  }
}

class MyRunnable implements Runnable
{
  public void run()
  {
    System.out.println("Job running in MyRunnable");
    System.out.println("Job is run by Thread " + Thread.currentThread().getName());
  }
}

class Invoker
{
  void invoke()
  {
    Thread t1 = new MyThread();          // Thread is not yet running
    assert(! t1.isAlive());              // Thread is not yet alive
    Thread.State s = t1.getState();
    assert(s == Thread.State.NEW);       // Thread state is "new"

    t1.start();                          // Start the thread; eventually run() will be called in a different execution thread
    assert(t1.isAlive());                // Thread is alive from the moment onwards when start() is invoked
    t1.start();                          // RUNTIME ERROR! - Thread cannot be started a second time
    // wait until thread is finished,
    // i.e. until the run() method of
    // the thread's target has finished
    s = t1.getState();
    assert(s == Thread.State.TERMINATED);  // Thread final state is "terminated"
    t1.start();                            // RUNTIME ERROR! - Thread cannot be started even after it has finished running


    Thread t2 = new MyThread("foo");    // Give the thread a name

    Runnable r1 = new MyRunnable();
    Thread t3 = new Thread(r1);         // Make the Runnable the *TARGET* of the thread
    t3.start();                         // Thread invokes run() on the Runnable
    Thread t4 = new Thread(r1);         
    t4.start();                         // Run the same job a second time in a different thread
    Thread t5 = new Thread(t2);         // Silly but legal: Thread implements Runnable, therefore we can pass a Thread instance to a Thread constructor
    t5.start();
    Thread t6 = new Thread(r1, "bar");  // Give the thread a name
    t6.setName("no, its foo");          // Change the name
    t6.start();

    t6.run();                           // Invokes r1.run() because that's how Thread.run() is implemented; invocation does *NOT* happen in a new thread context
  }
}

Mechanisms to influence thread scheduling

class MyRunnable implements Runnable
{
  public void run()
  {
    try
    {
      int milliseconds = 1000;
      Thread.sleep(milliseconds);  // Sleep *AT LEAST* this long; thread may *NOT* run for some time even after the specified time has expired

      Thread.yield();              // Voluntarily give up control so that another thread *MAY* get a chance at running; this is *NOT* guaranteed
    }
    catch (InterruptedException ex)  // This gets hit if sleep() is interrupted
    {
    }
  }
}

class Invoker
{
  void invoke()
  {
    Runnable r1 = new MyRunnable();
    Thread t1 = new Thread(r1);
    t1.setPriority(7);                     // Usually the priority is between 1 and 10 (higher numbers = higher priority), but this depends on the JVM
    t1.setPriority(Thread.MIN_PRIORITY);   // 1
    t1.setPriority(Thread.NORM_PRIORITY);  // 5
    t1.setPriority(Thread.MAX_PRIORITY);   // 10
    t1.start();

    try
    {
      int milliseconds = 1000;
      t1.join(milliseconds);     // Wait until t1 has finished running (i.e. becomes dead), then go on with the current thread; wake up earlier
                                 // if t1 takes longer than the specified amount of time to finish
      t1.join();                 // Wait unconditionally
    }
    catch (InterruptedException ex)  // This gets hit if join() is interrupted
    {
    }
  }
}

Locks and other fancy pancies

Usage of synchronized:

class Account
{
  private int balance = 50;
  public int getBalance() { return balance; }
  public void withdraw(int amount) { balance -= amount; }
}
class MyRunnable implements Runnable
{
  private Account a = new Account();
  public void run()
  {
    // do stuff
  }
  // Marking a method as synchronized causes the object's built-in lock to be acquired
  private synchronized void makeWithdrawal(int amount)
  {
    if (a.getBalance() >= amount)
    {
      a.withdraw(amount);
    }
  }
  private void makeWithdrawal2(int amount)
  {
    // Synchronize a code block instead of an entire method
    synchronized(this)
    {
      if (a.getBalance() >= amount)
      {
        a.withdraw(amount);
      }
    }
  }
}

Usage of wait() and notify():

class Foo
{
  public static void main(String [] args)
  {
    Runnable r = new MyRunnable();
    Thread b = new Thread(r);
    b.start();

    synchronized(r)  // Acquire lock *BEFORE* we enter the wait condition
    {
      try
      {
        System.out.println("Waiting for runnable to complete...");
        r.wait();  // Enter wait condition *AND* release the lock; the thread wakes up when it gets a notification *AND* can re-acquire the lock

        int milliseconds = 1000;
        r.wait(milliseconds);     // Doesn't make sense here, just for illustration purposes that we can also use a timeout
      }
      catch (InterruptedException e) {}
      System.out.println("Total is: " + r.total);
    }

    r.wait();  // RUNTIME ERROR! - We don't have the lock on object r
  }
}

class MyRunnable implements Runnable
{
  int total;

  public void run()
  {
    synchronized(this)
    {
      for (int i = 0; i < 100; i++)
      {
        total += i;
      }
      // NOTE: Both notify() and notifyAll() require a lock on the object on which they are invoked !!!
      notify();     // Notify *ONE* of the waiting threads; that thread will then try to wake up but will be blocked because we still have the lock
      notifyAll();  // Notify *ALL* waiting threads
    }
    // *NOW* one of the notified but blocked threads will wake up because we have released our lock
  }
}

Mixed pickles

System properties

System properties can be set, for instance, when the Java program is launched:

java -DmyProp=myValue Foo

A few examples how to work with system properties:

import java.util.Properties;

Properties p = System.getProperties();
String value1 = p.getProperty("myProp");        // Returns "myValue" (assuming the property has been set when the Java program was launched)
String value2 = p.getProperty("yourProp");      // Returns null
value2 = p.getProperty("yourProp", "default");  // Returns the default value "default"
p.setProperty("myProp", "yourValue"); 
p.list(System.out);

Garbage collection

Rules:

An object is eligible for garbage collection (GC) when no live thread can access it
There is no guarantee when, or if, an object eligible for GC is actually collected
There is no guarantee when GC is run; this wholly depends on the implementation of the JVM
GC cannot be forced. A request to run GC can be submitted to the JVM, but there is no guarantee when, or if, the request is granted

To make an object unreachable to live threads, hence make it eligible for GC:

Set variables that reference the object to some other value, e.g. set them to null, or to a reference to a different object
Isolated cross-references are usually discovered when GC is run

JavaBeans API

JavaBeans are classes that conform to a certain API. Among the rules are

JavaBeans have properties
- Properties are accessed using getter and setter methods (I like to call these accessors)
- The property name is inferred from the name of the accessors. There is no need for having an actual instance variable for a property
- The getter must be prefixed with "is" or "get" if the property is a boolean. The getter must always be prefixed with "get" if the property is not a boolean
- The setter must always be prefixed with "set"
- Setter method signatures must be marked public, with a void return type and an argument that represents the property type
- Getter method signatures must be marked public, take no arguments, and have a return type that matches the argument type of the setter method for that property
JavaBeans have events
- For each event type it is possible to register one or more so-called listeners; a listener is what I would call an observer: an object that is notified when the event occurs
- Methods used to manage event listeners must be prefixed with "add" or "remove", and end with the listener type. Note that the type must always end with the word "Listener"
- For instance: addFooListener and removeFooListener
- Both methods take exactly one argument: The object that should be registered or unregistered as a listener. The argument must have the type that is embedded in the method name, e.g. FooListener in the example above
- It is not yet clear what methods are invoked on a listener object to notify it that an event occurred

LearningJavaAPI

Contents

About this page

The root class: `java.lang.Object`

Strings

java.lang.String

`java.lang.StringBuffer` and `java.lang.StringBuilder`

Generics

Collections

Overview

Iterators

Converting between Lists and Arrays

Sorting and searching

`TreeSet` and `TreeMap`

`PriorityQueue`

File I/O

Overview

`java.io.File`

`java.io.FileReader`, `java.io.FileWriter` and `java.io.PrintWriter`

`java.io.BufferedReader` and `java.io.BufferedWriter`

`java.io.Console`

Serialization

i18n

`java.util.Locale`

Dates and calendars

Numbers and Currency

Regexp, tokenizing, and formatting

Regexp

Tokenizing

Formatting

Threads

Basic stuff

Mechanisms to influence thread scheduling

Locks and other fancy pancies

Mixed pickles

System properties

Garbage collection

JavaBeans API

Navigation menu

LearningJavaAPI

About this page

The root class: java.lang.Object

Strings

java.lang.String

java.lang.StringBuffer and java.lang.StringBuilder

Generics

Collections

Overview

Iterators

Converting between Lists and Arrays

Sorting and searching

TreeSet and TreeMap

PriorityQueue

File I/O

Overview

java.io.File

java.io.FileReader, java.io.FileWriter and java.io.PrintWriter

java.io.BufferedReader and java.io.BufferedWriter

java.io.Console

Serialization

i18n

java.util.Locale

Dates and calendars

Numbers and Currency

Regexp, tokenizing, and formatting

Regexp

Tokenizing

Formatting

Threads

Basic stuff

Mechanisms to influence thread scheduling

Locks and other fancy pancies

Mixed pickles

System properties

Garbage collection

JavaBeans API

Navigation menu

Search

The root class: `java.lang.Object`

`java.lang.StringBuffer` and `java.lang.StringBuilder`

`TreeSet` and `TreeMap`

`PriorityQueue`

`java.io.File`

`java.io.FileReader`, `java.io.FileWriter` and `java.io.PrintWriter`

`java.io.BufferedReader` and `java.io.BufferedWriter`

`java.io.Console`

`java.util.Locale`