Design Patterns - Singleton

(Free Web Tutorial)

by Michael Thomas

In this tutorial you will be introduced to the "Singleton" design pattern.

Note: On the Design Patterns Home page, you can download this whole tutorial (all content, tutorials & examples) !!!

Prerequisites

Nice to know JUnit

Objectives

Discuss the intent, motivation and applicability of the Singleton design pattern.
See example java code that implements the Singleton design pattern.

Terminology

Gof ("Gang of Four") - The 23 Gof design patterns comes from the book: Design Patterns: Elements of Reusable Object-Oriented Software, Addison-Wesley, by Erich Gamma, Richard Helm, Ralph Johnson, John Vissides.
JVM - Java Virtual Machine

Singleton Design Pattern (Group: Creational Patterns)

Intent of the Singleton Design Pattern
- Wikipedia's Singleton: Singleton restricts object creation for a class to only one instance.
- Gof: Ensure a class only has one instance, and provide a global point of access to it. (pg 127)
- Michael Thomas
  - You want to ensure that you only have one instance of a class per a JVM.
Common Uses for Singleton implementation:
- Factory Method
- Abstract Factory design pattern
- Builder design pattern
- Prototype design pattern
- Facade design pattern
- State design pattern

Singleton Design Pattern discussed

Singleton Objectives

The goal of a Singleton is to design a class so that only one object can be instantiated per JVM.
We can create a Singleton that exists as the JVM loads ("JVM-loading") using statics or one that exists the first time it is needed ("Lazy-loading") using object creation inside the class. With "JVM-loading" memory is allocated at JVM startup time. With ("Lazy-loading") memory is allocated the first time the one and only one object is instantiated and remains alive as long as there is a reference to the object and therefore is not garbage collected.
Do not allow another class to create an instance of the Singleton class so that only one instance exists.
(Note: This is done by making the constructor private.)
If you want an instance of a Singleton you must call a method to get the one and only reference to the instance of that object. That method is commonly called getInstance().

Key elements of a Singleton: (see the examples below for a full example)

The Singleton's constructor is private so you can't use the "new" key word to create an instance.

public class SingletonJVMTraditionalExample {
private SingletonJVMTraditionalExample() {
}
}

There is a method that returns an instance of the Singleton object which is commonly called getInstance(

public class SingletonJVMTraditionalExample {
    private static final SingletonJVMTraditionalExample instance = new SingletonJVMTraditionalExample();
    private SingletonJVMTraditionalExample() {
    }
    public static SingletonJVMTraditionalExample getInstance() {
        return instance;
    }
}

Examples

Download - Eclipse project exported as an archive file.
SingletonExampleTest.java.txt - JUnit test for the all the Singleton example code.
NormalClass.java.txt - this is a normal class and is NOT Singleton. This class was created so you can see the Class before it was made a Singleton. All of the classes below have taken this basic class and made it a Singleton.

Singletons created at JVM load time - using static instance. These Singleton objects are created when the JVM loads or starts up.

Additional Features
- Thread safe.
Issues
- Because the object is created at JVM load time you do not want to try to use resources that may not exist at that time.

SingletonJVMTraditionalExample.java.txt - most common "JVM-loading" Singleton.

Code Walkthrough:

Open up the link for "NormalClass.java.txt" so you can see the class before it was made into a Singleton class.
Open up the link for the Singleton code "SingletonJVMTraditionalExample.java.txt" above in a new window so you can look at the code. The "NormalClass.java" was converted to the Singleton "SingletonJVMTraditionalExample.java". You can compare this code to the "NormalClass.java" code.
Notice that the constructor is private so it can't be instantiated.

private SingletonJVMTraditionalExample() {}
Because of the code below the object is instantiated via the "new" key word at JVM load time because it is "static".

private static final SingletonJVMTraditionalExample instance = new SingletonJVMTraditionalExample();
The only way to get a reference to an instance of the class is to call the getInstance() method and therefore there is only 1 instance of this class.

public static SingletonJVMTraditionalExample getInstance() {
return instance;
}
That is it. All the other code remains the same from the original class ("NormalClass.java") that we are changing into a Singleton.

Now open up the link for SingletonExampleTest.java.txt so you can look at the JUnit code.

public void testSingletonTraditionalExample() {

    SingletonJVMTraditionalExample object1 = SingletonJVMTraditionalExample.getInstance();
    object1.setName("Hello");
    SingletonJVMTraditionalExample object2 = SingletonJVMTraditionalExample.getInstance();

object2.setName("World");

assertTrue(object1 == object2);

assertEquals("World", object1.getName());

assertEquals("World", object2.getName());

}

Notice that even though 2 objects were created the object references "object1 == object2" actually point to the same (one and only one) object which makes it a Singleton. The JUnit test is True for: assertTrue(object1 == object2);
Because there is one object when the object2.setName("World") was executed both object1 and object2 now have "World" because they point to the same object. Notice the JUnit test is equal to "World" for object1.getName() even though is was originally set to "Hello" but it was change by object2.setName("World") because both point to the one Singleton instance: assertEquals("World", object1.getName());

SingletonJVMEnumExample.java.txt - using ENUMs to create a "JVM-loading" Singleton.

Josh Bloch in his book "Effective Java" claims that the best implementation of a Singleton for Java 1.5 and greater is the ENUM approach. ENUMs were introduced in Java 1.5. It also doesn't have drawbacks regarding serializable objects.

Code Walkthrough:

Open up the link for "NormalClass.java.txt" so you can see the class before it was made into a Singleton class.
Open up the link for the Singleton code "SingletonJVMTraditionalExample.java.txt" above in a new window so you can look at the code. The "NormalClass.java" was converted to the Singleton "SingletonJVMTraditionalExample.java". You can compare this code to the "NormalClass.java" code.

Notice that the Class is now an ENUM.

public enum SingletonJVMEnumExample {

INSTANCE;

<.... All the original class code comes next! ....>

}

We still make the constructor private so now one can instantiate the object with the "new" key word.

private SingletonJVMEnumExample() {}
That is it. All the other code remains the same from the original class ("NormalClass.java") that we are changing into a Singleton.

Now open up the link for SingletonExampleTest.java.txt so you can look at the JUnit code.

@Test
public void testSingletonEnumExample() {

    SingletonJVMEnumExample object1 = SingletonJVMEnumExample.INSTANCE;
    object1.setName("Hello");
    SingletonJVMEnumExample object2 = SingletonJVMEnumExample.INSTANCE;
    object2.setName("World");
    assertTrue(object1 == object2);
    assertEquals("World", object1.getName());
    assertEquals("World", object2.getName());

}

You use the standard way of using ENUMs to create the objects. Note how object1 and object2 is instantiated.
If you look at the 3 JUnit assets you notice that there is one and only one object that was created.

Singletons created first time accessed which is called "Lazy-loading" - instance created only when needed.

SingletonLazyExample.java.txt - most common "Lazy-loading" Singleton example.
(Note: I'm not sure if this is thread safe. I need to look into that and maybe using volatile or synchronized with it to make it thread safe.)

Code Walkthrough:

Open up the link for "NormalClass.java.txt" so you can see the class before it was made into a Singleton class.
Open up the link for the Singleton code "SingletonLazyExample.java.txt" above in a new window so you can look at the code. The "NormalClass.java" was converted to the Singleton "SingletonLazyExample.java.txt". You can compare this code to the "NormalClass.java" code.
Notice that the constructor is private so it can't be instantiated.

private SingletonLazyExample() {}
Notice that the object is just defined and not instantiated here. In the JVM example above "SingletonJVMTraditionalExample.java" the variable is declared and instantiated with the "new" operator. Here it is just defined.

private static SingletonLazyExample instance;

The only way to get a reference to an instance of the class is to call the getInstance() method and therefore there is only 1 instance of this class. Notice that the first time the getInstance() method is called the variable is null and therefore the instance is created. Subsequence calls just returns the one and only one instance.

public static SingletonLazyExample getInstance() {
    if (instance == null) {
        instance = new SingletonLazyExample();
    }
    return instance;
}

That is it. All the other code remains the same from the original class ("NormalClass.java") that we are changing into a Singleton.

Now open up the link for SingletonExampleTest.java.txt so you can look at the JUnit code.

@Test
public void testSingletonLazyExample() {
    SingletonLazyExample object1 = SingletonLazyExample.getInstance();
    object1.setName("Hello");
    SingletonLazyExample object2 = SingletonLazyExample.getInstance();
    object2.setName("World");
    assertTrue(object1 == object2);
    assertEquals("World", object1.getName());
    assertEquals("World", object2.getName());
}

Note how object1 and object2 is instantiated.
If you look at the 3 JUnit assets you notice that there is one and only one object that was created.

SingletonLazyInnerClassExample.java.txt - "Lazy-loading" Singleton using an inner class's static variable. This solved issues with Java's memory management prior to JDK 1.5.

History: University of Maryland Computer Science researcher Bill Pugh used this approach to solve "Double-checked locking" issues with Java's memory model with JVM's prior to Java 1.5. This approach is called the "initialization on demand holder" idiom. (summarized from Wikipedia)
Additional Features
- Thread safe.

Code Walkthrough:

Open up the link for "NormalClass.java.txt" so you can see the class before it was made into a Singleton class.
Open up the link for the Singleton code "SingletonLazyInnerClassExample.java.txt" above in a new window so you can look at the code. The "NormalClass.java" was converted to the Singleton "SingletonLazyInnerClassExample.java.txt". You can compare this code to the "NormalClass.java" code.
Notice that the constructor is private so it can't be instantiated.

private SingletonLazyInnerClassExample() {}

This approach is different from the others in that the variable for the instance is not defined in the main class. Notice that it is defined and instantiated in an inner class. The inner class is not accessed until it is needed so this becomes "Lazy-Loading" only if needed.

private static class SingletonHolder {
public static final SingletonLazyInnerClassExample instance = new SingletonLazyInnerClassExample();
}

The only way to get a reference to an instance of the class is to call the getInstance() method. Because it just returns the instance that was created in the inner class called "SingletonHolder" via SingletonHolder.instance there is only one instance of the class. Because it is an inner class the JVM doesn't create the instance until the code is accessed therefore it is "Lazy-Loading".

public static SingletonLazyInnerClassExample getInstance() {
return SingletonHolder.instance;
}
That is it. All the other code remains the same from the original class ("NormalClass.java") that we are changing into a Singleton.

Now open up the link for SingletonExampleTest.java.txt so you can look at the JUnit code.

@Test
public void testSingletonInnerClassExample() {
    SingletonLazyInnerClassExample object1 = SingletonLazyInnerClassExample.getInstance();
    object1.setName("Hello");
    SingletonLazyInnerClassExample object2 = SingletonLazyInnerClassExample.getInstance();
    object2.setName("World");
    assertTrue(object1 == object2);
    assertEquals("World", object1.getName());
    assertEquals("World", object2.getName());
}

Note how object1 and object2 is instantiated.
If you look at the 3 JUnit assets you notice that there is one and only one object that was created.