Was ist die beabsichtigte Verwendung von IllegalStateException?

Dies kam heute in einer Diskussion mit einem Kollegen zur Sprache.

Die Javadocs für Java IllegalStateException sagen, dass es:

Signalisiert, dass eine Methode zu einem illegalen oder unangemessenen Zeitpunkt aufgerufen wurde. Mit anderen Worten, die Java-Umgebung oder Java-Anwendung befindet sich nicht in einem geeigneten Zustand für die angeforderte Operation.

Und effektives Java sagt (Punkt 60, Seite 248):

Eine weitere häufig wiederverwendete Ausnahme ist IllegalStateException. Dies ist im Allgemeinen die auszulösende Ausnahme, wenn der Aufruf aufgrund des Zustands des empfangenden Objekts illegal ist. Dies wäre beispielsweise die auszulösende Ausnahme, wenn der Aufrufer versucht, ein Objekt zu verwenden, bevor es ordnungsgemäß initialisiert wurde.

Hier scheint es eine kleine Diskrepanz zu geben. Der zweite Satz der Javadocs lässt es so klingen, als könnte die Ausnahme eine sehr breite Bedingung über den Java-Ausführungsstatus beschreiben, aber die Beschreibung in Effective Java lässt es so klingen, als würde sie für Bedingungen verwendet, die sich speziell auf den Status des Objekts beziehen, dessen Methode aufgerufen wurde.

Die Verwendungen, die ich im JDK gesehen habe (z. B. Sammlungen, Matcher) und in Guava scheinen definitiv in die Kategorie zu fallen, von der Effective Java spricht (“Dieses Objekt befindet sich in einem Zustand, in dem diese Methode nicht aufgerufen werden kann”). Dies scheint auch im Einklang mit IllegalStateExceptions Geschwister IllegalArgumentException.

Gibt es legitime IllegalStateException Verwendungen im JDK, die sich auf die “Java-Umgebung” oder “Java-Anwendung” beziehen? Oder befürworten Best-Practice-Leitfäden die Verwendung für den breiteren Ausführungsstatus? Wenn nicht, warum zum Teufel sind die Javadocs so formuliert? 😉

Hier ist eine besonders legitime Verwendung dieser Ausnahme im JDK (siehe: URLConnection.setIfModifiedSince(long) unter mehr als 300 anderen Verwendungen davon:

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

Ich denke, das Beispiel ist ziemlich klar. Befindet sich das Objekt in einem bestimmten Zustand (“Schon verbunden“), sollten einige Operationen nicht aufgerufen werden. In diesem Fall können einige Eigenschaften nicht festgelegt werden, wenn die Verbindung hergestellt wurde.

Diese Ausnahme ist besonders nützlich, wenn Ihre Klasse einen Zustand (Zustandsmaschine?) hat, der sich im Laufe der Zeit ändert, wodurch einige Methoden irrelevant oder unmöglich werden. Denken Sie an ein Car Klasse, die hat start(), stop() und fuel() Methoden. Beim Telefonieren start() zweimal nacheinander ist wahrscheinlich nichts falsch, aber ein gestartetes Auto zu tanken ist sicherlich eine schlechte Idee. Nämlich – Auto ist in einem falschen Zustand.

Eine wohl gute API sollte uns nicht erlauben, Methoden im falschen Zustand aufzurufen, sodass solche Probleme zur Kompilierzeit und nicht zur Laufzeit entdeckt werden. In diesem speziellen Beispiel sollte die Verbindung mit einer URL ein anderes Objekt mit einer Teilmenge von Methoden zurückgeben, die alle nach der Verbindung gültig sind.

Hier ist ein Beispiel im JDK. Es gibt eine private Paketklasse namens java.lang.Shutdown. Wenn das System heruntergefahren wird und Sie versuchen, einen neuen Hook hinzuzufügen, wird die IllegalStateException ausgelöst. Man könnte argumentieren, dass dies die Kriterien der “javadoc”-Anleitung erfüllt – da sich die Java-Umgebung im falschen Zustand befindet.

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;
        }
    }

Es zeigt jedoch auch, dass es wirklich keinen Unterschied zwischen der „Javadoc“-Anleitung und der „Effective Java“-Anleitung gibt. Aufgrund der Art und Weise, wie Shutdown implementiert wird, wird die Herunterfahrbarkeit der JVM in einem Feld namens state gespeichert. Daher erfüllt es auch die „Effective Java“-Anleitung für die Verwendung von IllegalStateException, da das Feld „state“ Teil des Status des empfangenden Objekts ist. Da sich das empfangende Objekt (Shutdown) im falschen Zustand befindet, löst es die IllegalStateException aus.

Meiner Meinung nach sind die beiden Beschreibungen, wann IllegalStateException verwendet werden soll, konsistent. Die effektive Java-Beschreibung ist etwas praktischer, das ist alles. Für die meisten von uns ist der wichtigste Teil der gesamten Java-Umgebung die Klasse, die wir gerade schreiben, also konzentriert sich der Autor darauf.

Ich denke, wenn Sie die Verwendung von sehen IllegalStateException Ich würde sagen, zweitens, wenn es angemessener ist. Diese Ausnahme wird in vielen Paketen verwendet

• java.net
• java.nio
• java.util
• java.util.concurrrent usw

Um ein Beispiel zu nennen ArrayBlockingQueue.add löst diese Ausnahme aus, wenn die Warteschlange bereits voll ist. Jetzt ist der Zustand des Objekts voll und es wird zu einem unpassenden oder illegalen Zeitpunkt aufgerufen

Ich denke, beides bedeutet dasselbe, aber unterschiedliche Formulierungen.

Bei einer Bibliothek sollte es eine werfen IllegalStateException oder IllegalArgumentException immer wenn es einen Fehler aufgrund des Benutzercodes erkennt, während die Bibliothek eine werfen sollte AssertionError immer dann, wenn es einen Fehler aufgrund der eigenen Implementierung der Bibliothek entdeckt.

Beispielsweise können Sie in den Tests der Bibliothek erwarten, dass die Bibliothek eine auslöst IllegalStateException wenn die Reihenfolge der Methodenaufrufe falsch ist. Aber Sie werden nie erwarten, dass die Bibliothek einen wirft AssertionError.

Hier gibt es keine “Diskrepanz”. Nichts in Blochs Formulierung schließt aus, was in der JLS steht. Bloch sagt einfach, dass, wenn Sie den Umstand A haben, diese Ausnahme auslösen. Er ist nicht sagen, dass diese Ausnahme ausgelöst wird/sollte nur in diesem Zustand. Die JLS sagt, dass diese Ausnahme ausgelöst wird, wenn A, B oder C.

Ich bin darauf gestoßen mit:

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

Ich denke, es wird für mich unpraktisch sein, zu werfen IllegalStateException hier anstelle von AssertionException obwohl dies in die Kategorie “die Java-Umgebung” fällt.