Page History

 Gamma et al. \[[Gamma 95|AA. Java References#Gamma 95]\]:

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

"Since there is only one 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 01|AA. Java References#Fox 01]\]. Other applications of singletons involve maintaining performance statistics, system monitoring and logging, implementing printer spoolers or as simple as ensuring that only one audio file plays at a time. 

Typically, the Singleton pattern uses a single instance of a class that encloses a {{private static}} instance field. The instance can be created using _lazy initialization_, which means that the instance is not created when the class loads but when it is first used.

h2. Noncompliant Code Example (nonprivate constructor)

This noncompliant code example uses a nonprivate constructor for instantiating a singleton.

{code:bgColor=#FFcccc}
class MySingleton {
  private static MySingleton INSTANCEinstance;

  protected MySingleton() {    
    // private constructor prevents instantiation by untrusted callers
    INSTANCE instance = new MySingleton();
  }

  public static synchronized MySingleton getInstance() {    
    return INSTANCEinstance;
  }
}
{code}

 field {{INSTANCE}} has not been declared as {{final}}.

h2. Compliant Solution ({{private}} constructor)

This compliant solution reduces the accessibility of the constructor to {{private}} and initializes the field {{INSTANCE}} immediately, allowing it to be declared {{final}}.

{code:bgColor=#ccccff}
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;
  }
}

{code}

h2. Noncompliant Code Example (visibility across threads)

When the getter method is called by two (or more) threads simultaneously, multiple instances of the {{Singleton}} class might result if access is not synchronized.

{code:bgColor=#FFcccc}
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;
  }
}
{code}

h2. Noncompliant Code Example (inappropriate synchronization)

Multiple instances can be created even if the singleton construction is encapsulated in a {{synchronized}} block.

{code:bgColor=#FFcccc}
public static MySingleton getInstance() {
  if (INSTANCEinstance == null) {
    synchronized (MySingleton.class) {
      INSTANCEinstance = new MySingleton();
    }
  }
  return INSTANCEinstance;
}
{code}

This is because two or more threads may simultaneously see the field {{INSTANCE}} as {{null}} in the {{if}} condition and enter the synchronized block one at a time.

h2

. Compliant Solution (1) ({{synchronized}} method)

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

{code:bgColor=#ccccff}
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;
  }
}

{code}

h2. Compliant Solution (2) (double-checked locking)

Another solution for implementing thread-safe singletons is the double-checked locking idiom.  

{code:bgColor=#ccccff}
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;
  }
}
{code}

class MySingleton {
  static class SingletonHolder {
    static MySingleton instance = new MySingleton();
  }

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

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

h2. Noncompliant Code Example (Serializable singleton)

This noncompliant code example implements the {{java.io.Serializable}} interface which allows the class to be serializable. Deserialization of the class implies that multiple instances of the singleton can be created.

{code:bgColor=#FFcccc}
class MySingleton implements Serializable {
  private static final long serialVersionUID = 6825273283542226860L;
  private static MySingleton INSTANCE;

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

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

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

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

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

  private Object readResolve() {
    return instance; 
  }
}

public class Untrusted implements Serializable {
  public static MySingleton captured;
  public MySingleton capture;
  
  public Untrusted(MySingleton capture) {
    this.capture = capture;
  }

  private void readObject(java.io.ObjectInputStream in)
                          throws Exception {
    in.defaultReadObject();
    captured = capture;
  }
}

public final class MySingleton
                   implements java.io.Serializable {
  private static final long serialVersionUID =
      6825273283542226860L;
  public Untrusted untrusted =
      new Untrusted(this); // Additional serial field
 
  public MySingleton() { }
}

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

  public void displayStr() {
    System.out.println(

h2. Compliant Solution (1) ({{readResolve}} method)

It is recommended that stateful singleton classes be made non-serializable. As a precautionary measure, classes that are serializable must never save a reference to a singleton object in their nontransient or nonstatic instance variables. This prevents the singleton from being indirectly serialized. 

If making a singleton class serializable is indispensable, ensure that only one instance of the class exists by adding a {{readResolve()}} method which can be made to return the original instance. The phantom instance obtained after deserialization is left to the judgment of the garbage collector. \[[Bloch 08|AA. Java References#Bloch 08]\]

{code:bgColor=#ccccff}
private Object readResolve() {
  return INSTANCE;
}
{code} 

If the serializable singleton class has any other instance fields, they must be declared {{transient}} to be compliant (described later in the nontransient instance fields noncompliant code example). 

h2. Compliant Solution (2) ({{enum}} types)

Bloch \[[Bloch 08|AA. Java References#Bloch 08]\] suggests the use of an {{enum}} type as a replacement for traditional implementations. 

{code:bgColor=#ccccff}
public enum MySingleton {
  INSTANCE;
  // Other methods
}
{code}

Functionally, this approach is equivalent to commonplace implementations and is safer. It ensures that only one instance of the object exists at any instant and also provides the serialization property as {{java.lang.Enum<E>}} extends {{java.io.Serializable}}.


h2. Noncompliant Code Example (nontransient instance fields)

This serializable noncompliant code example uses a nontransient instance field {{str}}.

{code:bgColor=#FFcccc}
class MySingleton implements Serializable {
  private static final long serialVersionUID = 2787342337386756967L;
  private static MySingleton INSTANCE;
  private String[] str = {"one", "two", "three"}; // nontransient instance field
                 
  private MySingleton() {
    // private constructor prevents instantiation by untrusted callers
  }

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

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

  private static MySingleton instance;

  // Nontransient field
  private the 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 08|AA. Java References#Bloch 08]\].

h2. Compliant Solution (1) (transient fields)

This compliant solution declares the {{str}} instance field as {{transient}} so that it is not serialized.

{code:bgColor=#ccccff}
class MySingleton implements Serializable {
  // ...
  private transient String[] str = {"one", "two", "three"};

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

class MySingleton implements Cloneable {
  private static MySingleton instance;

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

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

class MySingleton implements Cloneable {
  private static MySingleton instance;

  private MySingleton() {
    // Private // nontransient field
  // ...
}
{code}

h2. Compliant Solution (2) ({{enum}} types, non-transient fields)

This compliant solution uses the {{enum}} type to ensure that only one instance of the singleton exists at any time.

{code:bgColor=#ccccff}
public enum MySingleton {
  INSTANCE;
  private String[] str = {"one", "two", "three"}; // nontransient field
     
  public void displayStr() {
    System.out.println(Arrays.toString(str));
  }	 
}
{code}

h2. Noncompliant Code Example (Cloneable singleton)

It is also possible to create a copy of the singleton by cloning it using the object's {{clone()}} method if the singleton class implements {{java.lang.Cloneable}} directly or through inheritance. This noncompliant code example shows a singleton that implements the {{java.lang.Cloneable}} interface.

{code:bgColor=#FFcccc}
class MySingleton implements Cloneable {
  private static MySingleton INSTANCE;

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

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

h2. Compliant Solutionpublic (overrideObject {{clone()}} method)

Avoid making the singleton class cloneable by not implementing the {{Cloneable}} interface or not deriving from a class that already implements it. 

If the singleton class indirectly implements the {{Cloneable}} interface through inheritance, override the object's {{clone()}} method and throw a {{CloneNotSupportedException}} exception from within it \[[Daconta 03|AA. Java References#Daconta 03]\].

{code:bgColor=#ccccff}
class MySingleton implements Cloneable {
  private static MySingleton INSTANCE;

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

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

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

See [MSC05-J. Make sensitive classes noncloneable] for more details about restricting the {{clone()}} method.


h2. Noncompliant Code Example

When the utility of a class is over, it is free to be garbage collected. A dynamic reference can however, cause another instance of the singleton class to be returned. This behavior can be troublesome when the program needs to maintain only one instance throughout its lifetime.  
{mc} what kind of an NCE do we show here? {mc}

h2. Compliant Solution

This compliant solution takes into account the garbage collection issue described above. A class is not garbage collected until the {{ClassLoader}} object used to load it becomes eligible for garbage collection. An easier scheme to prevent the garbage collection is to ensure that there is a direct or indirect reference from a live thread to the singleton object that needs to be preserved. This compliant solution demonstrates this method (adopted from \[[Patterns 02|AA. Java References#Patterns 02]\]). 

{code:bgColor=#ccccff}
public class ObjectPreserver implements Runnable {
  private static ObjectPreserver lifeLine = new ObjectPreserver();
  
  // Neither this class, nor HashSet will be garbage collected.
  // References from HashSet to other objects will also exhibit this property
  private static HashSet protectedSet = new HashSet();
 
  private ObjectPreserver() {
    new Thread(this).start();  // keeps the reference alive
  }
 
  public synchronized void run(){
    try {
      wait();
    } catch(InterruptedException e) { /* Forward to handler */ }
  }

  // Objects passed to this method will be preserved until
  // the unpreserveObject method is called
  public static void preserveObject(Object o) {
    protectedSet.add(o);
  }

  // Unprotect the objects so that they can be garbage collected
  public static void unpreserveObject(Object o) {
    protectedSet.remove(o);
  }
}
{code} 

To be fully compliant, it must be ensured that the class obeys the _Singleton_ pattern's design contract. It is unreasonable to use the class for anything else, for example, as a method to share global state. \[[Daconta 03|AA. Java References#Daconta 03]\]

h2. Risk Assessment

Using lazy initialization in a Singleton without synchronizing the {{getInstance()}} method may lead to creation of multiple instances and can as a result, violate the expected contract.
|| Rule || Severity || Likelihood || Remediation Cost || Priority || Level ||
| CON23- J | low | unlikely | medium | {color:green}{*}P2{*}{color} | {color:green}{*}L3{*}{color} |

h3. Automated Detection

TODO

h3. Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the [CERT website|https://www.kb.cert.org/vulnotes/bymetric?searchview&query=FIELD+KEYWORDS+contains+CON32-J].


h2. References

\[[JLS 05|AA. Java References#JLS 05]\] [Chapter 17, Threads and Locks|http://java.sun.com/docs/books/jls/third_edition/html/memory.html]
\[[Fox 01|AA. Java References#Fox 01]\] [When is a Singleton not a Singleton?|http://java.sun.com/developer/technicalArticles/Programming/singletons/] 
\[[Daconta 03|AA. Java References#Daconta 03]\] Item 15: Avoiding Singleton Pitfalls;
\[[Darwin 04|AA. Java References#Darwin 04]\] 9.10 Enforcing the Singleton Pattern
\[[Gamma 95|AA. Java References#Gamma 95]\] Singleton
\[[Patterns 02|AA. Java References#Patterns 02]\] Chapter 5, Creational Patterns, Singleton
\[[Bloch 08|AA. Java References#Bloch 08]\] Item 3: "Enforce the singleton property with a private constructor or an enum type" and Item 77: "For instance control, prefer enum types to readResolve"
\[[MITRE 09|AA. Java References#MITRE 09]\] [CWE ID 543|http://cwe.mitre.org/data/definitions/543.html] "Use of Singleton Pattern in a Non-thread-safe Manner"

----
[!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_left.png!|CON22-J. Do not use incorrect forms of the double-checked locking idiom]      [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_up.png!|11. Concurrency (CON)]      [!The CERT Sun Microsystems Secure Coding Standard for Java^button_arrow_right.png!|CON24-J. Use a unique channel to acquire locks on any file]

 throws CloneNotSupportedException {
    throw new CloneNotSupportedException();
  }
}

  {
  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());

 {
  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[] { });
  ObjectPreserver.preserveObject(singleton); // Preserve the object
  System.out.println(singleton.hashCode());
}

ClassLoader cl1 = new MyClassLoader();
Class class1 = cl1.loadClass(MySingleton.class.getName());
Method classMethod = 
    class1.getDeclaredMethod("getInstance", new Class[] { });
// Retrieve the preserved object
Object singleton = ObjectPreserver.getObject();  
System.out.println(singleton.hashCode());