JsonReader.java

/*
 * MIT License
 *
 * Copyright (c) 2017 Konrad Kleczkowski
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

package com.github.repaj.libjson.io;

import java.io.Closeable;

/**
 * An interface describing a JSON stream reader.
 * <p>
 * A JSON reader reads input from tokenizer one by one and converts it to
 * Java objects.
 * <p>
 * Readers have to check output consistency. If some inconsistency will occur,
 * {@link MalformedJsonException} is thrown.
 * <p>
 * If an I/O error will occur, all methods throws unchecked I/O exceptions
 * during operation, in this case {@link java.io.IOException} is wrapped in
 * {@link JsonIOException}.
 *
 * @author Konrad Kleczkowski
 * @see JsonTokenizer
 */
public interface JsonReader extends Closeable {
    /**
     * Reads {@link JsonTokenType#BEGIN_OBJECT BEGIN_OBJECT}.
     *
     * @throws JsonIOException    if I/O error occurs
     * @throws JsonParseException if next token is other than was expected
     */
    void nextBeginObject();

    /**
     * Reads {@link JsonTokenType#END_OBJECT END_OBJECT}.
     *
     * @throws JsonIOException    if I/O error occurs
     * @throws JsonParseException if next token is other than was expected
     */
    void nextEndObject();

    /**
     * Reads {@link JsonTokenType#BEGIN_ARRAY BEGIN_ARRAY}.
     *
     * @throws JsonIOException    if I/O error occurs
     * @throws JsonParseException if next token is other than was expected
     */
    void nextBeginArray();

    /**
     * Reads {@link JsonTokenType#END_ARRAY END_ARRAY}.
     *
     * @throws JsonIOException    if I/O error occurs
     * @throws JsonParseException if next token is other than was expected
     */
    void nextEndArray();

    /**
     * Reads {@link JsonTokenType#BOOLEAN BOOLEAN}.
     * <p>
     * If the next token is {@link JsonTokenType#NULL NULL}, then <code>null</code> is returned.
     *
     * @return converted JSON boolean to Java boolean if next token is of {@link JsonTokenType#BOOLEAN BOOLEAN} type,
     * otherwise <code>null</code> if next token is of {@link JsonTokenType#NULL NULL} type
     * @throws JsonIOException    if I/O error occurs
     * @throws JsonParseException if next token is other than was expected
     */
    Boolean nextBoolean();

    /**
     * Reads {@link JsonTokenType#NUMBER NUMBER}.
     * <p>
     * If the next token is {@link JsonTokenType#NULL NULL}, then <code>null</code> is returned.
     *
     * @return converted JSON number to Java number if next token is of {@link JsonTokenType#NUMBER NUMBER} type,
     * otherwise <code>null</code> if next token is of {@link JsonTokenType#NULL NULL} type
     * @throws JsonIOException    if I/O error occurs
     * @throws JsonParseException if next token is other than was expected
     */
    Number nextNumber();

    /**
     * Reads {@link JsonTokenType#STRING STRING}.
     * <p>
     * If next token is {@link JsonTokenType#NULL NULL}, then <code>null</code> is returned.
     *
     * @return converted JSON string to Java string if next token is of {@link JsonTokenType#STRING STRING} type,
     * otherwise <code>null</code> if next token is of {@link JsonTokenType#NULL NULL} type
     * @throws JsonIOException    if I/O error occurs
     * @throws JsonParseException if next token is other than was expected
     */
    String nextString();

    /**
     * Reads {@link JsonTokenType#NULL NULL}.
     *
     * @throws JsonIOException    if I/O error occurs
     * @throws JsonParseException if next token is other than was expected
     */
    void nextNull();

    /**
     * Returns <code>true</code> if next token is {@link JsonTokenType#BEGIN_OBJECT BEGIN_OBJECT}.
     *
     * @return <code>true</code> if next token is of specified type, otherwise <code>false</code>
     * @throws JsonIOException if I/O error occurs
     * @see JsonTokenType#BEGIN_OBJECT
     */
    boolean hasNextBeginObject();

    /**
     * Returns <code>true</code> if next token is {@link JsonTokenType#END_OBJECT END_OBJECT}.
     *
     * @return <code>true</code> if next token is of specified type, otherwise <code>false</code>
     * @throws JsonIOException if I/O error occurs
     * @see JsonTokenType#END_OBJECT
     */
    boolean hasNextEndObject();

    /**
     * Returns <code>true</code> if next token is {@link JsonTokenType#BEGIN_ARRAY BEGIN_ARRAY}.
     *
     * @return <code>true</code> if next token is of specified type, otherwise <code>false</code>
     * @throws JsonIOException if I/O error occurs
     * @see JsonTokenType#BEGIN_ARRAY
     */
    boolean hasNextBeginArray();

    /**
     * Returns <code>true</code> if next token is {@link JsonTokenType#END_ARRAY END_ARRAY}.
     *
     * @return <code>true</code> if next token is of specified type, otherwise <code>false</code>
     * @throws JsonIOException if I/O error occurs
     * @see JsonTokenType#END_ARRAY
     */
    boolean hasNextEndArray();

    /**
     * Returns <code>true</code> if next token is {@link JsonTokenType#BOOLEAN BOOLEAN}.
     *
     * @return <code>true</code> if next token is of specified type, otherwise <code>false</code>
     * @throws JsonIOException if I/O error occurs
     * @see JsonTokenType#BOOLEAN
     */
    boolean hasNextBoolean();

    /**
     * Returns <code>true</code> if next token is {@link JsonTokenType#NUMBER NUMBER}.
     *
     * @return <code>true</code> if next token is of specified type, otherwise <code>false</code>
     * @throws JsonIOException if I/O error occurs
     * @see JsonTokenType#NUMBER
     */
    boolean hasNextNumber();

    /**
     * Returns <code>true</code> if next token is {@link JsonTokenType#STRING STRING}.
     *
     * @return <code>true</code> if next token is of specified type, otherwise <code>false</code>
     * @throws JsonIOException if I/O error occurs
     * @see JsonTokenType#STRING
     */
    boolean hasNextString();

    /**
     * Returns <code>true</code> if next token is {@link JsonTokenType#NULL NULL}.
     *
     * @return <code>true</code> if next token is of specified type, otherwise <code>false</code>
     * @throws JsonIOException if I/O error occurs
     * @see JsonTokenType#NULL
     */
    boolean hasNextNull();
}