What is a class invariant in Java?

Question

I googled the topic, but besides Wikipedia I didn't find any further useful documentation or articles.

Can anybody explain to me in simple words what it means or refer me to some nice and easy to understand documentation?

Answer 1

It doesn't mean anything in particular in reference to Java.

A class invariant is simply a property that holds for all instances of a class, always, no matter what other code does.

For example,

class X {
  final Y y = new Y();
}

X has the class invariant that there is a y property and it is never null and it has a value of type Y.

class Counter {
  private int x;

  public int count() { return x++; }
}

This fails to maintain two important invariants:

1. That count never returns a negative value because of possible underflow.
2. That calls to count are strictly monotonically increasing.

The modified class preserves those two invariants.

class Counter {
  private int x;

  public synchronized int count() {
    if (x == Integer.MAX_VALUE) { throw new IllegalStateException(); }
    return x++;
  }
}

...but fails to preserve the invariant that calls to count always succeed normally (absent TCB-violations^†) because count might throw an exception or it might block if a deadlocked thread owns the counter's monitor.

Each language with classes make it easy to maintain some class invariants but not others. Java is no exception:

1. Java classes consistently have or do not have properties and methods, so interface invariants are easy to maintain.
2. Java classes can protect their private fields, so invariants that rely on private data are easy to maintain.
3. Java classes can be final, so invariants that rely on there being no code that violates an invariant by crafting a malicious subclass can be maintained.
4. Java allows null values to sneak in in many ways, so it is tough to maintain "has a real value" invariants.
5. Java has threads which means that classes that do not synchronize have trouble maintaining invariants that rely on sequential operations in a thread happening together.
6. Java has exceptions which makes it easy to maintain invariants like "returns a result with property p or returns no result" but harder to maintain invariants like "always returns a result".

---

† - An externality or TCB violation is an event which a systems designer optimistically assumes will not happen.

Typically we just trust that the basic hardware works as advertised when talking about properties of high-level languages built on them, and our arguments that invariants hold don't take into account the possibility of:

• A programmer using debug hooks to alter local variables as a program runs in ways that code cannot.
• Your peers don't use reflection with setAccessible to modify private lookup tables.
• Loki altering physics causing your processor to incorrectly compare two numbers.

For some systems our TCB might include only parts of the system, so we might not assume that

• An administrator or privileged daemon won't kill our JVM process,

...but we might assume that:

• We can checkpoint to a reliable transactional file-system.

The higher-level a system, the larger its TCB typically is, but the more unreliable things you can get out of your TCB, the more likely your invariants are to hold, and the more reliable your system will be in the long run.