Gof Singleton

Singleton

Purpose

Treat this pattern as a request to justify global state. Singleton bundles two separate decisions — there is one instance and anyone can reach it without being given it — and the second is what causes the damage. It hides dependencies from constructors, so a type's real collaborators are invisible; it fixes initialisation order in ways nobody chose; it makes tests order-dependent; and it silently promises a uniqueness that stops at the class loader.

Almost always the requirement is "one instance", and dependency injection delivers exactly that by constructing one and wiring it. The instance is then unique because nothing else makes one — without any type having to enforce it, and without any caller reaching around its constructor.

Inspect compiler/toolchain, container definitions and deployment topology first. Implementation examples use Java 17 without preview; ScopedValue is final in Java 25 and represents dynamic context binding, not instance uniqueness. Do not upgrade a project to adopt an idiom.

The uniqueness ladder

Thread binding  ThreadLocal (not a uniqueness guarantee)
Dynamic scope   ScopedValue (may share the same value across structured forks)
Defining class loader    a static field — the same class may exist in several loaders
Process (JVM)   a static field, if one class loader; a DI container's
                singleton scope, if one relevant bean definition/container
Container/pod   the process, restated — one JVM per pod by convention
Node            an OS-coordinated lock/socket, with stale-owner and namespace handling
Cluster         leader election or a distributed lock with a lease
Region          the above, plus a consensus system that spans zones
System          a protocol and authority boundary, not a language primitive

A conventional static getInstance() is bounded by the defining class loader. A requirement for a horizontally scaled service — one scheduler, one cache warmer, one sequence generator, one outbox relay — needs an explicit coordination/effect contract, and no amount of static will produce it. This is the single most expensive misunderstanding in this pattern (leader-election, distributed-locks-and-leases).

Spring singleton scope is one instance per bean definition per container, not per type/JVM. Two definitions of the same class can produce two instances in one context; child contexts may inherit a parent's bean or define their own. DI avoids global access only when callers actually receive dependencies rather than consulting a static service locator.

When it is the answer

The type is a stateless, immutable value or function, and passing it
around is genuinely noise
        → an enum constant or a static final field. Not getInstance().

The hosting API owns creation and offers no injection point, while one
process-wide adapter must coordinate access to a JVM/native facility
        → a singleton bridge may be justified; hosting does not itself prove
          uniqueness (ServiceLoader, for example, can return many providers).

A framework or legacy call site cannot be given a dependency and must
reach one
        → Singleton as a bridge, marked as such, with a plan to remove it.

When it is not

• "Configuration should exist once." It does — the container creates one and injects it. The requirement was access, not uniqueness.
• "Creating it is expensive." That argues for creating it once, which is what a bean or a field already does. It does not argue for reaching it statically.
• "Everything needs it." A dependency that everything needs is still a dependency; making it invisible does not reduce coupling, it only stops the compiler from showing it.
• A cache or registry. Global mutable state under concurrency, with no eviction policy and no owner. Give it an owner and inject it (caching-strategies).
• Anything that must be unique across replicas. See the ladder above.
• Counters, sequence numbers, id generators. Process-local uniqueness produces colliding ids the day a second replica starts.

Decision rules

IF the requirement is stated as "only one X"
THEN ask "one per what?" and place it on the ladder before designing.

IF the answer is cluster or system
THEN this pattern is irrelevant. Use leader election, a lease, or make
     the operation idempotent so multiplicity stops mattering (idempotency).

IF the type has mutable state and is reached statically
THEN it is global mutable state. Every thread-safety argument must be
     made explicitly, and every test must undo it.

IF a singleton is being added so that code can reach a collaborator
THEN pass the collaborator. The singleton is solving a plumbing problem
     by removing the plumbing from view.

IF lazy initialisation is required
THEN use the holder idiom or an enum. Double-checked locking is correct
     only with a volatile field and is rarely worth the risk.

IF the singleton's initialiser touches another class's static initialiser
THEN inspect cycles and blocking: cross-class initialization alone is normal,
     but circular waits between initializing threads can deadlock. Avoid cyclic
     initialization and keep fallible/blocking acquisition in an owned lifecycle.

IF tests need a reset() method on it
THEN treat that as evidence of hidden mutable lifetime. Prefer an owned instance;
     when legacy migration requires reset, synchronize it, constrain it to tests,
     and prevent parallel-test interference.

IF an enum is used purely as a namespace for one instance holding
mutable state
THEN the serialisation and reflection safety it buys is irrelevant, and
     the global-state cost remains.

Cross-cutting checks

• Concurrency. Uniqueness and thread safety are unrelated: a singleton is one instance shared by every thread, which makes any mutable field in it a contended, visibility-sensitive variable. Publication of the instance itself must be safe — the holder idiom and enum get this from class-initialisation semantics; a plain if (instance == null) does not, and double-checked locking without volatile has no Java Memory Model guarantee (java-memory-model).
• Distribution. Process-local, always. A singleton connection pool, rate limiter or scheduler becomes N of them under horizontal scaling, and the resulting limit is N times what was configured — a common cause of exhausting a database's connection limit after a scale-up (connection-pool-sizing, rate-limiting-and-load-shedding).
• Performance. A contended synchronized getInstance() on a hot path can add latency; modern JVMs can make uncontended locking cheap, while the holder idiom removes per-access locking. The larger effect is indirect: a single shared mutable structure becomes the contention point for the whole application, and no amount of lock tuning fixes a design that funnels every thread through one object (false-sharing-and-contended, lock-inflation).
• Testing. Static state survives between tests in the same JVM, so tests pass alone and fail in a suite, or pass in one order and fail in another. Parallel test execution makes it worse. The absence of a constructor parameter also means a test cannot substitute the collaborator through constructor injection; legacy seams, wrappers or isolated processes may help during migration (java-test-design).

Review checklist

Return the required scope, actual creation/call sites, owner and close/retry policy, chosen mechanism and observed checks versus pending. Missing topology or external callers leaves uniqueness and removal safety conditional.

• "One per what?" is answered explicitly and matches the mechanism used
• Nothing that must be unique across replicas relies on a static field
• The instance holds no mutable state, or every mutation is documented as thread-safe
• Lazy initialisation uses the holder idiom or an enum, not unguarded or non-volatile checks
• Initialization has no cyclic/blocking dependency and has an explicit failure policy
• Legacy resets are isolated from concurrent tests and tracked for removal
• Dependency injection was considered and rejected for a stated reason
• Spring's singleton scope is not described as this pattern in review comments

References

• Uniqueness and scope — the ladder in full: what mechanism provides uniqueness at each level, what defeats it (class loaders, multiple contexts, replicas, restarts), and the distributed alternatives with their failure modes — leases expiring, split-brain, and why idempotency often removes the requirement. Read whenever "there must be only one" is stated.
• Implementation and migration — enum, holder idiom and double-checked locking compared with their exact guarantees, the class-initialisation deadlock, reflection and serialisation attacks on the invariant, and a step-by-step migration off an entrenched singleton without a big-bang change. Read when implementing or removing one.