Page History

class MySingleton {
  private static MySingleton instance;

  protected MySingleton Gamma et al. \[[Gamma 1995|AA. Bibliography#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 2001|AA. Bibliography#Fox 01]\]. Other applications of singletons involve maintaining performance statistics, system monitoring and logging, implementing printer spoolers or even ensuring that only one audio file plays at a time. Classes that contain only {{static}} methods are good candidates for the singleton pattern. 

The Singleton pattern typically uses a single instance of a class that encloses a {{private static}} class 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 (Non-Private Constructor)

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

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

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

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

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 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}

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

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}

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

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 unsynchronized.

{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 when 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 address 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) (

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(Arrays.toString(str));
  }
 
  private Object readResolve() {
    return instance;
  }
}

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

  private static MySingleton instance;

  // Nontransient field class.

h2. Compliant Solution ({{enum}} Types)

Stateful singleton classes should be made non-serializable. As a precautionary measure, classes that are serializable are forbidden to save a reference to a singleton object in their non-transient or non-static instance variables. This prevents the singleton from being indirectly serialized. 

Bloch \[[Bloch 2008|AA. Bibliography#Bloch 08]\] suggests the use of an {{enum}} type as a replacement for traditional implementations when serializable singletons are indispensable. 

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

This approach is functionally equivalent to, but much safer than, commonplace implementations. It both ensures that only one instance of the object exists at any instant and also provides the serialization property (because {{java.lang.Enum<E>}} extends {{java.io.Serializable}}).


h2. Noncompliant Code Example (Non-Transient Instance Fields)

This serializable noncompliant code example uses a non-transient 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"}; // non-transient instance field

  public void displayStr() {
            
  private MySingleton() {System.out.println(Arrays.toString(str));
    // private constructor prevents instantiation by untrusted callers
  }

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

"If a singleton contains a nontransient object reference field, the contents of this field will be deserialized before 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 2008|AA. Bibliography#Bloch 08]\].

h2. Noncompliant Code Example (Transient Fields)

This noncompliant code example declares the {{str}} instance field as {{transient}} so that it is not serialized.

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

However, this is still insecure because of reasons described in the noncompliant code example ({{readResolve()}} method).

h2. Compliant Solution ({{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"}; // non-transient 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 (INSTANCE == null) {
      INSTANCE = new MySingleton();
    }
    return INSTANCE;
  }
}
{code}

h2. Compliant Solution (Override {{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 2003|AA. Bibliography#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 rule [OBJ03-J. Sensitive classes must not let themselves be copied] for more details about restricting misuse of the {{clone()}} method.


h2. Noncompliant Code Example (Garbage Collection)

When a class is no longer reachable, it is free to be garbage collected. This behavior can be troublesome when the program must maintain the singleton property throughout the entire lifetime of the program. 

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 hashcode of the singleton object from different scopes. 

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

{mc}
back-up code
  {
    ClassLoader cl1 = new FirstClassLoader();
    Class class1 = cl1.loadClass(MySingleton.class.getName());
    Method instanceMethod = class1.getDeclaredMethod("getInstance", new Class[] { });
    Object singleton = instanceMethod.invoke(null, new Object[] { } );
  }
  ClassLoader cl2 = new SecondClassLoader();
  Class class2 = cl2.loadClass(MySingleton.class.getName());
  Method instanceMethod = class2.getDeclaredMethod("getInstance", new Class[] { });
  Object singleton = instanceMethod.invoke(null, new Object[] { } );
	
{mc}

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.


{mc}
// The following class produces the same hashcode from different scopes, so is safe

public class StaticClass {
  public void doSomething() {
     {
       MySingleton ms = new MySingleton();
       Object singleton = ms.getInstance();
       System.out.println(singleton.hashCode());
     }
       MySingleton ms = new MySingleton();
       Object singleton = ms.getInstance();
       System.out.println(singleton.hashCode());
  }
  
  public static void main(String[] args) {
    StaticClass sc = new StaticClass();
    sc.doSomething();
  }
}
{mc}

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 JVM. This typically happens in J2EE containers and applets. Technically, these instances are different classes that are independent of each other. Failing to protect against multiple instances of the singleton may or may not be insecure depending on the specific requirements of the program.

h2. Compliant Solution (Prevent Garbage Collection)

This compliant solution takes into account the garbage collection issue described above. A class is cannot be 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 must be preserved. 

This compliant solution demonstrates this technique. It prints a consistent hashcode across all scopes.  It uses the {{ObjectPreserver}} class based on \[[Grand 2002|AA. Bibliography#Grand 02]\] and described in rule [TSM02-J. Do not use background threads during class initialization].

{code:bgColor=#ccccff}
  {
    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[] { });
  Object singleton = ObjectPreserver.getObject();  // Retrieve the preserved object
  System.out.println(singleton.hashCode());
{code}


h2. Risk Assessment

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

|| Rule || Severity || Likelihood || Remediation Cost || Priority || Level ||
| MSC16-J | low | unlikely | medium | {color:green}{*}P2{*}{color} | {color:green}{*}L3{*}{color} |


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. Bibliography

\[[JLS 2005|AA. Bibliography#JLS 05]\] [Chapter 17, Threads and Locks|http://java.sun.com/docs/books/jls/third_edition/html/memory.html]
\[[Fox 2001|AA. Bibliography#Fox 01]\] [When is a Singleton not a Singleton?|http://java.sun.com/developer/technicalArticles/Programming/singletons/]&nbsp;
\[[Daconta 2003|AA. Bibliography#Daconta 03]\] Item 15: Avoiding Singleton Pitfalls;
\[[Darwin 2004|AA. Bibliography#Darwin 04]\] 9.10 Enforcing the Singleton Pattern
\[[Gamma 1995|AA. Bibliography#Gamma 95]\] Singleton
\[[Grand 2002|AA. Bibliography#Grand 02]\] Chapter 5, Creational Patterns, Singleton
\[[Bloch 2008|AA. Bibliography#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 2009|AA. Bibliography#MITRE 09]\] [CWE ID 543|http://cwe.mitre.org/data/definitions/543.html] "Use of Singleton Pattern Without Synchronization in a Multithreaded Context"

----
[!The CERT Oracle Secure Coding Standard for Java^button_arrow_left.png!|MSC15-J. Use numeric comparison operators to terminate loops whose counter changes by more than one]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[!The CERT Oracle Secure Coding Standard for Java^button_arrow_up.png!|49. Miscellaneous (MSC)]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[!The CERT Oracle Secure Coding Standard for Java^button_arrow_right.png!|MSC17-J. Detect and remove dead code]

}	 
}

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

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