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.