io.avaje.json.JsonReader Maven / Gradle / Ivy
/*
* Copyright (C) 2014 Square, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.avaje.json;
import java.io.Closeable;
import java.math.BigDecimal;
import java.math.BigInteger;
/**
* Reads json content as a stream of JSON tokens and content.
*/
public interface JsonReader extends Closeable {
/**
* Unwrap and return the underlying JsonParser.
*
* When using avaje-jsonb-jackson this will return the underlying Jackson JsonParser.
*
*
{@code
*
* // when using avaje-jsonb-jackson
* var jacksonParser = jsonReader.unwrap(JsonParser.class);
*
* }
*/
T unwrap(Class type);
/**
* Read the beginning of an ARRAY or x-json-stream (new line delimited json content).
*/
default void beginStream() {
beginArray();
}
/**
* Read the end of an ARRAY or x-json-stream (new line delimited json content).
*/
default void endStream() {
endArray();
}
/**
* Return true if there is a next element in an ARRAY or x-json-stream (new line delimited json content).
*
* Effectively this allows for new line delimited rather than commas between array elements.
*/
default boolean hasNextStreamElement() {
return hasNextElement();
}
/**
* Read array begin.
*/
void beginArray();
/**
* Read array end.
*/
void endArray();
/**
* Return true if there is a next element in an ARRAY.
*/
boolean hasNextElement();
/**
* Set the current property names.
*
* Can be used by the reader to optimize the reading of known names.
*/
void beginObject(PropertyNames names);
/**
* Read begin object.
*/
void beginObject();
/**
* Read end object.
*/
void endObject();
/**
* Return true if there is a next field to be read in an OBJECT.
*/
boolean hasNextField();
/**
* Return the next field.
*/
String nextField();
/**
* Return true if the value to be read is a null.
*/
boolean isNullValue();
/**
* Read and return the next value as a boolean.
*/
boolean readBoolean();
/**
* Read and return the next value as an int.
*/
int readInt();
/**
* Read and return the next value as a long.
*/
long readLong();
/**
* Read and return the next value as a double.
*/
double readDouble();
/**
* Read and return the next value as a BigDecimal.
*/
BigDecimal readDecimal();
/**
* Read and return the next value as a BigInteger.
*/
BigInteger readBigInteger();
/**
* Read and return the next value as String.
*/
String readString();
/**
* Read and return the binary value from base64.
*/
byte[] readBinary();
/**
* Read and return raw json content as a String.
*/
String readRaw();
/**
* Return the current location. This is typically used when reporting errors.
*/
String location();
/**
* Return the current Token.
*/
Token currentToken();
/**
* Close the resources of the reader.
*/
void close();
/**
* Skip the next value.
*/
void skipValue();
/**
* Reading json with an unmapped field, throw an Exception if failOnUnmapped is true.
*/
void unmappedField(String fieldName);
/**
* Explicitly state if the streaming content contains ARRAY '[' and ']' tokens.
*
* The builtin avaje-jsonb parser detects this automatically. Effectively we only need
* to set this when we are using the Jackson core parser.
*
*
{@code
*
* try (JsonReader reader = jsonb.reader(arrayJson)) {
* // content contains ARRAY '[' and ']' tokens, use streamArray(true)
* Stream asStream = type.stream(reader.streamArray(true));
* asStream.forEach(...);
* }
*
* }
*
* @param streamArray When true the content is expected to contain ARRAY '[' and ']' tokens.
*/
default JsonReader streamArray(boolean streamArray) {
// do nothing by default, jackson specifically needs this option
return this;
}
/**
* A structure, name, or value type in a JSON-encoded string.
*/
enum Token {
/**
* The opening of a JSON array. Written using {@link JsonWriter#beginArray} and read using
* {@link JsonReader#beginArray}.
*/
BEGIN_ARRAY,
/**
* The opening of a JSON object. Written using {@link JsonWriter#beginObject} and read using
* {@link JsonReader#beginObject}.
*/
BEGIN_OBJECT,
/**
* A JSON string.
*/
STRING,
/**
* A JSON number represented in this API by a Java {@code double}, {@code long}, or {@code int}.
*/
NUMBER,
/**
* A JSON {@code true} or {@code false}.
*/
BOOLEAN,
/**
* A JSON {@code null}.
*/
NULL,
}
}