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 java.io.OutputStream;
044import java.io.Writer;
045import java.nio.charset.Charset;
046import java.util.Map;
047
048/**
049 * Factory to create {@link JsonGenerator} instances. If a factory
050 * instance is configured with some configuration, the configuration applies
051 * to all generator instances created using that factory instance.
052 *
053 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonGeneratorFactory>
054 * 
055 * <BR /><BR />
056 * The class {@link javax.json.Json Json} also provides methods to create
057 * {@link JsonGenerator} instances, but using {@code JsonGeneratorFactory} is
058 * preferred when creating multiple generator instances as shown in the
059 * following example:
060 * 
061 * <BR /><DIV CLASS=SNIP>{@code
062 * JsonGeneratorFactory factory     = Json.createGeneratorFactory();
063 * JsonGenerator        generator1  = factory.createGenerator(...);
064 * JsonGenerator        generator2  = factory.createGenerator(...);
065 * }</DIV>
066 *
067 * <BR /><BR />All the methods in this class are safe for use by multiple concurrent
068 * threads.
069 */
070public interface JsonGeneratorFactory {
071
072    /**
073     * Creates a JSON generator to write JSON text to a character stream.
074     * The generator is configured with the factory configuration.
075     *
076     * @param writer i/o writer to which JSON is written
077     * @return the created JSON generator
078     */
079    JsonGenerator createGenerator(Writer writer);
080
081    /**
082     * Creates a JSON generator to write JSON text to a byte stream. Characters 
083     * written to the stream are encoded into bytes using UTF-8 encoding. 
084     * The generator is configured with the factory's configuration.
085     *
086     * @param out i/o stream to which JSON is written
087     * @return the created JSON generator
088     */
089    JsonGenerator createGenerator(OutputStream out);
090
091    /**
092     * Creates a JSON generator to write JSON text to a byte stream. Characters 
093     * written to the stream are encoded into bytes using the specified charset. 
094     * The generator is configured with the factory's configuration.
095     *
096     * @param out i/o stream to which JSON is written
097     * @param charset a charset
098     * @return the created JSON generator
099     */
100    JsonGenerator createGenerator(OutputStream out, Charset charset);
101
102    /**
103     * Returns a read-only map of supported provider specific configuration
104     * properties that are used to configure the JSON generators.
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 created generators. The map may be empty but not null
110     */
111    Map<String, ?> getConfigInUse();
112
113}