Page History

The singleton design pattern's intent is succinctly described by the seminal work of Gamma et al. and colleagues [Gamma 1995]:

Ensure a class only has one instance, and provide a global point of access to it.

Because there is only one Singleton singleton instance, "any instance fields of a Singleton will occur only once per class, just like static fields. Singletons often control access to resources such as database connections or sockets" [Fox 2001]. Other applications of singletons involve maintaining performance statistics, system monitoring and logging system activity, implementing printer spoolers, or and even tasks such as ensuring that only one audio file plays at a time. Classes that contain only static methods are good candidates for the Singleton pattern.

...

A class that implements the singleton design pattern must prevent multiple instantiations. Relevant techniques include the following:

• making Making its constructor private.
• employing Employing lock mechanisms to prevent an initialization routine from running being run simultaneously by multiple threads.
• ensuring Ensuring the class is not serializable.
• ensuring Ensuring the class cannot be cloned.
• preventing Preventing the class from being garbage-collected if it was loaded by a custom class loader.

Noncompliant Code Example (

...

Nonprivate Constructor)

This noncompliant code example uses a non-private nonprivate constructor for instantiating a singleton.:

class MySingleton {
  private static MySingleton Instanceinstance;

  protected MySingleton() {    
    Instanceinstance = new MySingleton();
  }

  public static synchronized MySingleton getInstance() {    
    return Instanceinstance;
  }
}

A malicious subclass may extend the accessibility of the constructor from protected to public, allowing untrusted code to create multiple instances of the singleton. Also, the class field Instance has not been declared final.

...

class MySingleton {
  private static final MySingleton Instanceinstance = new MySingleton();

  private MySingleton() {    
    // privatePrivate constructor prevents instantiation by untrusted callers
  }

  public static synchronized MySingleton getInstance() {    
    return Instanceinstance;
  }
}

The MySingleton class need not be declared final because it has a private constructor.

(Note that the initialization of instance  is done when MySingleton  is loaded, consequently it is protected by the class's initialization lock. See the JLS s12.4.2 for more information.)

Noncompliant Code Example (Visibility Noncompliant Code Example (Visibility across Threads)

Multiple instances of the Singleton class can be created when the getter method is tasked with initializing the singleton when necessary, and the getter method is invoked by two or more threads simultaneously.

class MySingleton {
  private static MySingleton Instanceinstance;

  private MySingleton() {    
    // privatePrivate constructor prevents instantiation by untrusted callers
  }

  // Lazy initialization
  public static MySingleton getInstance() { // Not synchronized
    if (Instanceinstance == null) {
      Instanceinstance = new MySingleton();
    }
    return Instanceinstance;
  }
}

A singleton initializer method in a multithreaded program must employ some form of locking to prevent construction of multiple singleton objects.

...

Multiple instances can be created even when the singleton construction is encapsulated in a synchronized block., as in this noncompliant code example:

public static MySingleton getInstance() {
  if (Instanceinstance == null) {
    synchronized (MySingleton.class) {
      Instanceinstance = new MySingleton();
    }
  }
  return Instanceinstance;
}

This is because The reason multiple instances can be created in this case is that two or more threads may simultaneously see the field Instance instance as null in the if condition and enter the synchronized block one at a time.

...

To address the issue of multiple threads creating more than one instance of the singleton, make getInstance() a synchronized method.:

class MySingleton {
  private static MySingleton Instanceinstance;

  private MySingleton() {
    // privatePrivate constructor prevents instantiation by untrusted callers
  }

  // Lazy initialization
  public static synchronized MySingleton getInstance() {
    if (Instanceinstance == null) {
      Instanceinstance = new MySingleton();
    }
    return Instanceinstance;
  }
}

Compliant Solution (Double-Checked Locking)

Another compliant solution for implementing thread-safe singletons is the correct use of the double-checked locking idiom.:

class MySingleton {
  private static volatile MySingleton Instanceinstance;

  private MySingleton() {
    // privatePrivate constructor prevents instantiation by untrusted callers
  }

  // Double-checked locking
  public static MySingleton getInstance() {
    if (Instanceinstance == null) {
      synchronized (MySingleton.class) {
        if (Instanceinstance == null) {
          Instanceinstance = new MySingleton();
        }
      }
    }
    return Instanceinstance;
  }
}

This design pattern is often implemented incorrectly . Refer to rule (see LCK10-J. Do not use incorrect forms Use a correct form of the double-checked locking idiom for more details on the correct use of the double-checked locking idiom).

Compliant Solution (Initialize-on-Demand Holder Class Idiom)

This compliant solution uses a static inner class to create the singleton instance.:

class MySingleton {
  static class SingletonHolder {
    static final MySingleton Instanceinstance = new MySingleton();
  }

  public static MySingleton getInstance() {
    return SingletonHolder.Instanceinstance;
  }
}

This approach is known as the initialize-on-demand holder class idiom. Refer to rule  (see LCK10-J. Do not use incorrect forms Use a correct form of the double-checked locking idiom for more information).

Noncompliant Code Example (Serializable)

...

class MySingleton implements Serializable {
  private static final long serialVersionUID = 6825273283542226860L;
  private static MySingleton Instanceinstance;

  private MySingleton() {
    // privatePrivate constructor prevents instantiation by untrusted callers
  }

  // Lazy initialization
  public static synchronized MySingleton getInstance() {
    if (Instanceinstance == null) {
      Instanceinstance = new MySingleton();
    }
    return Instanceinstance;
  }
}

A singleton's constructor cannot install checks to enforce the requirement that the class is instantiated only instantiated once because deserialization can bypass the object's constructor.

...

Adding a readResolve() method that returns the original instance is insufficient to enforce the singleton property. This technique is insecure even when all the fields are declared transient or static.

class MySingleton implements Serializable {
  private static final long serialVersionUID = 6825273283542226860L;
  private static MySingleton Instanceinstance;

  private MySingleton() {
    // privatePrivate constructor prevents instantiation by untrusted callers
  }

  // Lazy initialization
  public static synchronized MySingleton getInstance() {
    if (Instanceinstance == null) {
      Instanceinstance = new MySingleton();
    }
    return Instanceinstance;
  }

  private Object readResolve() {
    return Instanceinstance; 
  }
}

At runtime, an attacker can add a class that reads in a crafted serialized stream:

...

Upon deserialization, the field MySingleton.untrusted is reconstructed before MySingleton.readResolve() is called. Consequently, Untrusted.captured is assigned the deserialized instance of the crafted stream instead of MySingleton.Instanceinstance. This issue is pernicious when an attacker can add classes to exploit the singleton guarantee of an existing serializable class.

Noncompliant Code Example (

...

Nontransient Instance Fields)

This serializable noncompliant code example uses a non-transient nontransient instance field str.:

class MySingleton implements Serializable {
  private static final long serialVersionUID =
      2787342337386756967L;
  private static MySingleton Instanceinstance;
  
  // non-transientNontransient instance field 
  private String[] str = {"one", "two", "three"}; 
                 
  private MySingleton() {
    // privatePrivate constructor prevents instantiation by untrusted callers
  }

  public void displayStr() {
    System.out.println(Arrays.toString(str));
  }
 
  private Object readResolve() {
    return Instanceinstance;
  }
}

"If a singleton contains a nontransient object reference field, the contents of this field will be deserialized before the singletonâ���������������€š�š�š�š�š�š�š����������������€š�š�š�š�š�š�z�s singleton'€™s readResolve method is run. This allows a carefully crafted stream to 'steal' a reference to the originally deserialized singleton at the time the contents of the object reference field are deserialized" [Bloch 2008].

Compliant Solution (Enumeration Types)

Stateful singleton classes must be nonserializable. As a precautionary measure, classes that are serializable must not save a reference to a singleton object in their nontransient or nonstatic instance variables. This precaution prevents the singleton from being indirectly serialized.

Bloch [Bloch 2008] suggests the use of an enumeration type as a replacement for traditional implementations when serializable singletons are indispensable.

public enum MySingleton {
  ; // emptyEmpty list of enum values

  private static MySingleton Instanceinstance;

  // non-transientNontransient field
  private String[] str = {"one", "two", "three"};

  public void displayStr() {
    System.out.println(Arrays.toString(str));
  }	 
}

...

class MySingleton implements Cloneable {
  private static MySingleton Instanceinstance;

  private MySingleton() {
    // privatePrivate constructor prevents
    // instantiation by untrusted callers
  }

  // Lazy initialization
  public static synchronized MySingleton getInstance() {
    if (Instanceinstance == null) {
      Instanceinstance = new MySingleton();
    }
    return Instanceinstance;
  }
}

Compliant Solution (Override clone() Method)

Avoid To avoid making the singleton class cloneable by , do not implementing implement the Cloneable interface and do not deriving derive from a class that already implements it.

When the singleton class must indirectly implement the Cloneable interface through inheritance, the object's clone() method must be overridden with one that throws a CloneNotSupportedException exception [Daconta 2003].

class MySingleton implements Cloneable {
  private static MySingleton Instanceinstance;

  private MySingleton() {
    // privatePrivate constructor prevents instantiation by untrusted callers
  }

  // Lazy initialization
  public static synchronized MySingleton getInstance() {
    if (Instanceinstance == null) {
      Instanceinstance = new MySingleton();
    }
    return Instanceinstance;
  }

  public Object clone() throws CloneNotSupportedException {
    throw new CloneNotSupportedException();
  }
}

See rule OBJ07-J. Sensitive classes must not let themselves be copied for more details about preventing misuse of the clone() method.

...

A static singleton becomes eligible for garbage collection when its class loader becomes eligible for garbage collection. This usually happens when a nonstandard (custom) class loader is used to load the singleton. This noncompliant code example prints different values of the hash code of the singleton object from different scopes.:

  {
  ClassLoader cl1 = new MyClassLoader();
  Class class1 = cl1.loadClass(MySingleton.class.getName());
  Method classMethod = 
      class1.getDeclaredMethod("getInstance", new Class[] { });
  Object singleton = classMethod.invoke(null, new Object[] { });
  System.out.println(singleton.hashCode());
}

ClassLoader cl1 = new MyClassLoader();
Class class1 = cl1.loadClass(MySingleton.class.getName());
Method classMethod = 
    class1.getDeclaredMethod("getInstance", new Class[] { });
Object singleton = classMethod.invoke(null, new Object[] { } );
System.out.println(singleton.hashCode());

Code that is outside the scope can create another instance of the singleton class even though the requirement was to use only the original instance. 

Because a singleton instance is associated with the class loader that is used to load it, it is possible to have multiple instances of the same class in the JVMJava Virtual Machine. This situation typically happens occurs in J2EE containers and applets. Technically, these instances are different classes that are independent of each other. Failure to protect against multiple instances of the singleton may or may not be insecure depending on the specific requirements of the program.

...

This compliant solution demonstrates this technique. It prints a consistent hash code across all scopes. It uses the ObjectPreserver class [Grand 2002] described in rule TSM02-J. Do not use background threads during class initialization.

...

Using improper forms of the singleton Singleton design pattern may lead to creation of multiple instances of the singleton and violate the expected contract of the class.

Automated Detection

...

Related Guidelines

Bibliography

...

Image Removed      49. Miscellaneous (MSC)      Image Added Image Added Image Added