liveBook · Manning

Illegal state

As explained in Data-Oriented Programming in Java

An illegal state is a program state that violates the validity constraints imposed by its data model or domain rules.

An illegal state is a value your program can represent even though it violates the domain’s rules. It often begins with an imprecise type: a String used as a UUID can hold infinitely many values that are not valid IDs. The mismatch forces preconditions, checks, tests, and defensive code to compensate for a representation that permits the wrong thing. section 1.2

The practical warning sign is contextual meaning: fields are populated only for certain flag or enum values, nullable when absent, and unsafe when read without first rechecking the context. Constructor validation can block these combinations at creation, but poorly modeled values still spread defensive conditions and null risks through every consumer. section 4.1.4 section 4.1.6

Checklist completion is not template data

A travel-checklist template with Step(name, isCompleted) permits a nonsensical template in which “bring socks” is already complete. Removing completion from Step and recording it in a Status tied to a particular checklist Instance separates static template data from work performed during a run. section 4.1.3

Repair the model rather than merely refactoring its fields. Group attributes that always belong together into a dedicated type, then represent alternatives with separate types. Completed can carry who and when it was completed; NotStarted carries neither; Skipped carries its own actor, time, and rationale. Those combinations remove states that validation previously had to reject. section 4.2.1 section 4.8

Listing 4.17 Guarding against missing (or not missing!) attributes during construction
record Status(
  Instance instance,     
  Step step,              
  boolean isCompleted,
  User completedBy, 
  Instant completedOn
) {
  Status {  
    if (isCompleted && (completedBy == null || completedOn == null)) {
      throw new IllegalArgumentException(                    #A
          "completedBy and completedOn cannot be null " +    #A
          "when isCompleted is true"                         #A
      );                                                     #A
    }
    if (!isCompleted && (completedBy != null || completedOn != null ) {
      throw new IllegalArgumentException(                     #B
         "completedBy and completedOn cannot be populated " + #B
          "when isCompleted is false"                         #B
      ); 
    }
  }
}

The constructor guards show the cost of one record whose fields have different validity rules for completed and uncompleted states. section 4.1.4

Illegal states also arise through process, not only field layout. Partial construction can bypass earlier validation: a cart item gains a required seller ID after processing has started, producing duplicate-key behavior. Surface hidden knowledge, work backward from invariants, and make a data type the guarded boundary for validated values. section 9.2.4 section 9.6

How Data-Oriented Programming in Java covers it

How deep it goes
Works through type precision, nullable-field validation, alternative status types, and partial-construction failures.
Examples
Uses UUID identifiers, travel-checklist statuses, and partially constructed shopping-cart items.
What you can do after
Evaluate/understand weak representations, then redesign types and alternatives to prevent invalid combinations.
How it connects
Connects data modeling with records, interfaces, algebraic data types, validation, nulls, invariants, and defensive programming.

Also explained in

Compare how 2 books explain illegal state →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Data-Oriented Programming in Java. The section links point to the parts of the book it draws on.