what is a legal state?

[Naadiyaar Mansouri]

I'm reading "Java in a Nutshell" book and in a section about safe java programming it's listing 4 requirements of a safe program which are:

All objects start off in a legal state after creation
Externally accessible methods transition objects between legal states
Externally accessible methods must not return with objects in an inconsistent state
Externally accessible methods must reset objects to a legal state before throwing

the term legal state is repeated a few times here, what is it referring to?

[Campbell Ritchie]

It sounds rather like class invariants. An invariant is omething that has to be true at all times. For example, a kettle must at all times contain a non‑negative (that includes 0) amount of water and that water has to be at a temperature between 0℃ and 100℃ inclusive. An object is in a legal state when all its invariants are satisfied.
Every constructor must establish all the invariants and every method call must preserve them, in my opinion. It is however permissible for intermediate calculations in a method to breach the invariants, but that method must restore the invariants before it completes. Note in the following example I have omitted a bit of defensive programming; I challenge you to tell me what it is.

class Kettle
{
   // ...
   public void cool(int degrees)
   {
      temperature -= degrees;
      /* Invariant might be breached at this point */
      if (temperature < Temperatures.MELTING_ICE) // 0
      {
         /* Restore that invariant */
         temperature = Temperatures.MELTING_ICE; // 0
      }
   }
   // ...
}

[Paul Anilprem]

A legal state means that the values of the instance fields of an object make sense as per the business logic that the class is meant to represent/model. To continue with Campbell's example, if you are modeling a real kettle using a Kettle class and using an int field named t for temperature in degree Celsius, does your business logic expect its value to be less than 0 or greater than 100? If no, then a Kettle object with t = -1 is in an illegal state even though an int can very well store a value of -1.

The legality is decided by you, the developer, and not by Java.

[Stephan van Hulst]

I means whatever YOU, the designer, has defined it to mean for a particular class.

For instance, let's say you have a bank account:

/**
 * A bank account that keeps track of an amount of deposited money.
 * 
 * A bank account has a lower limit:
 * More money can be withdrawn than was deposited, but never beyond the lower limit.
 */
final class BankAccount {
  
  private final BigInteger lowerLimit;

  private BigInteger bankedAmount;

  /**
   * Initializes a bank account with a specified lower limit.
   *
   * @param lowerLimit the lower limit of the bank account.
   */
  BankAccount(BigInteger lowerLimit) {
    this.lowerLimit   = lowerLimit;
    this.bankedAmount = BigInteger.ZERO;
  }

  /**
   * Gets the total amount that was deposited into the account.
   *
   * May be negative if the account was overdrawn.
   *
   * @return a value greater than or equal to the account's lower limit.
   */
  BigInteger bankedAmount() {
    return bankedAmount;
  }

  /**
   * Deposits an amount into the bank account.
   *
   * The amount is added to the amount that the bank account already contains.
   *
   * @param amount the amount to deposit into the bank account.
   */
  void deposit(BigInteger amount) {
    bankedAmount = bankedAmount.add(amount);
  }

  /**
   * Withdraws an amount from the bank account.
   *
   * The amount is subtracted from the amount that the bank account already contains.
   *
   * If the net amount that is left in the account is less than the lower limit,
   * the withdrawal aborts and the amount in the bank account is unchanged.
   *
   * @param amount the amount to withdraw from the bank account.
   *
   * @return {@code true} if the amount was successfully withdrawn from the bank account;
   *         {@code false} if the amount was too large and the withdrawal was aborted.
   */
  boolean withdraw(BigInteger amount) {
    bankedAmount = bankedAmount.subtract(amount);

    if (bankedAmount.compareTo(lowerLimit) < 0) {
      bankedAmount = bankedAmount.add(amount);
      return false;
    }

    return true;
  }
}

The "legal state" of a bank account is that the amount of money deposited in the account is greater than or equal to the lower limit. Here is a valid use:

    var lowerLimit = BigInteger.valueOf(-500);

    var account = new BankAccount(lowerLimit);

    account.deposit (BigInteger.valueOf(150)); // total is  150

    account.withdraw(BigInteger.valueOf(600)); // total is -450, this is allowed

    account.withdraw(BigInteger.valueOf(100)); // total is -450, withdrawal was rejected

    System.out.println(account.bankedAmount());

At all times, the account is in a legal state. However, the following code demonstrates that the account can be in an illegal state:

    var lowerLimit = BigInteger.valueOf(200);

    System.out.println(account.bankedAmount()); // prints 0

The banked amount is 0, which is less than the lower limit. This should not be possible! The first requirement was violated:

All objects start off in a legal state after creation

We fix this by adding validation to the constructor:

    if (lowerLimit.compareTo(BigInteger.ZERO) > 0) {
      throw new IllegalArgumentException("The lower limit may not be greater than zero.");
    }
    
    this.lowerLimit   = lowerLimit;
    this.bankedAmount = BigInteger.ZERO;

Now, what if a bank account is not constructed with a lower limit, but instead the lower limit is read from a file:

  boolean withdraw(BigInteger amount) {
    bankedAmount = bankedAmount.subtract(amount);

    var lowerLimit = readLowerLimit();

    if (bankedAmount.compareTo(lowerLimit) < 0) {
      bankedAmount = bankedAmount.add(amount);
      return false;
    }

    return true;
  }

  private BigInteger readLowerLimit() {
    try (
      var scanner = new Scanner("lower-limit.txt");
    ) {
      return scanner.nextBigInteger();
    }
  }

"lower-limit.txt" is supposed to contain the value -300.

Assume that there is a problem with reading "lower-limit.txt". Maybe the file doesn't exist or is in the wrong location:

    var account = new BankAccount();

    account.deposit(BigInteger.valueOf(150));     // total is 150

    try {
      account.withdraw(BigInteger.valueOf(600));  // if an exception occurs, the total amount should be unchanged.
    }

    finally {
      System.out.println(account.bankedAmount()); // prints -450, even though we intended the lower limit to be -300!
    }

The object transitioned from a legal to an illegal state because it didn't reset before throwing. Here is the fix:

  boolean withdraw(BigInteger amount) {
    var newAmount = bankedAmount.subtract(amount);

    var lowerLimit = readLowerLimit();

    if (newAmount.compareTo(lowerLimit) < 0) {
      return false;
    }
    
    bankedAmount = newAmount;
    
    return true;
  }

The bankedAmount is only changed if the readLowerLimit() call succeeds. If an exception occurs, the account is unchanged, and so remains in a legal state.

[Naadiyaar Mansouri]

I have omitted a bit of defensive programming; I challenge you to tell me what it is.

I hope I understood what is in your mind correctly, so in this case since we're accepting any range of int values, getting a negative degree can cause the method to behave unexpectedly and despite its name being cool, it actually warms up the water
Therefor adding another if statement to check int's sign seems like a good idea

if (degrees < 0) 
        throw new IllegalArgumentException("reduced degree must be greater than or equal to 0");

[Campbell Ritchie]

Naadiyaar Mansouri wrote:. . . I hope I understood what is in your mind correctly . . .

Yes Spot on. Well done.

[Mike Simmons]

The other thing I noticed there is, what if degrees is a large enough number that subtraction would cause overflow?  That's effectively impossible in the real world (i.e. for remotely realistic temperatures), but within your program, it could happen...

[Campbell Ritchie]

I have conveniently forgotten about overflow.