001/*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2013-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.InputStream;
044import java.io.Reader;
045import java.nio.charset.Charset;
046import java.util.Map;
047
048/**
049 * Factory to create {@link javax.json.JsonReader} instances. If a factory
050 * instance is configured with some configuration, that would be
051 * used to configure the created reader instances.
052 *
053 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonReaderFactory>
054 * 
055 * <BR /><BR />
056 * {@link javax.json.JsonReader} can also be created using {@link Json}'s
057 * {@code createReader} methods. If multiple reader instances are created,
058 * then creating them using a reader factory is preferred.
059 * 
060 * <DIV CLASS=EXAMPLE>{@code
061 * JsonReaderFactory    factory = Json.createReaderFactory(...);
062 * JsonReader           reader1 = factory.createReader(...);
063 * JsonReader           reader2 = factory.createReader(...);
064 * }</DIV>
065 *
066 * <BR />All the methods in this class are safe for use by multiple concurrent
067 * threads.
068 */
069public interface JsonReaderFactory {
070
071    /**
072     * Creates a JSON reader from a character stream. The reader is configured
073     * with the factory configuration.
074     *
075     * @param reader a reader from which JSON is to be read
076     * @return a JSON reader
077     */
078    JsonReader createReader(Reader reader);
079
080    /**
081     * Creates a JSON reader from a byte stream. The character encoding of
082     * the stream is determined as described in
083     * <a target=_blank href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
084     * The reader is configured with the factory configuration.
085     *
086     * @param in a byte stream from which JSON is to be read
087     * @return a JSON reader
088     */
089    JsonReader createReader(InputStream in);
090
091    /**
092     * Creates a JSON reader from a byte stream. The bytes of the stream
093     * are decoded to characters using the specified charset. The reader is
094     * configured with the factory configuration.
095     *
096     * @param in a byte stream from which JSON is to be read
097     * @param charset a charset
098     * @return a JSON reader
099     */
100    JsonReader createReader(InputStream in, Charset charset);
101
102    /**
103     * Returns read-only map of supported provider specific configuration
104     * properties that are used to configure the created JSON readers.
105     * If there are any specified configuration properties that are not
106     * supported by the provider, they won't be part of the returned map.
107     *
108     * @return a map of supported provider specific properties that are used
109     * to configure the readers. The map be empty but not null.
110     */
111    Map<String, ?> getConfigInUse();
112
113}