001/*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
005 *
006 * The contents of this file are subject to the terms of either the GNU
007 * General Public License Version 2 only ("GPL") or the Common Development
008 * and Distribution License("CDDL") (collectively, the "License").  You
009 * may not use this file except in compliance with the License.  You can
010 * obtain a copy of the License at
011 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
012 * or LICENSE.txt.  See the License for the specific
013 * language governing permissions and limitations under the License.
014 *
015 * When distributing the software, include this License Header Notice in each
016 * file and include the License file at LICENSE.txt.
017 *
018 * GPL Classpath Exception:
019 * Oracle designates this particular file as subject to the "Classpath"
020 * exception as provided by Oracle in the GPL Version 2 section of the License
021 * file that accompanied this code.
022 *
023 * Modifications:
024 * If applicable, add the following below the License Header, with the fields
025 * enclosed by brackets [] replaced by your own identifying information:
026 * "Portions Copyright [year] [name of copyright owner]"
027 *
028 * Contributor(s):
029 * If you wish your version of this file to be governed by only the CDDL or
030 * only the GPL Version 2, indicate your decision by adding "[Contributor]
031 * elects to include this software in this distribution under the [CDDL or GPL
032 * Version 2] license."  If you don't indicate a single choice of license, a
033 * recipient has the option to distribute your version of this file under
034 * either the CDDL, the GPL Version 2 or to extend the choice of license to
035 * its licensees as provided above.  However, if you add GPL Version 2 code
036 * and therefore, elected the GPL Version 2 license, then the option applies
037 * only if the new code is made subject to such option by the copyright
038 * holder.
039 */
040
041package javax.json;
042
043import java.io.Closeable;
044
045/**
046 * Reads a JSON {@link JsonObject object} or an {@link JsonArray array}
047 * structure from an input source.
048 *
049 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonReader>
050 * 
051 * <BR /><BR />The class {@link javax.json.Json} contains methods to create readers from
052 * input sources ({@link java.io.InputStream} and {@link java.io.Reader}).
053 *
054 * <BR /><BR />The following example demonstrates how to read an empty JSON array from
055 * a string:
056 *
057 * <BR /><DIV CLASS=SNIP>{@code
058 * JsonReader   jsonReader  = Json.createReader(new StringReader("[]"));
059 * JsonArray    array       = jsonReader.readArray();
060 * 
061 * jsonReader.close();
062 * }</DIV>
063 *
064 * <BR /><BR />
065 * The class {@link JsonReaderFactory} also contains methods to create
066 * {@code JsonReader} instances. A factory instance can be used to create
067 * multiple reader instances with the same configuration. This the preferred
068 * way to create multiple instances. A sample usage is shown in the following
069 * example:
070 * 
071 * <BR /><DIV CLASS=SNIP>{@code
072 * JsonReaderFactory    factory = Json.createReaderFactory(config);
073 * JsonReader           reader1 = factory.createReader(...);
074 * JsonReader           reader2 = factory.createReader(...);
075 * }</DIV>
076 */
077public interface JsonReader extends  /*Auto*/Closeable {
078
079    /**
080     * Returns a JSON array or object that is represented in
081     * the input source. This method needs to be called
082     * only once for a reader instance.
083     *
084     * @return a JSON object or array
085     * @throws JsonException if a JSON object or array cannot
086     *     be created due to i/o error (IOException would be
087     * cause of JsonException)
088     * @throws javax.json.stream.JsonParsingException if a JSON object or array
089     *     cannot be created due to incorrect representation
090     * @throws IllegalStateException if read, readObject, readArray,
091     *     readValue or close method is already called
092     */
093    JsonStructure read();
094
095    /**
096     * Returns a JSON object that is represented in
097     * the input source. This method needs to be called
098     * only once for a reader instance.
099     *
100     * @return a JSON object
101     * @throws JsonException if a JSON object cannot
102     *     be created due to i/o error (IOException would be
103     *     cause of JsonException)
104     * @throws javax.json.stream.JsonParsingException if a JSON object cannot
105     *     be created due to incorrect representation
106     * @throws IllegalStateException if read, readObject, readArray,
107     *     readValue or close method is already called
108     */
109    JsonObject readObject();
110
111    /**
112     * Returns a JSON array that is represented in
113     * the input source. This method needs to be called
114     * only once for a reader instance.
115     *
116     * @return a JSON array
117     * @throws JsonException if a JSON array cannot
118     *     be created due to i/o error (IOException would be
119     *     cause of JsonException)
120     * @throws javax.json.stream.JsonParsingException if a JSON array cannot
121     *     be created due to incorrect representation
122     * @throws IllegalStateException if read, readObject, readArray,
123     *     readValue or close method is already called
124     */
125    JsonArray readArray();
126
127    /**
128     * Returns a JSON value that is represented in
129     * the input source. This method needs to be called
130     * only once for a reader instance.
131     *
132     * @return a JSON value
133     * @throws JsonException if a JSON value
134     *     be created due to i/o error (IOException would be
135     *     cause of JsonException)
136     * @throws javax.json.stream.JsonParsingException if a JSON value
137     *     cannot be created due to incorrect representation
138     * @throws IllegalStateException if read, readObject, readArray,
139     *     readValue or close method is already called
140     *
141     * @since 1.1
142     */
143    default JsonValue readValue() {
144        throw new UnsupportedOperationException();
145    }
146
147    /**
148     * Closes this reader and frees any resources associated with the
149     * reader. This method closes the underlying input source.
150     *
151     * @throws JsonException if an i/o error occurs (IOException would be
152     * cause of JsonException)
153     */
154    @Override
155    void close();
156
157}