From 5120a5bc7f2dd94bc2cd486380d44ddb54cd4676 Mon Sep 17 00:00:00 2001 From: Marcono1234 Date: Tue, 30 Apr 2024 23:28:47 +0200 Subject: [PATCH] Document that `JsonReader` methods throw `IllegalStateException` --- .../com/google/gson/stream/JsonReader.java | 29 ++++++++++++++----- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/gson/src/main/java/com/google/gson/stream/JsonReader.java b/gson/src/main/java/com/google/gson/stream/JsonReader.java index 58be43afc1..5a213efc18 100644 --- a/gson/src/main/java/com/google/gson/stream/JsonReader.java +++ b/gson/src/main/java/com/google/gson/stream/JsonReader.java @@ -414,6 +414,8 @@ public final Strictness getStrictness() { /** * Consumes the next token from the JSON stream and asserts that it is the beginning of a new * array. + * + * @throws IllegalStateException if the next token is not the beginning of an array. */ public void beginArray() throws IOException { int p = peeked; @@ -432,6 +434,8 @@ public void beginArray() throws IOException { /** * Consumes the next token from the JSON stream and asserts that it is the end of the current * array. + * + * @throws IllegalStateException if the next token is not the end of an array. */ public void endArray() throws IOException { int p = peeked; @@ -450,6 +454,8 @@ public void endArray() throws IOException { /** * Consumes the next token from the JSON stream and asserts that it is the beginning of a new * object. + * + * @throws IllegalStateException if the next token is not the beginning of an object. */ public void beginObject() throws IOException { int p = peeked; @@ -467,6 +473,8 @@ public void beginObject() throws IOException { /** * Consumes the next token from the JSON stream and asserts that it is the end of the current * object. + * + * @throws IllegalStateException if the next token is not the end of an object. */ public void endObject() throws IOException { int p = peeked; @@ -857,7 +865,7 @@ private boolean isLiteral(char c) throws IOException { /** * Returns the next token, a {@link JsonToken#NAME property name}, and consumes it. * - * @throws IOException if the next token in the stream is not a property name. + * @throws IllegalStateException if the next token is not a property name. */ public String nextName() throws IOException { int p = peeked; @@ -883,7 +891,7 @@ public String nextName() throws IOException { * Returns the {@link JsonToken#STRING string} value of the next token, consuming it. If the next * token is a number, this method will return its string form. * - * @throws IllegalStateException if the next token is not a string or if this reader is closed. + * @throws IllegalStateException if the next token is not a string. */ public String nextString() throws IOException { int p = peeked; @@ -916,7 +924,7 @@ public String nextString() throws IOException { /** * Returns the {@link JsonToken#BOOLEAN boolean} value of the next token, consuming it. * - * @throws IllegalStateException if the next token is not a boolean or if this reader is closed. + * @throws IllegalStateException if the next token is not a boolean. */ public boolean nextBoolean() throws IOException { int p = peeked; @@ -938,7 +946,7 @@ public boolean nextBoolean() throws IOException { /** * Consumes the next token from the JSON stream and asserts that it is a literal null. * - * @throws IllegalStateException if the next token is not null or if this reader is closed. + * @throws IllegalStateException if the next token is not a JSON null. */ public void nextNull() throws IOException { int p = peeked; @@ -958,7 +966,7 @@ public void nextNull() throws IOException { * token is a string, this method will attempt to parse it as a double using {@link * Double#parseDouble(String)}. * - * @throws IllegalStateException if the next token is not a literal value. + * @throws IllegalStateException if the next token is neither a number nor a string. * @throws NumberFormatException if the next literal value cannot be parsed as a double. * @throws MalformedJsonException if the next literal value is NaN or Infinity and this reader is * not {@link #setStrictness(Strictness) lenient}. @@ -1002,7 +1010,7 @@ public double nextDouble() throws IOException { * token is a string, this method will attempt to parse it as a long. If the next token's numeric * value cannot be exactly represented by a Java {@code long}, this method throws. * - * @throws IllegalStateException if the next token is not a literal value. + * @throws IllegalStateException if the next token is neither a number nor a string. * @throws NumberFormatException if the next literal value cannot be parsed as a number, or * exactly represented as a long. */ @@ -1239,7 +1247,7 @@ private void skipUnquotedValue() throws IOException { * token is a string, this method will attempt to parse it as an int. If the next token's numeric * value cannot be exactly represented by a Java {@code int}, this method throws. * - * @throws IllegalStateException if the next token is not a literal value. + * @throws IllegalStateException if the next token is neither a number nor a string. * @throws NumberFormatException if the next literal value cannot be parsed as a number, or * exactly represented as an int. */ @@ -1293,7 +1301,12 @@ public int nextInt() throws IOException { return result; } - /** Closes this JSON reader and the underlying {@link Reader}. */ + /** + * Closes this JSON reader and the underlying {@link Reader}. + * + *

Using the JSON reader after it has been closed will throw an {@link IllegalStateException} + * in most cases. + */ @Override public void close() throws IOException { peeked = PEEKED_NONE;