001/*
002 * Copyright (C) 2014 Square, Inc.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *    https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package io.avaje.jsonb;
017
018import io.avaje.jsonb.spi.PropertyNames;
019
020import java.io.Closeable;
021import java.math.BigDecimal;
022import java.math.BigInteger;
023
024/**
025 * Reads json content as a stream of JSON tokens and content.
026 */
027public interface JsonReader extends Closeable {
028
029  /**
030   * Set the current property names.
031   * <p>
032   * Can be used by the reader to optimise the reading of known names.
033   */
034  void names(PropertyNames names);
035
036  /**
037   * Read array begin.
038   */
039  void beginArray();
040
041  /**
042   * Read array end.
043   */
044  void endArray();
045
046  /**
047   * Return true if there is a next element in an ARRAY.
048   */
049  boolean hasNextElement();
050
051  /**
052   * Read begin object.
053   */
054  void beginObject();
055
056  /**
057   * Read end object.
058   */
059  void endObject();
060
061  /**
062   * Return true if there is a next field to be read in an OBJECT.
063   */
064  boolean hasNextField();
065
066  /**
067   * Return the next field.
068   */
069  String nextField();
070
071  /**
072   * Return true if the value to be read is a null.
073   */
074  boolean isNullValue();
075
076  /**
077   * Read and return the next value as a boolean.
078   */
079  boolean readBoolean();
080
081  /**
082   * Read and return the next value as an int.
083   */
084  int readInt();
085
086  /**
087   * Read and return the next value as a long.
088   */
089  long readLong();
090
091  /**
092   * Read and return the next value as a double.
093   */
094  double readDouble();
095
096  /**
097   * Read and return the next value as a BigDecimal.
098   */
099  BigDecimal readDecimal();
100
101  /**
102   * Read and return the next value as a BigInteger.
103   */
104  BigInteger readBigInteger();
105
106  /**
107   * Read and return the next value as String.
108   */
109  String readString();
110
111  /**
112   * Read and return the binary value from base64.
113   */
114  byte[] readBinary();
115
116  /**
117   * Read and return raw json content as a String.
118   */
119  String readRaw();
120
121  /**
122   * Return the current location. This is typically used when reporting errors.
123   */
124  String location();
125
126  /**
127   * Return the current Token.
128   */
129  Token currentToken();
130
131  /**
132   * Close the resources of the reader.
133   */
134  void close();
135
136  /**
137   * Skip the next value.
138   */
139  void skipValue();
140
141  /**
142   * Reading json with an unmapped field, throw an Exception if failOnUnmapped is true.
143   */
144  void unmappedField(String fieldName);
145
146  /**
147   * A structure, name, or value type in a JSON-encoded string.
148   */
149  enum Token {
150
151    /**
152     * The opening of a JSON array. Written using {@link JsonWriter#beginArray} and read using
153     * {@link JsonReader#beginArray}.
154     */
155    BEGIN_ARRAY,
156
157//    /**
158//     * The closing of a JSON array. Written using {@link JsonWriter#endArray} and read using {@link
159//     * JsonReader#endArray}.
160//     */
161//    END_ARRAY,
162
163    /**
164     * The opening of a JSON object. Written using {@link JsonWriter#beginObject} and read using
165     * {@link JsonReader#beginObject}.
166     */
167    BEGIN_OBJECT,
168
169//    /**
170//     * The closing of a JSON object. Written using {@link JsonWriter#endObject} and read using
171//     * {@link JsonReader#endObject}.
172//     */
173//    END_OBJECT,
174//
175//    /**
176//     * A JSON property name. Within objects, tokens alternate between names and their values.
177//     * Written using {@link JsonWriter#name} and read using {@link JsonReader#nextField()}
178//     */
179//    NAME,
180
181    /**
182     * A JSON string.
183     */
184    STRING,
185
186    /**
187     * A JSON number represented in this API by a Java {@code double}, {@code long}, or {@code int}.
188     */
189    NUMBER,
190
191    /**
192     * A JSON {@code true} or {@code false}.
193     */
194    BOOLEAN,
195
196    /**
197     * A JSON {@code null}.
198     */
199    NULL,
200
201//    /**
202//     * The end of the JSON stream. This sentinel value is returned by {@link JsonReader#peek()} to
203//     * signal that the JSON-encoded value has no more tokens.
204//     */
205//    END_DOCUMENT
206  }
207}