System Design (LLD)Revisiting Inheritance Problems

Revisiting Inheritance Problems

LevelIntermediate

Duration60 mins

TopicRevisiting Inheritance Problems

2 / 4

Fragile Base Class Revisited

When Safe Changes Become Dangerous

Imagine this scenario: you're maintaining a well-tested base class that's been stable for months. Code review is complete, all tests pass, and you deploy a seemingly innocent internal refactoring. The next morning, production alerts flood in—features are broken across multiple services, and they all trace back to your 'safe' change.

Welcome to the Fragile Base Class Problem.

This phenomenon, first formally described in the 1990s, remains one of the most insidious issues in object-oriented design. Unlike compile-time errors that stop you immediately, fragile base class bugs silently corrupt behavior, often only manifesting under specific runtime conditions. In this page, we'll dissect this problem thoroughly, understand its root causes, and learn to recognize and avoid it.

What You Will Learn

By the end of this page, you will understand the fragile base class problem in depth, recognize the patterns that make base classes fragile, learn how to design base classes that are safer to modify, and understand why this problem is inherent to implementation inheritance.

The Fragile Base Class Problem Defined

The Fragile Base Class Problem occurs when a modification to a base class that appears safe—passing all base class tests, maintaining the same public interface, and preserving documented behavior—nevertheless breaks one or more subclasses.

Formally stated:

A base class is fragile if changes to its internals that don't violate its documented contract can cause derived classes to malfunction.

The key insight is that subclasses depend on more than the documented contract. They depend on:

Self-use patterns: How the base class's methods call each other
Invocation order: The sequence in which methods execute
Side effect timing: When and how state changes occur
Implicit invariants: Undocumented assumptions about state

None of these are typically part of the formal API, yet subclasses often rely on them.

Types of Base Class Changes and Their Fragility Risk
Change Type	Example	Fragility Risk	Why
Add public method	Add `reset()` method	Low	Subclasses don't depend on absent methods
Remove public method	Remove `clear()` method	High (compile error)	Caught at compile time
Change method signature	Rename parameter, change type	High (compile error)	Caught at compile time
Change self-use pattern	`addAll()` stops calling `add()`	Very High	Silent runtime failure
Reorder internal operations	Validate before transform	Very High	Silent runtime failure
Add internal state	Add caching field	Moderate	May conflict with subclass state
Change thread safety	Add/remove synchronization	Extreme	Deadlocks or race conditions

The Danger Zone

The most dangerous changes are those that pass all tests and compile successfully. They represent silent contract violations—the base class behaves differently in ways that subclasses depend on, but nothing in the toolchain catches the problem.

The Canonical Example: HashSet and InstrumentedHashSet

The most famous illustration of the fragile base class problem comes from Joshua Bloch's Effective Java. Let's examine it in detail to understand the mechanics.

Goal: Create a HashSet subclass that counts how many elements have been added.

InstrumentedHashSet.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// A seemingly reasonable subclass
public class InstrumentedHashSet<E> extends HashSet<E> {
    private int addCount = 0;
    
    @Override
    public boolean add(E e) {
        addCount++;
        return super.add(e);
    }
    
    @Override
    public boolean addAll(Collection<? extends E> c) {
        addCount += c.size();
        return super.addAll(c);
    }
    
    public int getAddCount() {
        return addCount;
    }
}

The Hidden Bug

This looks correct. Test it with a single element:

TestSingleElement.java
Java
1
2
3
InstrumentedHashSet<String> set = new InstrumentedHashSet<>();
set.add("one");
System.out.println(set.getAddCount());  // Outputs: 1 ✓ Correct!

Now test with addAll():

TestAddAll.java
Java
1
2
3
4
InstrumentedHashSet<String> set = new InstrumentedHashSet<>();
set.addAll(Arrays.asList("one", "two", "three"));
System.out.println(set.getAddCount());  // Expected: 3
                                        // Actual: 6 ✗ WRONG!

Why 6 instead of 3?

The answer lies in HashSet's implementation of addAll(). Internally, HashSet.addAll() loops through each element and calls add(). Since our subclass overrides add(), each element is counted twice:

Once in our addAll() override: addCount += c.size() adds 3
Three more times when super.addAll() internally calls our overridden add()

Total: 3 + 3 = 6

ExecutionFlow.txt

Execution Trace

InstrumentedHashSet.addAll(["one", "two", "three"])
  │
  ├─→ addCount += 3                    // addCount = 3
  │
  └─→ super.addAll(collection)
       │
       └─→ HashSet.addAll() internally:
            │
            ├─→ this.add("one")        // Calls OUR add()!
            │    └─→ addCount++        // addCount = 4
            │
            ├─→ this.add("two")
            │    └─→ addCount++        // addCount = 5
            │
            └─→ this.add("three")
                 └─→ addCount++        // addCount = 6

The Hidden Self-Use Contract

The InstrumentedHashSet subclass unknowingly depended on addAll() NOT calling add(). But HashSet's implementation does call add(). This self-use pattern is an undocumented implementation detail—not part of any specification. And it can change at any time.

The Fix That's Also Fragile

The obvious fix is to not count in addAll()—just let add() do all the counting:

InstrumentedHashSetV2.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// "Fixed" version
public class InstrumentedHashSetV2<E> extends HashSet<E> {
    private int addCount = 0;
    
    @Override
    public boolean add(E e) {
        addCount++;
        return super.add(e);
    }
    
    // Don't override addAll() at all - let parent handle it
    // Parent's addAll() calls our add(), which counts correctly
    
    public int getAddCount() {
        return addCount;
    }
}

This works... for now.

But here's the fragility: This "fix" depends on the undocumented fact that HashSet.addAll() calls add() for each element. What if a future Java version optimizes this?

HashSet_FutureVersion.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Hypothetical future HashSet optimization
public boolean addAll(Collection<? extends E> c) {
    // For performance, directly modify internal table
    // without calling add() for each element
    Object[] elements = c.toArray();
    ensureCapacity(size + elements.length);
    for (Object e : elements) {
        table[hash(e)] = e;  // Direct insert
    }
    size += elements.length;
    return true;
}
 
// Now InstrumentedHashSetV2.addAll() never increments count!
// The "fix" breaks silently when the JDK is upgraded.

The Impossible Situation

The subclass developer faces an impossible choice:

Approach	Assumption	Breaks When
Count in both `add()` and `addAll()`	`addAll()` doesn't call `add()`	Parent `addAll()` calls `add()`
Count only in `add()`	`addAll()` calls `add()`	Parent `addAll()` is optimized to not call `add()`
Copy parent's `addAll()` implementation	Implementation is stable	Parent implementation changes

No approach is safe because the correct behavior depends on undocumented implementation details that can change at any time.

Self-Use Is Not Part of the Contract

Whether addAll() calls add() is an implementation decision, not a specification. The Java documentation doesn't promise either behavior. This means any subclass that depends on either assumption is fragile by definition.

Categories of Fragile Modifications

The HashSet example illustrates self-use fragility, but the fragile base class problem manifests in several distinct patterns. Understanding these categories helps you recognize and avoid them.

Fragility Categories

•Self-Use Fragility — When a base class method internally calls other overridable methods. Subclasses that override these methods may be affected by changes to self-use patterns.
•State Sequence Fragility — When a base class changes the order in which it modifies internal state. Subclasses that access state at specific points may see unexpected values.
•Exception Fragility — When a base class changes which exceptions it throws or catches. Subclasses with try-catch blocks around super calls may break.
•Threading Fragility — When a base class changes its synchronization strategy. Subclasses may experience deadlocks or race conditions.
•Resource Fragility — When a base class changes how it acquires or releases resources. Subclasses managing related resources may leak or double-free.

Example: State Sequence Fragility

StateSequenceFragility.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Original base class
public class Document {
    protected String title;
    protected String content;
    
    public void save() {
        title = sanitize(title);      // 1. Sanitize title first
        content = sanitize(content);  // 2. Then content
        persist();
    }
    
    protected void persist() {
        database.save(this);
    }
}
 
// Subclass depends on state sequence
public class AuditedDocument extends Document {
    @Override
    protected void persist() {
        // Assumes title is already sanitized when persist() is called
        auditLog.record("Saving: " + title);
        super.persist();
    }
}
 
// Later, someone "optimizes" Document
public class Document {
    public void save() {
        persist();  // Now persists first!
        title = sanitize(title);
        content = sanitize(content);
    }
}
 
// AuditedDocument now logs UNSANITIZED titles!
// Potential XSS or injection in audit logs

Example: Threading Fragility

ThreadingFragility.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// Original thread-safe base class
public class SafeCounter {
    private int count = 0;
    
    public synchronized void increment() {
        count++;
        onIncrement();  // Hook for subclasses
    }
    
    protected void onIncrement() {
        // Override point
    }
}
 
// Subclass adds its own synchronization
public class LoggingCounter extends SafeCounter {
    private final Object logLock = new Object();
    private List<String> log = new ArrayList<>();
    
    @Override
    protected void onIncrement() {
        synchronized (logLock) {
            log.add("Incremented at " + System.currentTimeMillis());
        }
    }
}
 
// Later, base class changes synchronization strategy
public class SafeCounter {
    private int count = 0;
    private final Object lock = new Object();
    
    public void increment() {
        synchronized (lock) {  // Now uses different lock
            count++;
            synchronized (this) {  // Nested lock!
                onIncrement();
            }
        }
    }
}
 
// LoggingCounter now has nested locks:
// Thread 1: lock -> this -> logLock
// Thread 2: logLock -> (waiting for this)
// DEADLOCK if another part of code acquires logLock then calls increment()

Threading Fragility Is The Most Dangerous

Threading bugs caused by base class changes are the hardest to diagnose. They're non-deterministic, may only appear under load, and can take weeks to reproduce and fix. The base class author may have no idea their change caused a deadlock in a subclass they've never seen.

Why Tests Don't Catch These Bugs

A common response to fragile base class examples is: "Just write better tests!"

Unfortunately, testing is fundamentally unable to catch fragile base class bugs in many situations. Here's why:

Why Testing Falls Short

•Base and subclass are often tested separately — The base class tests pass (the base class still works correctly). Subclass tests may not exist or may not cover the affected interaction.
•Implementation details aren't part of the test contract — Tests verify behavior, not internal implementation. A test for addAll() checks that elements are added, not whether add() is called internally.
•Tests can't anticipate future subclasses — When writing base class tests, you can't test against subclasses that don't exist yet.
•Cross-version testing is rare — Few teams run subclass tests against new base class versions before upgrading dependencies.
•Concurrency bugs are probabilistic — Threading fragility may require thousands of runs to manifest, far beyond normal test coverage.

The Test Coverage Illusion

Consider what happens when the HashSet optimization is deployed:

TestScenario.txt

Test Scenario

JDK Team runs their tests:
├── HashSet.add() tests → PASS ✓
├── HashSet.addAll() tests → PASS ✓ (elements are added correctly)
├── HashSet performance tests → PASS ✓ (faster now!)
└── HashSet behavior unchanged per spec → PASS ✓
 
Your App Team (uses InstrumentedHashSet):
├── InstrumentedHashSet was written 2 years ago
├── Tests pass with current JDK → PASS ✓
├── Nobody re-runs tests after JDK upgrade → NOT RUN
└── Production: addCount returns wrong values → BUG IN PRODUCTION
 
Gap: JDK team doesn't know InstrumentedHashSet exists.
     App team doesn't know HashSet implementation changed.

Testing For Fragility Requires Knowing The Future

To test against fragile base class bugs, you'd need to test: 'If the base class stops calling add() from addAll(), does the subclass still work?' But how do you know to write that test? You'd need to anticipate every possible future change to the base class—which is impossible.

The Limits of Documentation

Another common response is: "Document the self-use patterns!"

While documentation helps, it creates its own problems and ultimately cannot solve the fragile base class problem. Here's why:

Problems with Documenting Self-Use Patterns
Problem	Explanation	Impact
Documentation becomes specification	Once documented, self-use patterns can never change	Prevents optimization, locks implementation
Explosion of documentation	Every method must document which other methods it calls, in what order, with what arguments	Massive documentation burden
Documentation becomes stale	Implementation changes but docs aren't updated	False sense of security
Complex interactions	Method A calls B which calls C which calls D	Documentation becomes a graph, not prose
Conditional self-use	A calls B only if condition X	Documentation becomes pseudo-code

The Java Collections Framework Experience

The Java Collections Framework attempted to document self-use patterns. The result illustrates the problem:

AbstractCollectionJavadoc.txt

Javadoc

/**
 * {@inheritDoc}
 *
 * <p>This implementation iterates over the specified collection,
 * and adds each object returned by the iterator to this
 * collection, in turn.
 *
 * <p>Note that this implementation will throw an
 * UnsupportedOperationException unless add is
 * overridden (assuming the specified collection is non-empty).
 *
 * @implSpec
 * This implementation iterates over the collection and calls
 * the add method once for each element.
 *
 * @param c elements to be inserted into this collection
 * @return true if this collection changed as a result of the call
 * @throws UnsupportedOperationException if the add operation is
 *         not supported by this collection
 */
public boolean addAll(Collection<? extends E> c) {
    // ...
}

The @implSpec tag was added specifically to document self-use patterns. But this comes with costs:

Locked Implementation: The documented behavior cannot change without breaking the 'spec'
Selective Documentation: Not all self-use is documented; gaps remain
Developer Awareness: Most developers don't read @implSpec sections
Version Drift: Implementations evolve, docs may not

Even with extensive documentation, the fundamental problem remains: subclasses depend on implementation details, and those details are harder to evolve once documented.

Documentation Trades Flexibility for Safety

Documenting implementation details makes those details permanent. You can never optimize addAll() to be faster if you've documented that it calls add(). The choice becomes: keep flexibility (risk breaking subclasses) or document patterns (can never improve performance).

Strategies for Less Fragile Base Classes

While the fragile base class problem cannot be eliminated entirely from implementation inheritance, certain design strategies can reduce fragility. If you must design a class for inheritance, these practices help:

Strategies for Reduced Fragility

•Minimize overridable methods — The fewer methods that can be overridden, the fewer self-use patterns matter. Use final liberally.
•Don't call overridable methods from constructors — The subclass isn't fully constructed yet; calling its methods leads to unpredictable behavior.
•Eliminate self-use of overridable methods — If addAll() must call something, make it call a private helper, not the public add().
•Document all self-use that exists — Use @implSpec or equivalent to make dependencies explicit.
•Provide non-overridable alternatives — Offer final methods that do the work, and overridable hooks for customization.
•Test with subclasses — Write actual subclass implementations and test them against the base class.

Example: Eliminating Self-Use

SaferHashSet.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// Safer base class design - no self-use of overridables
public class SaferHashSet<E> {
    private Set<E> internal = new HashSet<>();
    
    // Public API methods are marked final
    public final boolean add(E e) {
        boolean result = addInternal(e);
        onAdd(e, result);  // Hook AFTER the work
        return result;
    }
    
    public final boolean addAll(Collection<? extends E> c) {
        boolean modified = false;
        for (E e : c) {
            if (addInternal(e)) {
                modified = true;
                onAdd(e, true);
            }
        }
        return modified;
    }
    
    // Private helper - implementation detail
    private boolean addInternal(E e) {
        return internal.add(e);
    }
    
    // Protected hook for subclass customization
    // Called AFTER the element is added, with result
    protected void onAdd(E element, boolean wasNew) {
        // Override this for notifications, logging, etc.
    }
}
 
// Subclass using the hook
public class InstrumentedSaferSet<E> extends SaferHashSet<E> {
    private int addCount = 0;
    
    @Override
    protected void onAdd(E element, boolean wasNew) {
        if (wasNew) {
            addCount++;
        }
    }
    
    public int getAddCount() {
        return addCount;
    }
}

Key Design Decisions in the Safer Version:

add() and addAll() are final — cannot be overridden, no self-use concerns
Actual work is in a private method — hidden implementation detail
Single hook method for customization — onAdd() is the only override point
Hook is called after the work — state is consistent when hook runs
Hook receives explicit parameters — doesn't need to access internal state

This design is significantly less fragile because:

The base class can optimize addAll() without affecting subclasses
Subclasses have a clear, documented customization point
The hook method has explicit preconditions (element was just added)

Design Pattern: Template Method Done Right

The safer design uses a variation of Template Method where the template (algorithm) is final and only specific, well-defined hooks are overridable. This limits the subclass's dependency surface and makes the contract explicit.

The Ultimate Solution: Don't Inherit

While we can mitigate fragile base class problems, the only way to eliminate them is to avoid implementation inheritance entirely for cases where it creates undue coupling.

The Composition Alternative

Here's how the InstrumentedHashSet is properly implemented using composition:

InstrumentedSetComposition.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Proper solution using composition
public class InstrumentedSet<E> implements Set<E> {
    private final Set<E> delegate;  // Composition, not inheritance
    private int addCount = 0;
    
    public InstrumentedSet(Set<E> delegate) {
        this.delegate = delegate;
    }
    
    @Override
    public boolean add(E e) {
        addCount++;
        return delegate.add(e);  // Delegate, don't inherit
    }
    
    @Override
    public boolean addAll(Collection<? extends E> c) {
        addCount += c.size();
        return delegate.addAll(c);  // Delegate, don't inherit
    }
    
    public int getAddCount() {
        return addCount;
    }
    
    // All other Set methods delegate to internal set
    @Override
    public int size() { return delegate.size(); }
    
    @Override
    public boolean isEmpty() { return delegate.isEmpty(); }
    
    @Override
    public boolean contains(Object o) { return delegate.contains(o); }
    // ... etc
}

Why Composition Solves the Problem:

Inheritance Version

•Depends on self-use patterns
•Cannot change parent class
•Shares identity with parent
•Inherits all methods, wanted or not
•Breaks when parent changes internally

Composition Version

•No self-use dependency — we control all calls
•Can wrap any Set implementation
•Has its own identity
•Exposes only what we choose
•Stable as long as Set interface is stable

The Decorator Pattern

This composition pattern is a form of the Decorator Pattern. The InstrumentedSet wraps a Set, adds behavior (counting), and delegates to the wrapped object. The key insight:

When you delegate to an object you contain, you call its methods directly. You don't call through super, so there's no chance of self-use patterns affecting you.

If HashSet.addAll() internally calls HashSet.add(), that has no effect on us—we're not overriding those methods. We call delegate.addAll(), and whatever happens inside is the delegate's business.

Composition Eliminates Self-Use Fragility

With composition, changes to the delegate's internal implementation cannot affect the wrapper. The wrapper depends only on the delegate's public interface—exactly the contract we want to depend on.

Summary: The Fragile Base Class Reality

The fragile base class problem is not a flaw in any particular language or framework—it's an inherent consequence of implementation inheritance. Let's consolidate our understanding:

Key Takeaways

•Subclasses depend on undocumented details — Self-use patterns, state sequences, and threading models are rarely specified but always depended upon.
•Safe-looking changes break subclasses — A base class change that passes all tests and maintains the public interface can still break subclasses.
•Tests cannot catch these bugs — Testing the base class cannot predict subclass dependencies; testing the subclass cannot predict base class evolution.
•Documentation creates lock-in — Documenting implementation details makes them permanent, preventing future optimization.
•Safer base class design is possible but limited — Using final methods, hooks, and eliminating self-use reduces but doesn't eliminate fragility.
•Composition eliminates the problem — By depending on interfaces rather than implementations, composition avoids self-use fragility entirely.

What's Next

In the next page, we'll examine Inheritance Hierarchy Rigidity—how inheritance hierarchies become increasingly difficult to change over time, and why this rigidity conflicts with software's need to evolve.

Page Complete

You now understand the fragile base class problem in depth—its causes, manifestations, and the fundamental reason it cannot be fully solved within implementation inheritance. This knowledge is essential for making informed decisions about when inheritance is worth the risk.

2 / 4

Loading learning content...

System Design (LLD)Revisiting Inheritance Problems

Revisiting Inheritance Problems

LevelIntermediate

Duration60 mins

TopicRevisiting Inheritance Problems

2 / 4

Fragile Base Class Revisited

When Safe Changes Become Dangerous

Welcome to the Fragile Base Class Problem.

What You Will Learn

The Fragile Base Class Problem Defined

Formally stated:

A base class is fragile if changes to its internals that don't violate its documented contract can cause derived classes to malfunction.

The key insight is that subclasses depend on more than the documented contract. They depend on:

Self-use patterns: How the base class's methods call each other
Invocation order: The sequence in which methods execute
Side effect timing: When and how state changes occur
Implicit invariants: Undocumented assumptions about state

None of these are typically part of the formal API, yet subclasses often rely on them.

Types of Base Class Changes and Their Fragility Risk
Change Type	Example	Fragility Risk	Why
Add public method	Add `reset()` method	Low	Subclasses don't depend on absent methods
Remove public method	Remove `clear()` method	High (compile error)	Caught at compile time
Change method signature	Rename parameter, change type	High (compile error)	Caught at compile time
Change self-use pattern	`addAll()` stops calling `add()`	Very High	Silent runtime failure
Reorder internal operations	Validate before transform	Very High	Silent runtime failure
Add internal state	Add caching field	Moderate	May conflict with subclass state
Change thread safety	Add/remove synchronization	Extreme	Deadlocks or race conditions

The Danger Zone

The Canonical Example: HashSet and InstrumentedHashSet

The most famous illustration of the fragile base class problem comes from Joshua Bloch's Effective Java. Let's examine it in detail to understand the mechanics.

Goal: Create a HashSet subclass that counts how many elements have been added.

InstrumentedHashSet.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// A seemingly reasonable subclass
public class InstrumentedHashSet<E> extends HashSet<E> {
    private int addCount = 0;
    
    @Override
    public boolean add(E e) {
        addCount++;
        return super.add(e);
    }
    
    @Override
    public boolean addAll(Collection<? extends E> c) {
        addCount += c.size();
        return super.addAll(c);
    }
    
    public int getAddCount() {
        return addCount;
    }
}

The Hidden Bug

This looks correct. Test it with a single element:

TestSingleElement.java
Java
1
2
3
InstrumentedHashSet<String> set = new InstrumentedHashSet<>();
set.add("one");
System.out.println(set.getAddCount());  // Outputs: 1 ✓ Correct!

Now test with addAll():

TestAddAll.java
Java
1
2
3
4
InstrumentedHashSet<String> set = new InstrumentedHashSet<>();
set.addAll(Arrays.asList("one", "two", "three"));
System.out.println(set.getAddCount());  // Expected: 3
                                        // Actual: 6 ✗ WRONG!

Why 6 instead of 3?

Once in our addAll() override: addCount += c.size() adds 3
Three more times when super.addAll() internally calls our overridden add()

Total: 3 + 3 = 6

ExecutionFlow.txt

Execution Trace

InstrumentedHashSet.addAll(["one", "two", "three"])
  │
  ├─→ addCount += 3                    // addCount = 3
  │
  └─→ super.addAll(collection)
       │
       └─→ HashSet.addAll() internally:
            │
            ├─→ this.add("one")        // Calls OUR add()!
            │    └─→ addCount++        // addCount = 4
            │
            ├─→ this.add("two")
            │    └─→ addCount++        // addCount = 5
            │
            └─→ this.add("three")
                 └─→ addCount++        // addCount = 6

The Hidden Self-Use Contract

The Fix That's Also Fragile

The obvious fix is to not count in addAll()—just let add() do all the counting:

InstrumentedHashSetV2.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// "Fixed" version
public class InstrumentedHashSetV2<E> extends HashSet<E> {
    private int addCount = 0;
    
    @Override
    public boolean add(E e) {
        addCount++;
        return super.add(e);
    }
    
    // Don't override addAll() at all - let parent handle it
    // Parent's addAll() calls our add(), which counts correctly
    
    public int getAddCount() {
        return addCount;
    }
}

This works... for now.

But here's the fragility: This "fix" depends on the undocumented fact that HashSet.addAll() calls add() for each element. What if a future Java version optimizes this?

HashSet_FutureVersion.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Hypothetical future HashSet optimization
public boolean addAll(Collection<? extends E> c) {
    // For performance, directly modify internal table
    // without calling add() for each element
    Object[] elements = c.toArray();
    ensureCapacity(size + elements.length);
    for (Object e : elements) {
        table[hash(e)] = e;  // Direct insert
    }
    size += elements.length;
    return true;
}
 
// Now InstrumentedHashSetV2.addAll() never increments count!
// The "fix" breaks silently when the JDK is upgraded.

The Impossible Situation

The subclass developer faces an impossible choice:

Approach	Assumption	Breaks When
Count in both `add()` and `addAll()`	`addAll()` doesn't call `add()`	Parent `addAll()` calls `add()`
Count only in `add()`	`addAll()` calls `add()`	Parent `addAll()` is optimized to not call `add()`
Copy parent's `addAll()` implementation	Implementation is stable	Parent implementation changes

No approach is safe because the correct behavior depends on undocumented implementation details that can change at any time.

Self-Use Is Not Part of the Contract

Categories of Fragile Modifications

The HashSet example illustrates self-use fragility, but the fragile base class problem manifests in several distinct patterns. Understanding these categories helps you recognize and avoid them.

Fragility Categories

•Self-Use Fragility — When a base class method internally calls other overridable methods. Subclasses that override these methods may be affected by changes to self-use patterns.
•State Sequence Fragility — When a base class changes the order in which it modifies internal state. Subclasses that access state at specific points may see unexpected values.
•Exception Fragility — When a base class changes which exceptions it throws or catches. Subclasses with try-catch blocks around super calls may break.
•Threading Fragility — When a base class changes its synchronization strategy. Subclasses may experience deadlocks or race conditions.
•Resource Fragility — When a base class changes how it acquires or releases resources. Subclasses managing related resources may leak or double-free.

Example: State Sequence Fragility

StateSequenceFragility.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Original base class
public class Document {
    protected String title;
    protected String content;
    
    public void save() {
        title = sanitize(title);      // 1. Sanitize title first
        content = sanitize(content);  // 2. Then content
        persist();
    }
    
    protected void persist() {
        database.save(this);
    }
}
 
// Subclass depends on state sequence
public class AuditedDocument extends Document {
    @Override
    protected void persist() {
        // Assumes title is already sanitized when persist() is called
        auditLog.record("Saving: " + title);
        super.persist();
    }
}
 
// Later, someone "optimizes" Document
public class Document {
    public void save() {
        persist();  // Now persists first!
        title = sanitize(title);
        content = sanitize(content);
    }
}
 
// AuditedDocument now logs UNSANITIZED titles!
// Potential XSS or injection in audit logs

Example: Threading Fragility

ThreadingFragility.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// Original thread-safe base class
public class SafeCounter {
    private int count = 0;
    
    public synchronized void increment() {
        count++;
        onIncrement();  // Hook for subclasses
    }
    
    protected void onIncrement() {
        // Override point
    }
}
 
// Subclass adds its own synchronization
public class LoggingCounter extends SafeCounter {
    private final Object logLock = new Object();
    private List<String> log = new ArrayList<>();
    
    @Override
    protected void onIncrement() {
        synchronized (logLock) {
            log.add("Incremented at " + System.currentTimeMillis());
        }
    }
}
 
// Later, base class changes synchronization strategy
public class SafeCounter {
    private int count = 0;
    private final Object lock = new Object();
    
    public void increment() {
        synchronized (lock) {  // Now uses different lock
            count++;
            synchronized (this) {  // Nested lock!
                onIncrement();
            }
        }
    }
}
 
// LoggingCounter now has nested locks:
// Thread 1: lock -> this -> logLock
// Thread 2: logLock -> (waiting for this)
// DEADLOCK if another part of code acquires logLock then calls increment()

Threading Fragility Is The Most Dangerous

Why Tests Don't Catch These Bugs

A common response to fragile base class examples is: "Just write better tests!"

Unfortunately, testing is fundamentally unable to catch fragile base class bugs in many situations. Here's why:

Why Testing Falls Short

•Base and subclass are often tested separately — The base class tests pass (the base class still works correctly). Subclass tests may not exist or may not cover the affected interaction.
•Implementation details aren't part of the test contract — Tests verify behavior, not internal implementation. A test for addAll() checks that elements are added, not whether add() is called internally.
•Tests can't anticipate future subclasses — When writing base class tests, you can't test against subclasses that don't exist yet.
•Cross-version testing is rare — Few teams run subclass tests against new base class versions before upgrading dependencies.
•Concurrency bugs are probabilistic — Threading fragility may require thousands of runs to manifest, far beyond normal test coverage.

The Test Coverage Illusion

Consider what happens when the HashSet optimization is deployed:

TestScenario.txt

Test Scenario

JDK Team runs their tests:
├── HashSet.add() tests → PASS ✓
├── HashSet.addAll() tests → PASS ✓ (elements are added correctly)
├── HashSet performance tests → PASS ✓ (faster now!)
└── HashSet behavior unchanged per spec → PASS ✓
 
Your App Team (uses InstrumentedHashSet):
├── InstrumentedHashSet was written 2 years ago
├── Tests pass with current JDK → PASS ✓
├── Nobody re-runs tests after JDK upgrade → NOT RUN
└── Production: addCount returns wrong values → BUG IN PRODUCTION
 
Gap: JDK team doesn't know InstrumentedHashSet exists.
     App team doesn't know HashSet implementation changed.

Testing For Fragility Requires Knowing The Future

The Limits of Documentation

Another common response is: "Document the self-use patterns!"

While documentation helps, it creates its own problems and ultimately cannot solve the fragile base class problem. Here's why:

Problems with Documenting Self-Use Patterns
Problem	Explanation	Impact
Documentation becomes specification	Once documented, self-use patterns can never change	Prevents optimization, locks implementation
Explosion of documentation	Every method must document which other methods it calls, in what order, with what arguments	Massive documentation burden
Documentation becomes stale	Implementation changes but docs aren't updated	False sense of security
Complex interactions	Method A calls B which calls C which calls D	Documentation becomes a graph, not prose
Conditional self-use	A calls B only if condition X	Documentation becomes pseudo-code

The Java Collections Framework Experience

The Java Collections Framework attempted to document self-use patterns. The result illustrates the problem:

AbstractCollectionJavadoc.txt

Javadoc

/**
 * {@inheritDoc}
 *
 * <p>This implementation iterates over the specified collection,
 * and adds each object returned by the iterator to this
 * collection, in turn.
 *
 * <p>Note that this implementation will throw an
 * UnsupportedOperationException unless add is
 * overridden (assuming the specified collection is non-empty).
 *
 * @implSpec
 * This implementation iterates over the collection and calls
 * the add method once for each element.
 *
 * @param c elements to be inserted into this collection
 * @return true if this collection changed as a result of the call
 * @throws UnsupportedOperationException if the add operation is
 *         not supported by this collection
 */
public boolean addAll(Collection<? extends E> c) {
    // ...
}

The @implSpec tag was added specifically to document self-use patterns. But this comes with costs:

Locked Implementation: The documented behavior cannot change without breaking the 'spec'
Selective Documentation: Not all self-use is documented; gaps remain
Developer Awareness: Most developers don't read @implSpec sections
Version Drift: Implementations evolve, docs may not

Even with extensive documentation, the fundamental problem remains: subclasses depend on implementation details, and those details are harder to evolve once documented.

Documentation Trades Flexibility for Safety

Strategies for Less Fragile Base Classes

Strategies for Reduced Fragility

•Minimize overridable methods — The fewer methods that can be overridden, the fewer self-use patterns matter. Use final liberally.
•Don't call overridable methods from constructors — The subclass isn't fully constructed yet; calling its methods leads to unpredictable behavior.
•Eliminate self-use of overridable methods — If addAll() must call something, make it call a private helper, not the public add().
•Document all self-use that exists — Use @implSpec or equivalent to make dependencies explicit.
•Provide non-overridable alternatives — Offer final methods that do the work, and overridable hooks for customization.
•Test with subclasses — Write actual subclass implementations and test them against the base class.

Example: Eliminating Self-Use

SaferHashSet.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// Safer base class design - no self-use of overridables
public class SaferHashSet<E> {
    private Set<E> internal = new HashSet<>();
    
    // Public API methods are marked final
    public final boolean add(E e) {
        boolean result = addInternal(e);
        onAdd(e, result);  // Hook AFTER the work
        return result;
    }
    
    public final boolean addAll(Collection<? extends E> c) {
        boolean modified = false;
        for (E e : c) {
            if (addInternal(e)) {
                modified = true;
                onAdd(e, true);
            }
        }
        return modified;
    }
    
    // Private helper - implementation detail
    private boolean addInternal(E e) {
        return internal.add(e);
    }
    
    // Protected hook for subclass customization
    // Called AFTER the element is added, with result
    protected void onAdd(E element, boolean wasNew) {
        // Override this for notifications, logging, etc.
    }
}
 
// Subclass using the hook
public class InstrumentedSaferSet<E> extends SaferHashSet<E> {
    private int addCount = 0;
    
    @Override
    protected void onAdd(E element, boolean wasNew) {
        if (wasNew) {
            addCount++;
        }
    }
    
    public int getAddCount() {
        return addCount;
    }
}

Key Design Decisions in the Safer Version:

add() and addAll() are final — cannot be overridden, no self-use concerns
Actual work is in a private method — hidden implementation detail
Single hook method for customization — onAdd() is the only override point
Hook is called after the work — state is consistent when hook runs
Hook receives explicit parameters — doesn't need to access internal state

This design is significantly less fragile because:

The base class can optimize addAll() without affecting subclasses
Subclasses have a clear, documented customization point
The hook method has explicit preconditions (element was just added)

Design Pattern: Template Method Done Right

The Ultimate Solution: Don't Inherit

While we can mitigate fragile base class problems, the only way to eliminate them is to avoid implementation inheritance entirely for cases where it creates undue coupling.

The Composition Alternative

Here's how the InstrumentedHashSet is properly implemented using composition:

InstrumentedSetComposition.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Proper solution using composition
public class InstrumentedSet<E> implements Set<E> {
    private final Set<E> delegate;  // Composition, not inheritance
    private int addCount = 0;
    
    public InstrumentedSet(Set<E> delegate) {
        this.delegate = delegate;
    }
    
    @Override
    public boolean add(E e) {
        addCount++;
        return delegate.add(e);  // Delegate, don't inherit
    }
    
    @Override
    public boolean addAll(Collection<? extends E> c) {
        addCount += c.size();
        return delegate.addAll(c);  // Delegate, don't inherit
    }
    
    public int getAddCount() {
        return addCount;
    }
    
    // All other Set methods delegate to internal set
    @Override
    public int size() { return delegate.size(); }
    
    @Override
    public boolean isEmpty() { return delegate.isEmpty(); }
    
    @Override
    public boolean contains(Object o) { return delegate.contains(o); }
    // ... etc
}

Why Composition Solves the Problem:

Inheritance Version

•Depends on self-use patterns
•Cannot change parent class
•Shares identity with parent
•Inherits all methods, wanted or not
•Breaks when parent changes internally

Composition Version

•No self-use dependency — we control all calls
•Can wrap any Set implementation
•Has its own identity
•Exposes only what we choose
•Stable as long as Set interface is stable

The Decorator Pattern

This composition pattern is a form of the Decorator Pattern. The InstrumentedSet wraps a Set, adds behavior (counting), and delegates to the wrapped object. The key insight:

When you delegate to an object you contain, you call its methods directly. You don't call through super, so there's no chance of self-use patterns affecting you.

Composition Eliminates Self-Use Fragility

With composition, changes to the delegate's internal implementation cannot affect the wrapper. The wrapper depends only on the delegate's public interface—exactly the contract we want to depend on.

Summary: The Fragile Base Class Reality

The fragile base class problem is not a flaw in any particular language or framework—it's an inherent consequence of implementation inheritance. Let's consolidate our understanding:

Key Takeaways

•Subclasses depend on undocumented details — Self-use patterns, state sequences, and threading models are rarely specified but always depended upon.
•Safe-looking changes break subclasses — A base class change that passes all tests and maintains the public interface can still break subclasses.
•Tests cannot catch these bugs — Testing the base class cannot predict subclass dependencies; testing the subclass cannot predict base class evolution.
•Documentation creates lock-in — Documenting implementation details makes them permanent, preventing future optimization.
•Safer base class design is possible but limited — Using final methods, hooks, and eliminating self-use reduces but doesn't eliminate fragility.
•Composition eliminates the problem — By depending on interfaces rather than implementations, composition avoids self-use fragility entirely.

What's Next

Page Complete

2 / 4