001/*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2011-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.stream;
042
043import javax.json.JsonArray;
044import javax.json.JsonObject;
045import java.io.InputStream;
046import java.io.Reader;
047import java.nio.charset.Charset;
048import java.util.Map;
049
050/**
051 * Factory for creating {@link JsonParser} instances. If a factory
052 * instance is configured with a configuration, the configuration applies
053 * to all parser instances created using that factory instance.
054 *
055 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonParserFactory>
056 * 
057 * <BR /><BR />
058 * The class {@link javax.json.Json Json} also provides methods to create
059 * {@link JsonParser} instances, but using {@code JsonParserFactory} is 
060 * preferred when creating multiple parser instances as shown in the following
061 * example:
062 *
063 * <BR /><DIV CLASS=SNIP>{@code
064 * JsonParserFactory    factory = Json.createParserFactory();
065 * JsonParser           parser1 = factory.createParser(...);
066 * JsonParser           parser2 = factory.createParser(...);
067 * }</DIV>
068 *
069 * <BR /><BR />All the methods in this class are safe for use by multiple concurrent
070 * threads.
071 */
072public interface JsonParserFactory {
073
074    /**
075     * Creates a JSON parser from a character stream.
076     *
077     * @param reader a i/o reader from which JSON is to be read
078     * @return the created JSON parser
079     */
080    JsonParser createParser(Reader reader);
081
082    /**
083     * Creates a JSON parser from the specified byte stream.
084     * The character encoding of the stream is determined
085     * as specified in
086     * <a target=_blank href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
087     *
088     * @param in i/o stream from which JSON is to be read
089     * @return the created JSON parser
090     * @throws javax.json.JsonException if encoding cannot be determined
091     *         or i/o error (IOException would be cause of JsonException)
092     */
093    JsonParser createParser(InputStream in);
094
095    /**
096     * Creates a JSON parser from the specified byte stream.
097     * The bytes of the stream are decoded to characters using the
098     * specified charset.
099     *
100     * @param in i/o stream from which JSON is to be read
101     * @param charset a charset
102     * @return the created JSON parser
103     */
104    JsonParser createParser(InputStream in, Charset charset);
105
106    /**
107     * Creates a JSON parser from the specified JSON object.
108     *
109     * @param obj a JSON object
110     * @return the created JSON parser
111     */
112    JsonParser createParser(JsonObject obj);
113
114    /**
115     * Creates a JSON parser from the specified JSON array.
116     *
117     * @param array a JSON array
118     * @return the created JSON parser
119     */
120    JsonParser createParser(JsonArray array);
121
122    /**
123     * Returns a read-only map of supported provider specific configuration
124     * properties that are used to configure the JSON parsers.
125     * If there are any specified configuration properties that are not
126     * supported by the provider, they won't be part of the returned map.
127     *
128     * @return a map of supported provider specific properties that are used
129     * to configure the created parsers. The map may be empty but not null
130     */
131    Map<String, ?> getConfigInUse();
132
133}