What's the intended use of IllegalStateException?

Question

This came up in a discussion with a colleague today.

The Javadocs for Java\'s IllegalStateException state that it:

Signals that a method has b

Answer 1

There is no 'discrepancy' here. There is nothing in Bloch's wording that excludes what it says in the JLS. Bloch is simply saying that if you have circumstance A, throw this exception. He is not saying that this exception is/should be thrown only in this condition. The JLS is saying this exception is thrown if A, B, or C.

Answer 2

Given a library, it should throw an IllegalStateException or IllegalArgumentException whenever it detects a bug due to the user code, whereas the library should throw an AssertionError whenever it detects a bug due to the library's own implementation.

For example, in the library's tests, you may expect the library throws an IllegalStateException when the order of method calls are wrong. But you will never expect the library throws an AssertionError.

Answer 3

Here is an example in the JDK. There is a package private class called java.lang.Shutdown. If the system is shutting down and you attempt to add a new hook, it throws the IllegalStateException. One could argue that this meets the criteria of the "javadoc" guidance - since it is the Java environment that is in the wrong state.

class Shutdown {    
...

   /* Add a new shutdown hook.  Checks the shutdown state and the hook itself,
    * but does not do any security checks.
    */
    static void add(int slot, Runnable hook) {
        synchronized (lock) {
            if (state > RUNNING)
                throw new IllegalStateException("Shutdown in progress");

            if (hooks[slot] != null)
                throw new InternalError("Shutdown hook at slot " + slot + " already registered");

            hooks[slot] = hook;
        }
    }

However it also illustrates that there really is no distinction between the "javadoc" guidance and the "Effective Java" guidance. Because of the way Shutdown is implemented, the shutdown-ness of the JVM is stored in a field called state. Therefore it also meets the "Effective Java" guidance for when to use IllegalStateException, since the "state" field is part of the state of the receiving object. Since the receiving object (Shutdown) is in the wrong state, it throws the IllegalStateException.

In my opinion the two descriptions of when to use IllegalStateException are consistent. The Effective Java description is a bit more practical, that's all. For most of us, the most important part of the entire Java environment is the class that we are writing right now, so that is what the author is focusing on.

Answer 4

Here is one particularly legitimate usage of this exception in JDK (see: URLConnection.setIfModifiedSince(long) among 300+ other usages of it:

public void setIfModifiedSince(long ifmodifiedsince) {
    if (connected)
        throw new IllegalStateException("Already connected");
    ifModifiedSince = ifmodifiedsince;
}

I think the example is pretty clear. If the object is in particular state ("Already connected"), some operations should not be called. In this case when connection was established, some properties cannot be set.

This exception is especially useful when your class has some state (state machine?) that changes over time, making some methods irrelevant or impossible. Think about a Car class that has start(), stop() and fuel() methods. While calling start() twice, one after another, is probably nothing wrong, but fueling a started car is certainly a bad idea. Namely - car is in a wrong state.

Arguably good API should not allow us to call methods in wrong state so that problems like that are discovered at compile time, not at runtime. In this particular example connecting to a URL should return a different object with a subset of methods, all of which are valid after connecting.

Answer 5

I ran into this with:

try {
    MessageDigest digest = MessageDigest.getInstance("SHA-1");
    ...
} catch (NoSuchAlgorithmException e) {
    throw new AssertionError(e);
}

I think it will be impractical for me to throw IllegalStateException here in place of AssertionException even though this falls into the "the Java environment" category.

Answer 6

I guess if you see usage of IllegalStateException I would say second if more appropriate. This exception is used in lot of packages

• java.net
• java.nio
• java.util
• java.util.concurrrent etc

To specify one example ArrayBlockingQueue.add throws this exception if queue is already full. Now full is state of the object and it is being invoked at inappropriate or Illegal time

I guess both means same but difference of wording.