The Observer in the Physical World

The idea behind the observer is like a subscription. Do you have a newspaper or magazine subscription? Have you signed up for cell phone texts from your favorite band when they have new tour dates? The act of you signing up with the newspaper, the magazine, or the band, is you saying you want a subscription, or that you want to become an observer. When the subject (newspaper, magazine, band) has something new to share (on a schedule or not) they run down their subscriber list, and notify the observers by mail, or text.

The Observer in the Software World

On the software side, the idea is the same. Your subject needs to provide a way to take subscriptions, hold a list of observers, and when a particular state changes, notify them. There is usually a couple of methods on the subject that takes in an interface that is used for getting on or off the subscription list. On this interface is also the “call back” method. This is the method that the subject will execute when it wants to inform the observers of state changes.

Do you have a picture?

 

Here is a class diagram for our first example. We have two classes and an interface. The interface, NumberObserver is the piece that connects the subject and the observer together. The NumberHolder class has methods to add and remove our observer from an internal list. The NumberDisplayer sets this object and the notify method on NumberHolder. The way it was implemented here was that NumberDisplayer implemented the interface. This is not the only way to do it. NumberDisplayer could create an inner class, or there could be an external class that implements the NumberObserver interface. It doesn’t matter. All that does matter is that NumberDisplayer passes a NumberObserver object to NumberHolder that implements the notifyNewNumber method. When NumberHolder changes it’s number, it then notifies all the observers by looping over the list it has of observers and executing the notifyNewNumber method on each one.

The NumberObserver is very basic. Just one method is defined here. The value that will be sent by the subject is the new number.

public interface NumberObserver {
   public void notifyNewNumber(int pNewValue);
   }
}

The NumberHolder doesn’t have much going on either. Most of the code is just to take care of the observers. Note the add, remove, and update observer methods.

public class NumberHolder {
   private int number;
   private List observerList;

   public NumberHolder() {
      number = 10;
      observerList = new ArrayList();
   }

   public void setNumber(int pNumber) {
      System.out.println("Number set to " + pNumber);
      number = pNumber;
      updateObservers();
   }

   public void addObserver(NumberObserver pObserver) {
      System.out.println("Adding observer:" + pObserver);
      observerList.add(pObserver);
   }

   public void removeObserver(NumberObserver pObserver) {
      System.out.println("Removing observer:" + pObserver);
      observerList.remove(pObserver);
   }

   private void updateObservers() {
      for (NumberObserver aObserver : observerList) {
         aObserver.notifyNewNumber(number);
      }
   }
}

And finally, the NumberDisplayer class that implements the NumberObserver interface.

public class NumberDisplayer implements NumberObserver {
   private String name;

   public NumberDisplayer(String pName) {
      name = pName;
   }

   public void notifyNewNumber(int pNewValue) {
      System.out.println(name + " is now displaying " + pNewValue);
   }
}

NumberHolderTest puts these three classes together. It creates several NumberDisplayer classes and adds and removes objects from the NumberHolder as well as updating the value. Run this to see the observer at work.

public class NumberHolderTest {
   public static void main(String[] args) {
      NumberHolder aNumberHolder = new NumberHolder();

      // we can set the number at any time. Nothing happens because we don't
      // have any observers registered.
      aNumberHolder.setNumber(10);

      // Each NumberDisplayer will register with the NumberHolder
      NumberDisplayer aObserverAndDisplayerOne = new NumberDisplayer("One");
      aNumberHolder.addObserver(aObserverAndDisplayerOne);

      NumberDisplayer aObserverAndDisplayerTwo = new NumberDisplayer("Two");
      aNumberHolder.addObserver(aObserverAndDisplayerTwo);

      NumberDisplayer aObserverAndDisplayerThree = new NumberDisplayer("Three");
      aNumberHolder.addObserver(aObserverAndDisplayerThree);

      // Each NumberDisplayer should get notified of the change
      aNumberHolder.setNumber(20);

      // Remove two observers
      aNumberHolder.removeObserver(aObserverAndDisplayerOne);
      aNumberHolder.removeObserver(aObserverAndDisplayerTwo);

      // Now only one observer is left
      aNumberHolder.setNumber(30);
   }
}

The main idea here is that we can keep the two objects loosely coupled, with the one interface joining them together. The way this is done can vary a bit. In this particular case we have chosen to pass the new number. You could pass a different interface that exposed methods on the subject. You could just have a method that doesn’t pass anything if just need to know that something happened.

Let’s look at another example, this time using our Animal classes.

Defining the problem

We have a zoo. A zoo contains many cages, each cage contains several animals. The zoo keepers would like to have an up-to-date tally of all the animals in the zoo. Every time animals are added or removed from the cages, they want to know the totals. Let’s look at this without the observer pattern first.

No Observer Pattern

public class Cage1 {

   // List to hold our animals
   private List animalList;

   public Cage1() {
      animalList = new ArrayList();
   }

   public void insertAnimal(T pAnimal) {
      animalList.add(pAnimal);
      System.out.println("\n" + pAnimal.getName() + " " + pAnimal.getType()	+ " is added to the cage.");
   }

   public void removeAnimal(T pAnimal) {
      animalList.remove(pAnimal);
      System.out.println("\n" + pAnimal.getName() + " " + pAnimal.getType()	+ " is removed from the cage.");
   }

   public void clearCage() {
      animalList.clear();
   }

   public List getAnimals() {
      return animalList;
   }
}

public class Zoo1 {
   private List> cages;

   public Zoo1() {
      cages = new ArrayList>();
   }

   public void addCage(Cage1 pCage) {
      cages.add(pCage);
   }

   public void removeCage(Cage1 pCage) {
      cages.remove(pCage);
   }

   public void doCageUpdated() {
      Map aAnimalCounts = getAnimalCounts();
      displayAnimalCounts(aAnimalCounts);
   }

   public Map getAnimalCounts() {
      Map aAnimalCounts = new HashMap();
      for (Cage1 aCage : cages) {
         List aAnimalList = aCage.getAnimals();
         int aCount = aAnimalList.size();
         if (aCount > 0) {
            String aType = aAnimalList.get(0).getType();
            Integer aTypeCount = aAnimalCounts.get(aType);
            if (aTypeCount == null) {
               aTypeCount = new Integer(aCount);
            } else {
               aTypeCount = new Integer(aTypeCount.intValue() + aCount);
            }
            aAnimalCounts.put(aType, aTypeCount);
         }
      }
      return aAnimalCounts;
}

   public void displayAnimalCounts(Map animalCounts) {

      Set aAnimalSet = animalCounts.keySet();
      if (aAnimalSet == null || aAnimalSet.isEmpty()) {
         System.out.println("\nZoo is currently empty.");
      } else {
         System.out.println("\nCurrent zoo animal counts:");
      }
      for (String aType : aAnimalSet) {
         Integer aTypeCount = animalCounts.get(aType);
         System.out.println("There are " + aTypeCount.intValue() + " of type " + aType);
      }
   }
}

See Cage1.java. Pretty simple. Just a simple list, and the methods to support getting data in and out of the list. Now look at Zoo1.java. This class contains the cages in a List. It also has the methods that can look at all the cages and create the totals for each animal type.

There is also a method doCageUpdated that must be called everytime an animal is added to a cage. The way we have this set up so far, there is no way for the zoo to know when an animal is added to a cage. A cage knows where an animal is added, but the cage doesn’t know about the zoo. It is contained within the zoo, but there is no coupling between the cage, and the zoo. We could insert a reverence for the zoo into the cage when the cages are added to the zoo, but we try to avoid this circular coupling.

public class ZooTest1 {
   public static void main(String[] args) {

      Zoo1 aZoo = new Zoo1();

      Cage1 aBirdCage = new Cage1();
      aZoo.addCage(aBirdCage);

      aBirdCage.insertAnimal(new Bird());
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();

      aBirdCage.insertAnimal(new Bird());
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();

      Cage1 aMammalCage = new Cage1();
      aZoo.addCage(aMammalCage);
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();

      Mammal aFred = new Mammal("Fred");
      aMammalCage.insertAnimal(aFred);
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();

      Cage1 aDogCage = new Cage1();
      aZoo.addCage(aDogCage);

      aDogCage.insertAnimal(new Mammal("Rover"));
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();

      aDogCage.insertAnimal(new Mammal("Spot"));
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();

      aMammalCage.removeAnimal(aFred);
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();

      aBirdCage.clearCage();
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();

      aDogCage.clearCage();
      // tell zoo to check counts and update display
      aZoo.doCageUpdated();
   }
}

What we are forced to do, and must rely on, is that the developer writing the program will call the doCageUpdated() method on the zoo object every time an animal is added to a cage. See ZooTest1.java. This is not good programming practice.

Implementing the Observer Pattern

public class Cage2 {
   // List to hold our animals
   private List animalList;

   // List to hold our observers
   private List cageObservers;

   public Cage2() {
      animalList = new ArrayList();
      cageObservers = new ArrayList();
   }

   public void insertAnimal(T pAnimal) {
      animalList.add(pAnimal);
      System.out.println("\n" + pAnimal.getName() + " " + pAnimal.getType()	+ " is added to the cage.");
      notifyObservers();
   }

   public void removeAnimal(T pAnimal) {
      animalList.remove(pAnimal);
      System.out.println("\n" + pAnimal.getName() + " " + pAnimal.getType()	+ " is removed from the cage.");
      notifyObservers();
   }

   public void clearCage() {
      animalList.clear();
      notifyObservers();
   }

   public List getAnimals() {
      return animalList;
   }

   public void addCageObserver(CageObserver pCageObserver) {
      cageObservers.add(pCageObserver);
   }

   public void removeCageObserver(CageObserver pCageObserver) {
      cageObservers.remove(pCageObserver);
   }

   private void notifyObservers() {
      for (CageObserver aCageObserver : cageObservers) {
         aCageObserver.doCageUpdated();
      }
   }
}

public class Zoo2 implements CageObserver {
   private List> cages;

   public Zoo2() {
      cages = new ArrayList>();
   }

   public void addCage(Cage2 pCage) {
      pCage.addCageObserver(this);
      cages.add(pCage);
   }

   public void removeCage(Cage2 pCage) {
      pCage.removeCageObserver(this);
      cages.remove(pCage);
   }

   public void doCageUpdated() {
      Map aAnimalCounts = getAnimalCounts();
      displayAnimalCounts(aAnimalCounts);
   }

   public Map getAnimalCounts() {
      Map aAnimalCounts = new HashMap();
      for (Cage2 aCage : cages) {
         List aAnimalList = aCage.getAnimals();
         int aCount = aAnimalList.size();
         if (aCount > 0) {
            String aType = aAnimalList.get(0).getType();
            Integer aTypeCount = aAnimalCounts.get(aType);
            if (aTypeCount == null) {
               aTypeCount = new Integer(aCount);
            } else {
               aTypeCount = new Integer(aTypeCount.intValue() + aCount);
            }
            aAnimalCounts.put(aType, aTypeCount);
         }
      }
      return aAnimalCounts;
   }

   public void displayAnimalCounts(Map animalCounts) {

      Set aAnimalSet = animalCounts.keySet();
      if (aAnimalSet == null || aAnimalSet.isEmpty()) {
         System.out.println("\nZoo is currently empty.");
      } else {
         System.out.println("\nCurrent zoo animal counts:");
      }
      for (String aType : aAnimalSet) {
         Integer aTypeCount = animalCounts.get(aType);
         System.out.println("There are " + aTypeCount.intValue() + " of type " + aType);
      }
   }
}

A better way is to implement the observer pattern. Look at Cage2.java, Zoo2.java, and ZooTest2.java. Looking at Cage2.java you can see that the Cage2 class now has another list, the list of CageObserver’s. Now, when an animal is added to the cage, the cage informs anyone that is listening that the cage count has changed. In our case, we just send a message that the cage is updated, but in a different design you may have passed the Cage2 object its self, or an interface, or another object that indicated the type of event (add, remove, clear) and the number of animals that it evolved. That is all up to your design. They would all fit the observer pattern.

public class ZooTest2 {
   public static void main(String[] args) {

      Zoo2 aZoo = new Zoo2();

      Cage2 aBirdCage = new Cage2();
      aZoo.addCage(aBirdCage);

      aBirdCage.insertAnimal(new Bird());
      aBirdCage.insertAnimal(new Bird());

      Cage2 aMammalCage = new Cage2();
      aZoo.addCage(aMammalCage);

      Mammal aFred = new Mammal("Fred");
      aMammalCage.insertAnimal(aFred);

      Cage2 aDogCage = new Cage2();
      aZoo.addCage(aDogCage);

      aDogCage.insertAnimal(new Mammal("Rover"));
      aDogCage.insertAnimal(new Mammal("Spot"));

      aMammalCage.removeAnimal(aFred);

      aBirdCage.clearCage();
      aDogCage.clearCage();
   }
}

Now look at the ZooTest2 class. Much better. No longer do we have to tell the zoo to display the data, it is done automatically. This may not seem that worthwhile here, but the process for adding cages to the zoo may not be connected with the process of adding animals to anyone cage. Keeping these things separate allows for more flexibility.

Swinging the Observer Pattern

We have already used the observer pattern in a previous lesson. Way back when we covered classes we looked at creating a Gui and implemented a WindowListener. We didn’t discuss it back then, but we were implementing the Observer Pattern. That’s right, every time we register an action listener of some sort in AWT, or Swing, we are registering an Observer with a Subject. Go back and look at Gui1 to Gui4. These are 4 different ways of creating the Observing class. As an example, here is Gui3.java.

public class Gui3 extends JFrame {
   public Gui3() {
      setTitle("Gui3");
      setSize(300, 300);
      addWindowListener(new WindowAdapter() {
         public void windowClosing(WindowEvent e) {
            System.out.println("Closeing Gui3");
            System.exit(0);
         }
      });
   }

   public static void main(String[] args) {
      JFrame aFrame = new Gui3();
      aFrame.setVisible(true);
   }
}

So keep this in mind. If you have written a GUI program, it is almost certain that you have implemented the Observer pattern. Swing depends heavily on it. That is how your visual components can react when users press buttons, move focus, and close windows. This way, you don’t have to create a loop of code that checks for a mouse click, and then determine which button the mouse was over, and then directs the program flow to specific code handling sections. You simple register with each button to be informed when it is clicked. And remember, several objects can register to listen at the same time. Because of this, Java even has a solution you can implement, called the EventListenerList. You can use this list in your classes to implement event listeners. Why reinvent it your self if it is already provided. This class supplies the underlying list, and methods to add and remove EventListeners to and from the List. It doesn’t supply a method to notify listeners in the list, but it does provide a method (getListeners()) that can take in a class type parameter so that you can ask the list to return just the listeners of a particular type. If you find you need to implement an observer event list, check this class out.

The Decorator in the Physical World

The idea behind decorating things in the real world is pretty much how it sounds. We wrap an object with new functionality, while keeping the old functionality. How about a camera in a waterproof housing? When closed up, we have added the functionality of waterproofing, but we still provide a way to press the buttons and turn the dials so that the camera can be operated.

The Decorator in the Software World

On the software side, the idea is the same. It is usually used when we have one object that we like how it functions, but we want to augment the behavior for a different situation. Done correctly, we can keep inserting one object inside another adding functionality at every step.

What do we need to create a Decorator?

We need to create a class (our Decorator) that contains the class we want to decorate. We usually get this class into the Decorator using a constructor. Our Decorator needs to extend or implement the class or interface that contains the functionality we want to Decorate. Then when one of the methods of the decorated class is called, we call it before or after adding our own functionality.

Ummm, Example?

Lets use our Animals again. We are going to get a little bit emotional, or at least our animals are. Have you ever met people, who no matter what you ask them, has to tell you their emotional state? We will create an animal decorator that does just that. Every time we ask them to move() or speak() they will still move and speak, but they will also tell us their emotional state.

So, how do we accomplish this? Just as we could have done when we started looking at the Adapter, we could just go into the code for Animal or BaseAnimal and add new code to store a feeling, and put some getters and setters on it. But, our Animal code works, and not every animal likes to tell everyone they meet what they are feeling.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

public abstract class EmotionDecorator extends BaseAnimal {
 
   private Animal decoratedAnimal;
 
   public EmotionDecorator(Animal pDecoratedAnimal) {
      decoratedAnimal = pDecoratedAnimal;
   }
 
   public String getType() {
      return decoratedAnimal.getType();
   }
 
   public void move() {
      decoratedAnimal.move();
      showEmotion();
   }
 
   public void speak() {
      decoratedAnimal.speak();
      showEmotion();
   }
 
   private void showEmotion() {
      System.out.println("(Who by the way, is very " + getEmotion() + ".)");
   }
 
   public abstract String getEmotion();
}

So, we start by extending BaseAnimal. This means that we get all the functionality that is in BaseAnimal, and means that other objects can just treat us like an Animal. (BaseAnimal implements the Animal interface). We have a constructor that takes in an Animal to be decorated. Not every method is implemented by BaseAnimal however, so we provide the pass thru method for getType() and decorate move() and speak().

The getType() method does not add anything, but we still need to provide this pass thru method, because we want the decorated Animal’s type to be returned if someone asks us.

The move() and speak() methods get decorated. We first call the method on our decorated Animal, then we call showEmotion(). This does the same thing for both, it prints out how the animal is feeling. It gets its emotion from an abstract method. This allows us to push down the hierarchy to some small concrete classes just the specific behavior for each emotion. This does mean a different emotion class for each emotion, but it can be used for all animals. As an exercise, when this is over, try to create a EmotionDecorator that takes in a parameter for the emotion type instead.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public class HappyDecorator extends EmotionDecorator {
 
   public HappyDecorator(Animal pDecoratedAnimal) {
      super(pDecoratedAnimal);
   }
 
   public String getEmotion() {
      return "happy";
   }
}
 
Nothing to it. It just creates the constructor so our decorated animal is set up, and provides the correct emotion.
 
Lets see an example of how we construct this decorator now.
<pre lang="Java">public static void main(String[] args) {
 
   Animal aBird = new Bird();
   Animal aHappyBird = new HappyDecorator(aBird);
 
   aBird.move();
   aHappyBird.move();
}

Here we create a Bird and we create a HappyDecorator that we put the bird into. If we call move() on aBird, we just get the move() method on bird. If we call the move() method on aHappyBird, we get the Bird.move() method called and the decoration.

We don’t have to create and hold an instance of Bird. We could just add them by doing a new inside the constructor of our decorator. We can even chain our emotions together to get one confused bird.

1
2
3
4
5
6
7
8
9
10

public static void main(String[] args) {
 
   Animal aAngryBird = new AngryDecorator(new Bird());
   Animal aHappyBird = new HappyDecorator(new Bird());
   Animal aConfusedBird = new AngryDecorator(new HappyDecorator(new Bird()));
 
   aAngryBird.move();
   aHappyBird.move();
   aConfusedBird.move();
}

And just so you can see that we can decorate any of our Animals:

1
2
3
4
5
6
7
8
9
10

public static void main(String[] args) {
 
   Animal aAngryBird = new AngryDecorator(new Bird());
   Animal aHappyFish = new HappyDecorator(new Fish());
   Animal aConfusedMammal = new AngryDecorator(new HappyDecorator(new Mammal()));
 
   aAngryBird.move();
   aHappyFish.move();
   aConfusedMammal.move();
}

The chaining thing doesn’t look all that useful in this context, but it can be a great tool. Lets take a quick look at another example, the MovingDecorator. This is almost the same implementation as the EmotionDecorator, but we are only going to decorate the move() method. Lets throw a new twist in there too. Often with a Decorator, there is some sort of setup or initialization to do, so lets allow a way to init this decorator with a value, and have an abstract method to provide the values expected type.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

public abstract class MovingDecorator extends BaseAnimal {
 
   private Animal decoratedAnimal;
   private int movementAmount;
 
   public MovingDecorator(Animal pDecoratedAnimal) {
      decoratedAnimal = pDecoratedAnimal;
   }
 
   public void init(int pMovementAmount) {
      movementAmount = pMovementAmount;
   }
 
   public String getType() {
      return decoratedAnimal.getType();
   }
 
   public void move() {
      decoratedAnimal.move();
      StringWriter aWriter = new StringWriter();
      aWriter.append("Move " + getMovement());
      if (movementAmount != 0) {
         aWriter.append(" " + movementAmount);
         aWriter.append(" " + getMovementUnits());
      }
      aWriter.append(".");
      System.out.println(aWriter.toString());
   }
 
   public void speak() {
      decoratedAnimal.speak();
   }
 
   public abstract String getMovement();
 
   public abstract String getMovementUnits();
}

We now have a more complicated move method, but the idea is much the same. Decorate the object, then add functionality.

Once again we need to create concrete methods for the movement types. We have MoveForward, MoveLeft, and MoveRight.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

public class MoveRightDecorator extends MovingDecorator {
 
   public MoveRightDecorator(Animal pDecoratedAnimal) {
      super(pDecoratedAnimal);
   }
 
   public String getMovement() {
      return "right";
   }
 
   public String getMovementUnits() {
      return "degrees";
   }
}

These look almost the same as our Emotion ones, but we also have to implement a movement units method.

For our purposes we didn’t have to execute the init method, but we could. First is a simple class showing the using of this Decorator.

1
2
3
4

public static void main(String[] args) {
   Animal aMammal = new MoveForwardDecorator(new Mammal());
   aMammal.move();
}

Here shows chaining the move methods:

1
2
3
4
5

public static void main(String[] args) {
   Animal aBird = new MoveForwardDecorator(new MoveLeftDecorator(
   new MoveForwardDecorator(new MoveRightDecorator(new Fish()))));
   aBird.move();
}

And finally, here we use the init method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public static void main(String[] args) {
   Animal aBird = new Bird();
   MovingDecorator aDecoBird = new MoveForwardDecorator(aBird);
   aDecoBird.init(10);
   aDecoBird = new MoveRightDecorator(aDecoBird);
   aDecoBird = new MoveForwardDecorator(aDecoBird);
   aDecoBird = new MoveLeftDecorator(aDecoBird);
   aDecoBird.init(90);
   aDecoBird = new MoveForwardDecorator(aDecoBird);
 
   //What happens when this is uncommented?
   //aDecoBird = new HappyDecorator(aBird);
 
   aDecoBird.move();
   aDecoBird.speak();
}

If you noticed, I actually created a MovingDecorator instead of an Animal here, and that was simply so that I didn’t have to keep casting to call the init method.

How about in the Java SDK?

One of the best examples is the FileIO section. This is the code that allows you to read and write to the file system. You start with a basic byte or character reader, then wrap with decorators that can read by lines, or buffer for more performance.

You can learn about file IO in this sun trail.

If you remember from the Reflection Session, we read data from a properties file. We will access a file the same way here. This is shown so you can see what it looks like with no decoration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

public class IODecoratorTest1 {
   public static void main(String[] args) throws Exception {
 
      int c;
 
      InputStream aStream = IODecoratorTest1.class.getResourceAsStream("ioTest.txt");
 
      while (( c = aStream.read() ) >= 0 ) {
         System.out.println((char)c);
      }
 
      aStream.close();
   }
}

IODecoratorTest2 shows how we decorate the input stream. First with InputStreamReader, then with BufferedReader, then finally adding a LineNumberReader.

1
2
3
4
5
6
7
8
9

Reader aReader = new InputStreamReader(IODecoratorTest1.class
.getResourceAsStream("ioTest.txt"));
 
Reader aReader = new BufferedReader(new InputStreamReader(
IODecoratorTest1.class.getResourceAsStream("ioTest.txt")));
 
Reader aReader = new LineNumberReader(new BufferedReader(
new InputStreamReader(IODecoratorTest2.class
.getResourceAsStream("ioTest.txt"))));

So, as you can see, we are layering, or stacking the classes. We are decorating the read() methods in each of these classes to add behavior. We can do the same thing. Lets write a Reader decorator ourselves that can count the number of times ‚ÄòI’ is in the file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

public class ICountReader extends FilterReader {
 
   private Reader inReader;
   private int count;
 
   public ICountReader(Reader pInReader) {
      super(pInReader);
      inReader = pInReader;
      count = 0;
   }
 
   public int read() throws IOException {
      int aByte = inReader.read();
      if (aByte == 'I') {
         count++;
      }
      return aByte;
   }
 
   public int read(char[] cbuf, int off, int len) throws IOException {
      int n = inReader.read(cbuf, off, len);
 
      for (int i = off; i < off + n; i++) {
         int c = cbuf[i];
         if (c == 'I') {
            count++;
         }
      }
   return n;
   }
 
   public int getICount() {
      return count;
   }
}

We are extending FilterReader instead of implementing the Reader interface so we don’t have quite so many methods to implement. This is just the same as the other decorators we have been looking at. We can insert it into a decorator chain just the same way.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public class IODecoratorTest3 {
   public static void main(String[] args) throws Exception {
      int c;
      ICountReader aICountReader = new ICountReader(new BufferedReader(new InputStreamReader(IODecoratorTest1.class.getResourceAsStream("ioTest.txt"))));
      LineNumberReader aLineReader = new LineNumberReader(aICountReader);
 
      while ((c = aLineReader.read()) >= 0) {
          System.out.println((char) c);
      }
 
      aLineReader.close();
 
      // We cast because we need a ICountRe to ask for the line
      // number, and it is zero based so we add one
      System.out.println("# of I's:" + aICountReader.getICount());
      System.out.println("# of lines:" + (aLineReader.getLineNumber() + 1));
   }
}

The Singleton in the Physical World

The idea behind the Singleton is to ensure that there can be only one (insert Highlander jokes here). If you had a factory that made widgets, you would want a widget to be created many many times. But there is only one factory. If you were modeling the US government, you would only want one president. Only one senate.

The Singleton in the Software World

On the software side, the idea is the same. It is usually used when we only want one set of configuration variables, one controller, one data base connection pool, that kind of thing.

How do we do this?

Let’s back up a bit. Let us look at a very basic class that provides us with a code that is needed across our application.

public class MyClass {

   private long code;

   public MyClass() {
      code = Calendar.getInstance().getTimeInMillis();
   }

   public long getCode() {
      return code;
   }
}

public class MyClassTest {
   public static void main(String[] args) throws Exception {

      MyClass myClass1 = new MyClass();
      System.out.println(myClass1.getCode());

      Thread.sleep(500);// wait a bit to see if our code is the same

      MyClass myClass2 = new MyClass();
      System.out.println(myClass2.getCode());

      System.out.println("Oops. Different values.");
   }
}

If you only ever instantiated this class once, you are fine. But we haven’t done anything here to ensure that this is the case. There is nothing to stop someone from creating two MyClass objects.

Let’s start with the opposite. How do we create an instance of a class?

1
2

MyClass myClass1 = new MyClass();
MyClass myClass2 = new MyClass();

What can we do to ensure that only one instance can be created? Is there something else we have looked at that allows only one instance of a variable to occur? Static! We can use the static property.

public class MyStaticClass {

   private static long code = Calendar.getInstance().getTimeInMillis();

   public static long getCode() {
      return code;
   }
}

   public static void main(String[] args) throws Exception {

      MyStaticClass myClass1 = new MyStaticClass();
      System.out.println(MyStaticClass.getCode());
      System.out.println(myClass1);

      Thread.sleep(500);// wait a bit to make sure our code is the same

      MyStaticClass myClass2 = new MyStaticClass();
      System.out.println(MyStaticClass.getCode());
      System.out.println(myClass2);

      System.out.println("Ok. Same values.");
      System.out.println("Oops, different objects.");

   }
}

This time we have assigned a static variable our code, and provided a static method for accessing this code. Does this work? Somewhat. We only have one instance of code inside of MyStaticClass, but MyStaticClass is not guaranteed to have only one instance. This will get cumbersome to initialize as we add other data. It also results in a bunch of MyStaticClass.getCode() all over the application. What would be better would be to ask for this class just once, and then call getCode() as needed. How can we set that up?

The Simplest Singleton

1
2
3
4
5
6
7
8
9
10
11
12
13
14

public class Singleton {
 
   private static Singleton singleton;
 
   private Singleton() {
   }
 
   public static Singleton getInstance() {
      if ( singleton == null ) {
         singleton = new Singleton();
      }
      return singleton;
   }
}

This example doesn’t have our “code” in it, but it does show the elements of the singleton. We will add the “code” later.

There are some interesting things about this class. Look at the constructor. It is private! How does that work? We can’t do a “new” on this class! How can we create it? There is a private member variable that is static, and is of the same type as the class! It is a very strange sight at first glance. What is going on?

The constructor being private accounts for our first goal. No ability to call “new” on the object. If we can’t do a “new”, how can we create it? Well, we can do a “new”, but only from inside the class itself. We are doing that in the static getInstance() method. Look at what that method does. It first checks to see if an instance of the member variable singleton exists. If it doesn’t, it creates a “new” instance. This is the only place we will ever create an instance of the class Singleton. Therefore we have ensured that this is the only copy available. We then return singleton.

By doing things this way we have also lazy initialized the singleton. If we don’t need it, we never call getInstance(), and we never have to worry about the JVM allocating memory for something not used.

We also get a normal looking class out of it. We can have standard getters that are not static, and our application can pass this object around. It is easier to conceptualize the object used this way, and do maintenance later than a bunch of static methods seemingly randomly called within methods.

Can we actually do something?

Ok, I get your point. We need a bit more of an example. So here is a singleton with one “code” just like the others.

public class MySingletonClass {

   private static MySingletonClass singleton;

   private long code;

   private MySingletonClass() {
      code = Calendar.getInstance().getTimeInMillis();
   }

   public static MySingletonClass getInstance() {

      if ( singleton == null ) {
         singleton = new MySingletonClass();
      }
      return singleton;
   }

   public long getCode() {
      return code;
   }
}

public class MySingletonClassTest {
   public static void main(String[] args) throws Exception {

      MySingletonClass mySingletonClass1 = MySingletonClass.getInstance();
      System.out.println(mySingletonClass1.getCode());
      System.out.println(mySingletonClass1);

      Thread.sleep(500); //wait a bit to make sure our code is the same

      MySingletonClass mySingletonClass2 = MySingletonClass.getInstance();
      System.out.println(mySingletonClass2.getCode());
      System.out.println(mySingletonClass2);

      System.out.println("yea, same code");
      System.out.println("yea, same object");
   }
}

Look at that. Other than the singleton field, the constructor marked as private, and the getInstance() method, it is a pretty normal looking class. The constructor initializes our class just as we would expect. We can have pretty standard fields, like “code” with normal public getters.

Is that all there is to it?

Yup. It is that easy. Almost. Sometimes. There is one more wrinkle. Depending on how this singleton is being used, you may need to account for multiple threads. I am not going to get into that here, as we haven’t looked at threads yet. Keep in mind that if multiple objects could all call getInstance() at the same time, you may have an issue. Look it up, or wait and see if I get to threads eventually

Why use the pattern?

• Ensures only one instance of your code with minimal fuss.
• The singleton can be assigned.
• Uses lazy initialization to save memory.
• It is proven. It works. You can try to avoid the pattern, but why bother?

What do they look like?

1
2
3
4

@Override
public String getName() {
	return "no name";
}

The word after the ‘@’ is the Annotation. It precedes a method or class name. The Override annotation is built into Java. It is used to indicate that a method overrides a parents method. These are used for compiler hinds, for documentation, and to apply meta data.

Built in Annotations

• @Deprecated : used much like the java doc comment
• @Override ‚Äì indicates a method overrides a parents method
• @SuppressWarnings ‚Äì tells compiler not to indicate warnings
• @Documented ‚Äì tells javadoc to document the applied Annotations
• @Retention(RetentionPolicy.xxx) ‚Äì indicate to compiler when the Annotation is available

Take a look at the Bird.getName() method, and the Animal.getType() method to see a couple of Annotations. Theese classes have been altered slightly here to add some annotations. AnnotationsTest1 shows what you will see in eclipse, or if you compile a deprecated method. AnnotationsTest2 shows how you can use @SupressWarnings.

1
2
3
4
5
6
7
8
9
10
11

public interface Animal {
   public void speak();
   public void move();
   public String getName();
   public void setName(String pName);
   /**
    * @ deprecated This will not work in the future
    */
   @Deprecated
   public String getType();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

@Ratable(value=8)
public class Bird extends BaseAnimal {
 
   public Bird() {
      this(null);
   }
 
   public Bird(String pName) {
      super(pName);
      System.out.println("Bird created.");
   }
 
   @Ratable(6)
   public void move() {
      System.out.println(getDescription() + " is flying.");
   }
 
   @Ratable(10)
   public void speak() {
      System.out.println(getDescription() + " chirps.");
   }
 
   /**
    * Can't use @Override because it is an interface method
    */
   public String getType() {
      return "bird";
   }
 
   @Override
   public String getName() {
      return "no name";
   }
}

1
2
3
4
5
6
7
8
9
10
11
12

public class AnnotationsTest1 {
   public static void main(String[] args) {
 
      Fish aFish = new Fish();
      aFish.getType();
 
      Animal aAnimal = new Fish();
      // this line in Eclipse show a strike through on the method
      // when compiling with warnings you would get the error too
      aAnimal.getType();
   }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

public class AnnotationsTest2 {
 
   public void doWithOutGenerics() {
      // without generics compiler gives warning about generic type
      List aList = new ArrayList();
      aList.clear();
   }
 
   @SuppressWarnings("unchecked")
   public void doWithAnnotations() {
      // adding annotation to remove compiler warning
      List aList = new ArrayList();
      aList.clear();
   }
 
   public void doWithGenerics() {
      // add type to List and ArrayList
      List aList = new ArrayList();
      aList.clear();
   }
}

Creating your own Annotations

If you would like to create your own Annotations, it is not very hard. For example look at the Ratable Annotation.

1
2
3
4
5
6
7
8
9
10

@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Ratable {
 
   int value() default 0;
 
   int rating() default 1;
 
   String why() default "because";
}

The class is defined as an @Interface. This makes it an annotation. The strange method definitions that follow are the types of meta data that this annotation can contain. This one can have a value, a rating, and a why. One of the neat things, is that you can provide defaults in the case that someone using your annotation does not provide values for them. So how would you apply this annotation?

Look at the first couple of lines from Fish.

1
2

@Ratable(rating = 2, why = "Smells Bad")
public class Fish extends BaseAnimal {

The Ratable annotation has been applied to the class Fish with a rating of 2, a value of 0 (default) and a why of “Smells Bad”.

Why would you want your own Annotations?

Why would create your own? If you create an annotation, you can use them with compiler tools to provide information. If you specify a RetentionPolicy of Runtime, then you can use your annotation at Runtime. What good would that be? Think about MP3 files. You can do a search of all your music for all music files that are by a certain author. You can do that with annotations of your classes as well. You can use annotations instead of using instanceof. You can also scan the class path to look for annotations.

Several well know packages and utilities have started to use annotations for configuration. Struts2, JBoss, and hibernate are some you may have heard about. This idea allows you to specify configuration right in the classes themselves instead of in separate XML or properties files.

The Java reflections API provides some help for dealing with these as runtime, but libraries have been created that help with this. One such library is also called “reflections”. AnnotationsTest3 is an example that uses this API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

public class AnnotationsTest3 {
   public static void main(String[] args) {
      AbstractConfiguration configuration = new AbstractConfiguration(); 
 
      configuration.setUrls(ClasspathHelper.getUrlsForCurrentClasspath());
      configuration.setScanners(new ClassAnnotationsScanner());
      configuration.setFilter(new IncludePrefix("net.cyberward.tutorial.java.annotations"));
 
      Reflections reflections = new Reflections(configuration);
      Set> annotated = reflections.getTypesAnnotatedWith(Ratable.class);
 
      for (Class aAnnotatedClass : annotated) {
         Ratable aRateableAnnotation = aAnnotatedClass.getAnnotation(Ratable.class);
         System.out.println(aAnnotatedClass);
         System.out.println(aRateableAnnotation);
         System.out.println("rateing:"+aRateableAnnotation.rating());
         System.out.println();
      }
   }
}

More Information:

• http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html
• http://en.wikipedia.org/wiki/Java_annotation
• http://www.javabeat.net/articles/30-annotations-in-java-50-1.html
• http://code.google.com/p/reflections/

Note: If you are using Eclipse and do a “Refactor / Rename…” of an Annotation, all the places that use the Annotation will be modified too.

What do they look like?

Since we are talking about Lists, lets look at what a ArrayList would look like that could only take Strings.

1

List aList = new ArrayList();

What goes between the <> is the type that you want to specify for the List. You need to do it in the left side declaration, and on the right side where you are creating the Object.

Does this work for all classes?

A class has to be specifically defined for generics. All the collections have been defined this way, and you can create your own classes like this too.

Lets look at the class definition of List:

1

public interface List extends Collection {

Now lets look at methods such as add and get:

1
2
3

boolean add(E o);
 
E get(int index);

In the definition, between the <> List is defined to have a variable E that will contain a class type. (It is always a class type.) This variable can be used anywhere you want to specify this class type. In the case of the add() method, it means that the add method can only accept Objects of the class type E. For the get method, it means that the get method returns an Object of type E.

How is any of this useful?

Well, first of all, if you have your compiler set up to compile at a Java 5 level, adding these types removes all the compiler warnings. In Eclipse it will remove all the yellow warnings that are annoying.

More importantly, it allows you to limit the type that you take in with your methods.

GenericsTest1 serves as an example of how you would apply generics to a List.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

public class GenericsTest1 {
   public static void main(String[] args) {
      // Create a List without specifying type parameters
      List aList1 = new ArrayList();
      aList1.add(new Bird());
      aList1.add(new Fish());
      aList1.add(new Mammal());
      // Does compiler complain? Does it work at runtime?
      //aList1.add(new Object());
 
      for (Iterator iterator = aList1.iterator(); iterator.hasNext();) {
         //notice the need for a cast
         Animal aAnimal = (Animal) iterator.next();
         aAnimal.move();
      }
 
      // Create a List and specify that only an Animal can be used.
      List aList2 = new ArrayList();
      aList2.add(new Bird());
      aList2.add(new Fish());
      aList2.add(new Mammal());
      // Does compiler complain? Does it work at runtime?
      //aList2.add(new Object());
 
      for (Iterator iterator = aList2.iterator(); iterator.hasNext();) {
         // notice no casting
         Animal aAnimal = iterator.next();
         aAnimal.move();
      }
   }
}

GenericsTest2 shows a similar example, but using a Map.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

public class GenericsTest2 {
   public static void main(String[] args) {
      Integer aIntegerKey = new Integer(10);
 
      // Create a Map without specifying type parameters
      Map aMap1 = new HashMap();
      aMap1.put("bird", new Bird());
      aMap1.put("fish", new Fish());
      // Notice that there is no restriction on the key type
      aMap1.put(aIntegerKey, new Mammal());
 
      Animal aBird = (Animal) aMap1.get("bird");
      aBird.move();
 
      Animal aFish = (Animal) aMap1.get("fish");
      aFish.move();
 
      Animal aMammal = (Animal) aMap1.get(aIntegerKey);
      aMammal.move();
 
      // Create a Map an specify that only a String key and an Animal value
      // can be used in the map.
      Map aMap2 = new HashMap();
      aMap2.put("bird", new Bird());
      aMap2.put("fish", new Fish());
 
      // What happens when this is uncommented
      //aMap2.put(aIntegerKey, new Mammal());
 
      Animal aBird2 = aMap2.get("bird");
      aBird2.move();
 
      Animal aFish2 = aMap2.get("fish");
      aFish2.move();
 
      //What happens when this is uncommented. Compiler? Run time? Why?
      //Animal aMammal2 = aMap2.get(aIntegerKey);
      //aMammal2.move();
   }
}

Now lets rewrite a couple of things to use generics.

Look at the CollectionUtilities.printAnimalList() method from the “Intro to Java Collections” lesson.

1
2
3
4
5
6
7

public static void printAnimalList(List pAnimalList) {
   for (Iterator iterator = pAnimalList.iterator(); iterator.hasNext();) {
      // notice the need for a cast
      Animal aAnimal = (Animal) iterator.next();
      System.out.println(aAnimal.getName() + ":" + aAnimal.getType());
   }
}

You can’t get much more un type safe than this. We define the method to only take in a List. But in the code we expect to only have Animals. We also have to cast to an Animal because when the List is created we don’t define a specific type, so the list can contain any type of Object.

Lets rewrite this method using generics.

1
2
3
4
5
6
7

public static void printAnimalList(List pAnimalList) {
   for (Iterator iterator = pAnimalList.iterator(); iterator.hasNext();) {
      // notice no casting
      Animal aAnimal = iterator.next();
      System.out.println(aAnimal.getName() + ":" + aAnimal.getType());
   }
}

Our method definition has determined that only Lists that contain Animal types are allowed. If someone tried to use this method with a List of Strings, the compiler would not let it happen. Also notice that we no longer need to cast from this Iterator. That is because the .iterator() method in List returns a Iterator, and Iterator doesn’t return just an Object, but one of the Animal type.

Even better, lets use a new Java 5 looping structure called a “for each” loop. This works for any class that implements the Iterable interface (like List).

1
2
3
4
5

public static void printAnimalList(List pAnimalList) {
   for (Animal aAnimal : pAnimalList) {
      System.out.println(aAnimal.getName() + ":" + aAnimal.getType());
   }
}

Now lets look at Cage. Cage is a version of a cage that allows you to specify what type of animal the cage contains using generics. See GenericsTest3. This is not quite the same as BirdCage, it is not a singleton, but BirdCage could also be rewritten so that it could be a cage for any animal, not just birds. Try to rewrite it using this Cage as an example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public class Cage {
   // We can then use T to define our list class type
   private List animalList;
 
   public Cage() {
      // When we create the list we must tell it a type too.
      animalList = new ArrayList();
   }
 
   // We can even specify in a method signature that only objects of type T are
   // allowed to be here. Not just any Animal, but just of class type T.
   public void insertAnimal(T pAnimal) {
      animalList.add(pAnimal);
      System.out.println(pAnimal.getName() + " " + pAnimal.getType() + " is in the cage.");
   }
 
   // When we return our list, it will be a list that only contains class type
   // T, and you won't need to cast individual elements from the list.
   public List getAnimals() {
      return animalList;
   }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

public class GenericsTest3 {
   public static void main(String[] args) {
      // Without specifying type parameters the compiler gives us all kinds of warnings.
      Cage aCage = new Cage();
      aCage.insertAnimal(new Bird());
      // Notice that because we didn't specify a type when we created the
      // Cage, we can actually add a fish.
      aCage.insertAnimal(new Fish());
 
      // Lets add parameters.
      Cage aBirdCage = new Cage();
      aBirdCage.insertAnimal(new Bird());
      aBirdCage.insertAnimal(new Bird());
      // What happens when this is uncommented
      // aBirdCage.insertAnimal(new Fish());
 
      // You can get back a non parameterized list, and it is functional, but
      // you get a warning from the compiler.
      List aList2 = aBirdCage.getAnimals();
      System.out.println(aList2.size());
 
      // Add the type parameter to list to make the compiler happy.
      List aBirdList = aBirdCage.getAnimals();
      System.out.println(aBirdList.size());
   }
}

Letter Conventions

There is no restriction on what letters you can use in your class definitions and method signatures. In fact, instead of “T” you could use “QQ” or “Type”. It seems that the Java authors have settled on using just one letter, and they themselves have been fairly consistent about the letters they use.

In the collections packages they usually use “E” for element. So when you look at the interface for List, you will see .

If you look at the Map interface, you will see for Key and Value.

Also, other classes that take in a class type usually use the letter “T” for type.

More Information:

• http://java.sun.com/docs/books/tutorial/java/generics/index.html
• http://java.sun.com/j2se/1.5.0/docs/guide/language/generics.html
• http://java.sun.com/j2se/1.5/pdf/generics-tutorial.pdf (pdf)
• http://en.wikipedia.org/wiki/Generics_in_Java

What do they look like?

There are three main types of collections: Lists, Maps, and Sets. Technically you could try to argue that Map doesn’t extend Collection, so therefore it is not a Collection, but I think of it as part of the group.
They are used for groups of objects, or exactly as its name would imply, collections of objects.

List

A List is just that, a list of objects. The List interface provides a way to add, remove and get objects from a list. It however is just an interface. ArrayList is one of the more popular concrete collections that implements the List interface. Each implementation of the List interface may behave slightly different, but once you understand how a List works, you have a good start on understanding any List.

An ArrayList can be thought of in some ways like an Array, but there are some differences. One of the biggest is that you can keep adding or removing from an ArrayList (or any List) without needing to have defined it in a constructor.

1
2
3

List aList = new ArrayList();
 
String[] aArray = new String[5];

On the first line we created a generic list that can hold ANY type of object, and of any amount of them. On the second line, we created an Array that always has a size of 5, and can only hold Strings. (The type limitation can be seen as a positive or a negative, and we will look at how we can do similar things with Lists when we get to Generics in a different lesson.)

Some of the typical methods of List you will use are :

• add(Object o) : to add an element to the end of the list
• add(int index, Object o) : to add an object at a particular index
• boolean remove(Object o) : remove the specific Object
• remove(int index) : remove the Object at a particular index
• boolean contains(Object o) : if an object exists in the list
• int indexOf(Object o) : position of an index in the list
• Object get(int index) : return the Object from a particular index
• Iterator iterator() : return an Iterator for the list
• size() : number of elements in the list
• Object[] toArray(Object[] o) : return an Array of type o

public class CollectionsTest1 {
   public static void main(String[] args) {
      // List is just an interface. We need to create something that
      // implements List, and ArrayList is one such Class that is pretty
      // common, but not the only one.
      List aList1 = new ArrayList();
      aList1.add(new Bird("Tweety"));
      aList1.add(new Fish("Swimmy"));
      aList1.add(new Mammal());
      // Does compiler complain? Does it work at runtime?
      // aList1.add(new String("Johnny"));

      // To prove that our List is a Collection, we have a static method that
      // will print out any item from a Collection
      CollectionUtilities.printAnimalList(aList1);
   }
}

public class CollectionUtilities {

   /**
    * Any object that extends Collection can be printed here. It works because
    * you can get an iterator from a collection object.
    *
    * @param pCollection
    */
   public static void printList(Collection pCollection) {

      for (Iterator iterator = pCollection.iterator(); iterator.hasNext();) {
         Object aObject = iterator.next();
         System.out.println(aObject);
      }
   }

   /**
    * Note that for now, we are only specifying a list, there is nothing to
    * stop you from passing in a list of any type of object. See the generics
    * lesson for more info.
    *
    * @param pAnimalList
    */
   public static void printAnimalList(List pAnimalList) {
      for (Iterator iterator = pAnimalList.iterator(); iterator.hasNext();) {
         // notice the need for a cast
         Animal aAnimal = (Animal) iterator.next();
         System.out.println(aAnimal.getName() + ":" + aAnimal.getType());
      }
   }

   /**
    * Sorts a List of elements of type Animal useing the AnimalComparator
    *
    * @param pAnimalList
    */
   public static void sortAnimals(List pAnimalList) {
      Collections.sort(pAnimalList, new AnimalComparator());
   }

   /**
    * Figured if we had a comparator, we should use it on an array too.
    *
    * @param pAnimalArray
    */
   public static void sortAnimals(Animal[] pAnimalArray) {
      Arrays.sort(pAnimalArray, new AnimalComparator());
   }

   /**
    * Shows how we can take in a list and return a set
    *
    * @param pAnimalList
    * @return
    */
   public static Set findBirds(List pAnimalList) {
      Set aBirdSet = new HashSet();
      for (Iterator iterator = pAnimalList.iterator(); iterator.hasNext();) {
         Animal aAnimal = (Animal) iterator.next();
         if ( aAnimal instanceof Bird ) {
            aBirdSet.add(aAnimal);
         }
      }
      return aBirdSet;
   }
}

CollectionsTest1.java is a very basic class that uses an ArrayList. One of powerful features of Java is the use of Interfaces. Using them, we can create methods that know enough to get the job done, but little enough that they are still generic. That is the idea behind CollectionUtilities. The printList method can print anything that is a Collection. The printAnimalList can print more details as long as the item is a List of Animals.

public class CollectionsTest2 {
   public static void main(String[] args) {
      List aList1 = new ArrayList();
      aList1.add(new Bird("Birdy"));
      // size() method will print number of elements in the list
      System.out.println(aList1.size());
      // clear() method will remove all elements from list
      aList1.clear();
      System.out.println(aList1.size());

      Bird aTweety = new Bird("Tweety");
      aList1.add(aTweety);
      aList1.add(new Fish("Swimmy"));
      aList1.add(new Mammal());

      // contains() method is used to check the list for a particular object
      if (aList1.contains(aTweety)) {
         System.out.println("found tweety");
      } else {
         System.out.println("tweety has flown the coop");
      }
      // remember, this is object equals
      if (aList1.contains(new Fish("Swimmy"))) {
         System.out.println("found swimmy");
      } else {
         System.out.println("swimmy has left the building");
      }

      // get() method to retrieve an object from the list
      Animal aMammal1 = (Animal) aList1.get(2);
      System.out.println("aMammal1(index 2):" + aMammal1.getName());

      // This object is "live". The list only contains pointers to the real
      // objects. Change an object from the list...
      aMammal1.setName("Rover");

      // and the object in the list is changed.
      Animal aMammal2 = (Animal) aList1.get(2);
      System.out.println("aMammal2(index 2):" + aMammal2.getName());
   }
}

CollectionsTest2 shows some of the other methods that are commonly used with Lists.

Another interesting thing that is often done with Lists, is to sort them. You can sort Objects in anyway imaginable that makes sense to your for your particular object. One way to do this is to create a reusable class called a Comparator. AnimalComparator is a Comparator that can be used to sort based on first the type, then the name of the Animal. CollectionsTest3 shows how to use this comparator to sort both a List and an Array. This class also shows how you can take a List and turn it into an Array.

/**
 * This Comparator can be used to sort animals. A null animal is < an actual
 * animal. The order is alphabetical on type, then alphabetical on name.
 *
 * Note: not null safe on type and name. If running against VERY large lists you
 * may want to try to avoid creating all the Strings for type and name.
 *
 * @author Chris Ward 
 */
public class AnimalComparator implements Comparator {
   public int compare(Object pAnimal1, Object pAnimal2) {
      if (pAnimal1 == null && pAnimal2 == null) {
         return 0; // equal
      }
      if (pAnimal1 == null) {
         return -1; // pAnimal1 < pAnimal2
      }
      if (pAnimal2 == null) {
         return 1; // pAnimal 1 > pAnimal2
      }

      String aType1 = ((Animal) pAnimal1).getType();
      String aType2 = ((Animal) pAnimal2).getType();

      int aTypeCompare = aType1.compareTo(aType2);
      // If different, we don't need to compare anymore
      if (aTypeCompare != 0) {
         return aTypeCompare;
      }

      String aName1 = ((Animal) pAnimal1).getName();
      String aName2 = ((Animal) pAnimal2).getName();
      return aName1.compareTo(aName2);
   }
}

public class CollectionsTest3 {
   public static void main(String[] args) {
      List aList1 = new ArrayList();
      aList1.add(new Bird("Tweety"));
      aList1.add(new Fish("Swimmy"));
      aList1.add(new Mammal());
      aList1.add(new Bird("Robby Robbin"));
      aList1.add(new Mammal("Zeke"));

      System.out.println();
      CollectionUtilities.printAnimalList(aList1);

      // sort using a comparator
      CollectionUtilities.sortAnimals(aList1);

      System.out.println();
      CollectionUtilities.printAnimalList(aList1);

      System.out.println();
      List aList2 = new ArrayList();
      aList2.add(new Bird("Tweety"));
      aList2.add(new Fish("Swimmy"));
      aList2.add(new Mammal());
      aList2.add(new Bird("Robby Robbin"));
      aList2.add(new Mammal("Zeke"));

      // A List can convert to an Array
      Animal[] aAnimalArray = (Animal[]) aList2.toArray(new Animal[0]);

      // You can sort an array with the same comparator
      CollectionUtilities.sortAnimals(aAnimalArray);

      System.out.println();
      for (int i = 0; i < aAnimalArray.length; i++) {
         System.out.println(aAnimalArray[i].getName());
      }
   }
}

Map

A Map is like a look up table, or index table. For every object that goes into the Map, you have to give an index to where it is. A List can know where each object is by a numeric index, but if you removed the first object, you would no longer know the index of any of the Objects in your list! By using a Map, you can use any type of index you wish. You can use Integers, Strings, or any Object you can come up with. As with List, Map is just an Interface. We will use the HashMap in our examples.

CollectionsTest4 shows how to use a Map and how the concept of keys works.

public class CollectionsTest4 {
   public static void main(String[] args) {
      Integer aIntegerKey = new Integer(10);

      Map aMap1 = new HashMap();
      aMap1.put("bird", new Bird());
      aMap1.put("fish", new Fish());
      // Notice that there is no restriction on the key type
      aMap1.put(aIntegerKey, new Mammal());

      // Note: Map doesn't actually implement the Collection interface
      // CollectionUtilities.printList(aMap1);

      // A map stores Objects, must cast to Animal
      Animal aBird = (Animal) aMap1.get("bird");
      System.out.println(aBird);

      // Non Strings work as keys just fine
      Mammal aMammal = (Mammal) aMap1.get(aIntegerKey);
      System.out.println(aMammal);
   }
}

Some of the more common methods of a Map are:

• Object put(Object key, Object value)
• Object get(Object key)
• boolean containsKey(Object key) : check to see if a particular key exists in the Map
• boolean containsValue(Object value) : check to see if a particular value exits in the Map
• Object remove(Object key) : remove the entry that has the particular key
• int size()

If you get a lot of Birds in a cage, it is tough to remember what bird is inside, so let's use a HashMap to create a cache of Bird objects. BirdCage will use the bird's name as the key, and the actual Bird object as the value. See CollectionsTest5 to see this implemented.

/**
 * Using a HashMap to implement a type of cache. We use the name of our Bird's
 * as the key. The Bird its self is the value. If the bird does not exist in our
 * cache, we add it. It it is there, we return the one we found.
 *
 * @author Chris Ward 
 */
public class BirdCage {

   private static BirdCage birdCage;
   private Map birdCache;

   /**
    * The BirdCage is a singleton. We have decided that there will be only one
    * bird cage in per java machine.
    */
   private BirdCage() {
      birdCache = new HashMap();
      System.out.println("Creating a BirdCage. There can be only one bird with a given name.");
   }

   public static BirdCage getInstance() {
      if (birdCage == null) {
         birdCage = new BirdCage();
      }
      return birdCage;
   }

   public Bird checkCage(String pName) {
      if (birdCage == null) {
         getInstance();
      }

      if (!birdCache.containsKey(pName)) {
         System.out.println(pName + " not found... adding.");
         Bird aBird = new Bird(pName);
         birdCache.put(pName, aBird);
         return aBird;
      }
      System.out.println("The name " + pName + " was found");
      System.out.println("Returning original " + pName);
      return (Bird) birdCache.get(pName);
   }

   public int getSize() {
      return birdCache.size();
   }

   public boolean isInCage(String pName) {
      return birdCache.containsKey(pName);
   }
}

public class CollectionsTest5 {
   public static void main(String[] args) {
      BirdCage aCage = BirdCage.getInstance();

      Bird aTweety1 = aCage.checkCage("Tweety");
      Bird aRobby = aCage.checkCage("Robby Robbin");
      //will Tweety be added twice?
      Bird aTweety2 = aCage.checkCage("Tweety");
      Bird aSam = aCage.checkCage("Sam");

      //What will be the size?
      System.out.println("size:" + aCage.getSize());

      //Will these two birds be equal?
      System.out.println("Tweety1 == Tweety2 : " + aTweety1.equals(aTweety2));
      System.out.println("Frank is in cage? " + aCage.isInCage("Frank"));
      System.out.println("Sam is in cage? " + aCage.isInCage("Sam"));
   }
}

Set

A set is like a partial List. They are often returned from a collection when you have asked for some subset of the whole. For example, if we had a big list of Animals, and we wanted to find out what of these Animals were Birds, we could get a Set back. The methods of Set are much like the List, but with a Set, no two elements are equal within a Set. There are no duplicates.

As an example, take a look at the CollectionsTest6 class. This creates a list, then asks a method from the CollectionUtilities to return a Set of just the Birds.

public class CollectionsTest6 {
   public static void main(String[] args) {
      List aAnimalList = new ArrayList();
      aAnimalList.add(new Bird("Tweety"));
      aAnimalList.add(new Fish());
      aAnimalList.add(new Mammal());
      aAnimalList.add(new Bird());
      aAnimalList.add(new Bird("Sam"));

      Set aBirdSet = CollectionUtilities.findBirds(aAnimalList);
      CollectionUtilities.printList(aBirdSet);
   }
}

More Information

Java collections trail: http://java.sun.com/docs/books/tutorial/collections/index.html