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   * Return the current location. This is typically used when reporting errors.
113   */
114  String location();
115
116  /**
117   * Return the current Token.
118   */
119  Token currentToken();
120
121  /**
122   * Close the resources of the reader.
123   */
124  void close();
125
126  /**
127   * Skip the next value.
128   */
129  void skipValue();
130
131  /**
132   * Reading json with an unmapped field, throw an Exception if failOnUnmapped is true.
133   */
134  void unmappedField(String fieldName);
135
136  /**
137   * A structure, name, or value type in a JSON-encoded string.
138   */
139  enum Token {
140
141    /**
142     * The opening of a JSON array. Written using {@link JsonWriter#beginArray} and read using
143     * {@link JsonReader#beginArray}.
144     */
145    BEGIN_ARRAY,
146
147//    /**
148//     * The closing of a JSON array. Written using {@link JsonWriter#endArray} and read using {@link
149//     * JsonReader#endArray}.
150//     */
151//    END_ARRAY,
152
153    /**
154     * The opening of a JSON object. Written using {@link JsonWriter#beginObject} and read using
155     * {@link JsonReader#beginObject}.
156     */
157    BEGIN_OBJECT,
158
159//    /**
160//     * The closing of a JSON object. Written using {@link JsonWriter#endObject} and read using
161//     * {@link JsonReader#endObject}.
162//     */
163//    END_OBJECT,
164//
165//    /**
166//     * A JSON property name. Within objects, tokens alternate between names and their values.
167//     * Written using {@link JsonWriter#name} and read using {@link JsonReader#nextField()}
168//     */
169//    NAME,
170
171    /**
172     * A JSON string.
173     */
174    STRING,
175
176    /**
177     * A JSON number represented in this API by a Java {@code double}, {@code long}, or {@code int}.
178     */
179    NUMBER,
180
181    /**
182     * A JSON {@code true} or {@code false}.
183     */
184    BOOLEAN,
185
186    /**
187     * A JSON {@code null}.
188     */
189    NULL,
190
191//    /**
192//     * The end of the JSON stream. This sentinel value is returned by {@link JsonReader#peek()} to
193//     * signal that the JSON-encoded value has no more tokens.
194//     */
195//    END_DOCUMENT
196  }
197}