Singleton pattern

Introduction

The Singleton pattern restricts a class to one instance within a defined scope and provides a way to access that instance. The scope matters: a manual singleton is usually one instance per class loader or process, while a dependency-injection container may define one instance per application context.

TL;DR / mental model: Make construction private, centralize instance creation, and make the lifecycle explicit. Use a singleton only when uniqueness is a real resource or coordination requirement; prefer dependency injection so callers receive the dependency instead of fetching global state.

Problem and Context

You need exactly one database connection pool for your entire application. Multiple pools would waste memory, exhaust database connections, and create inconsistent state. The naive solution looks simple but breaks under concurrency.

If two threads call getInstance() at the same moment, both see null, both create a pool, and one silently overwrites the other. You now have two pools, leaked connections, and a mystery production bug. This is the race condition every singleton discussion starts with.

The pattern seems trivial until you consider thread safety, serialization, reflection, and testability. Those four concerns separate a working singleton from a broken one.

Here is what changes when you apply the Singleton pattern.

When It Helps

Use it when multiple instances would represent the same process-wide resource or coordination point, such as a connection pool or hardware handle. If uniqueness is merely convenient, a regular object managed by dependency injection is usually easier to test and replace.

Participants and Structure

The private constructor prevents anyone from calling new. The Holder inner class leverages the JVM's class-loading guarantee: a class is initialized exactly once, and initialization is thread-safe without explicit synchronization. The pool is created only when getInstance() is first called (lazy) and only once (thread-safe).

Idiomatic Example and Implementation Notes

The examples below show three common approaches. Each solves a different set of concerns, so choose based on initialization timing, inheritance, serialization, reflection, and testability rather than on a single universal ranking.

// APPROACH 1: Initialization-on-demand holder idiom.
// Lazy, thread-safe, no synchronized keyword, no volatile.
// The JVM spec (§12.4.2) guarantees class initialization
// is atomic and happens-before any thread reads static fields.
public class DatabaseConnectionPool {
  private final String jdbcUrl;
  private final int poolSize;

  // Private constructor: nobody outside can instantiate
  private DatabaseConnectionPool() {
      this.jdbcUrl = System.getenv("DB_URL");
      this.poolSize = Integer.parseInt(
          System.getenv().getOrDefault("POOL_SIZE", "10"));
      System.out.println("Pool created with " + poolSize + " connections");
  }

  // Inner class is NOT loaded until getInstance() is called.
  // When it IS loaded, JVM guarantees single-threaded init.
  private static final class Holder {
      static final DatabaseConnectionPool INSTANCE =
          new DatabaseConnectionPool();
  }

  public static DatabaseConnectionPool getInstance() {
      return Holder.INSTANCE;
  }

  public String getJdbcUrl() { return jdbcUrl; }
  public int getPoolSize() { return poolSize; }
}

The Testability Problem

The larger design concern is often testability. A singleton creates hidden global state, so unit tests can depend on each other unless that state is carefully reset. Thread safety is a separate implementation concern that can be addressed by several approaches.

// Problem: tests that use ConfigService.getInstance() share state.
// Test A modifies the singleton, Test B runs next and unexpectedly
// sees Test A's changes. Test order matters. Parallel tests break.

// Solution: Dependency Injection. Pass the instance, don't fetch it.
public class OrderService {
    private final ConfigService config; // injected, not fetched

    // Constructor injection: tests control which instance is used
    public OrderService(ConfigService config) {
        this.config = config;
    }

    public int getMaxRetries() {
        return Integer.parseInt(config.get("max.retries"));
    }
}
// In production: new OrderService(ConfigService.getInstance())
// In tests:      new OrderService(mockConfigService)

The key design insight is to use dependency injection so the singleton is wired at the composition root. Classes receive their dependencies; they do not fetch global state from inside business methods.

How It Works, Step by Step

The sequence diagram shows the holder idiom under concurrent access. JVM class initialization supplies the synchronization for this holder, so no additional application-level lock is needed for instance creation.

1. Thread A calls getInstance(), which references Holder.INSTANCE for the first time.
2. The JVM loads the Holder class. The JVM specification guarantees this happens atomically. No application synchronization needed.
3. During class loading, INSTANCE is initialized. The DatabaseConnectionPool constructor runs exactly once.
4. Thread B calls getInstance() concurrently. If class loading is in progress, Thread B blocks on the JVM's internal lock. If done, Thread B reads the fully-constructed instance.
5. Both threads get the same instance. The happens-before relationship of class initialization guarantees all fields are visible.

Real-World Examples

• java.lang.Runtime.getRuntime() returns the singleton Runtime instance. There is exactly one runtime per JVM process, managing memory and external processes.
• Spring's default bean scope is singleton. When you annotate a class with @Service, Spring normally creates one instance per application context and injects it where needed. This is singleton scope managed by a DI container, not a manual getInstance() implementation.
• SLF4J's LoggerFactory maintains a singleton logging framework binding. One binding per application, selected at startup, used by every class that calls LoggerFactory.getLogger().
• java.awt.Desktop.getDesktop() returns a singleton representing the user's desktop environment. Only one desktop exists per user session.

Trade-offs, Alternatives, and When Not to Use

Use when:

• The resource is inherently singular (connection pool, thread pool, hardware interface)
• Creating multiple instances would cause resource exhaustion or state conflicts
• You need a global coordination point (registry, cache, configuration)

Skip when:

• You want testability but would otherwise make callers fetch global state (use DI to inject the instance)
• The class has mutable state that tests modify (tests will interfere with each other)
• You are using it as a glorified global variable to avoid passing parameters

The trade-off is centralized uniqueness in exchange for global-state coupling, lifecycle complexity, and harder substitution when callers invoke getInstance() directly. Alternatives include a regular object with one instance wired at the composition root, a static stateless utility for pure functions, or a provider/factory when instances may vary by scope. If the resource is truly singular, singleton scope can make sense; a DI container can usually manage that scope more safely than scattered manual access.

30-Second Explanation

A Singleton restricts construction so one instance exists within a chosen scope, then exposes access to that instance. The hard parts are safe initialization, visibility, serialization, reflection, lifecycle, and testability. In modern applications, dependency injection often provides singleton scope while keeping dependencies explicit.

5-Minute Explanation

Start with a private constructor and a static access path. The initialization-on-demand holder idiom uses JVM class initialization for lazy, thread-safe creation; double-checked locking can also work when the instance is volatile; an enum gets special serialization and reflection behavior but cannot extend another class. The pattern is appropriate for genuinely unique resources, not as a shortcut for passing dependencies. If callers use getInstance() throughout the codebase, hidden global state makes tests and replacement harder, so inject the singleton from the composition root instead.

Common Mistakes and Misconceptions

1. Writing the broken version and calling it done. The naive if (instance == null) check is not thread-safe. Contrast it with a safe approach and make the initialization guarantee explicit.

2. Using synchronized on the entire method without considering the trade-off. Synchronizing the whole method is simple and correct, but it serializes access to the method. Double-checked locking can avoid repeated lock acquisition after initialization, while the holder idiom is often simpler for a no-argument singleton.

3. Forgetting volatile in double-checked locking. Without volatile, safe publication is not established and another thread may observe a non-null reference without the constructor's writes being safely visible. The field must be volatile for the standard pattern.

4. Ignoring testability. A correct initialization strategy does not remove the hidden dependency created by getInstance() calls. Prefer constructor injection so tests can provide a controlled instance.

5. Treating enum singleton as interchangeable with every other approach. Enum singleton handles Java's enum serialization and reflective-construction rules with little boilerplate, but it cannot extend another class and is initialized with the enum class. The holder idiom is more flexible about inheritance and initialization timing.

Test Your Understanding

Recap

1. The naive if (instance == null) singleton has a race condition. Two threads can create two instances if they interleave at the null-check.
2. The Holder idiom (inner static class) is lazy, thread-safe, and needs no synchronized or volatile. It relies on the JVM's class-loading guarantee.
3. Double-checked locking needs volatile to prevent partial construction visibility. Without it, another thread can see a non-null but incomplete object.
4. Enum singleton benefits from Java's special serialization and reflective-construction rules, but it cannot extend another class and is not as flexible about initialization.
5. Testability is a major design concern: global state can make unit tests depend on one another and can hide dependencies.
6. Use dependency injection to manage singleton scope when possible. The container defines the scope and injects the instance where needed.
7. Choose among Holder, double-checked locking, enum, or container-managed scope based on initialization, inheritance, serialization, reflection, and testability requirements.

Related Patterns and Alternatives

The key takeaway: static classes are for stateless utilities. Singletons are for stateful resources that must be unique. DI-managed singleton scope is often a useful application choice because the framework can handle lifecycle and injection.