Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document that JsonReader methods throw IllegalStateException #2670

Merged
merged 1 commit into from
Apr 30, 2024
Merged

Document that JsonReader methods throw IllegalStateException #2670

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 21 additions & 8 deletions gson/src/main/java/com/google/gson/stream/JsonReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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}.
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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}.
*
* <p>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;
Expand Down