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.OutputStream;
044import java.io.Writer;
045import java.nio.charset.Charset;
046import java.util.Map;
047
048/**
049 * Factory to create {@link javax.json.JsonWriter} instances. If a factory
050 * instance is configured with some configuration, that would be
051 * used to configure the created writer instances.
052 *
053 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonWriterFactory>
054 * 
055 * <BR /><BR />{@link javax.json.JsonWriter} can also be created using {@link Json}'s
056 * {@code createWriter} methods. If multiple writer instances are created,
057 * then creating them using a writer factory is preferred.
058 * 
059 * <DIV CLASS=EXAMPLE>{@code
060 * JsonWriterFactory    factory = Json.createWriterFactory(...);
061 * JsonWriter           writer1 = factory.createWriter(...);
062 * JsonWriter           writer2 = factory.createWriter(...);
063 * }</DIV>
064 *
065 * <BR />All the methods in this class are safe for use by multiple concurrent
066 * threads.
067 */
068public interface JsonWriterFactory {
069
070    /**
071     * Creates a JSON writer to write a JSON {@link JsonObject object} or
072     * {@link JsonArray array} structure to the specified character stream.
073     * The writer is configured with the factory configuration.
074     *
075     * @param writer to which JSON object or array is written
076     * @return a JSON writer
077     */
078    JsonWriter createWriter(Writer writer);
079
080    /**
081     * Creates a JSON writer to write a JSON {@link JsonObject object} or
082     * {@link JsonArray array} structure to the specified byte stream.
083     * Characters written to the stream are encoded into bytes using UTF-8
084     * encoding. The writer is configured with the factory configuration.
085     *
086     * @param out to which JSON object or array is written
087     * @return a JSON writer
088     */
089    JsonWriter createWriter(OutputStream out);
090
091    /**
092     * Creates a JSON writer to write a JSON {@link JsonObject object} or
093     * {@link JsonArray array} structure to the specified byte stream.
094     * Characters written to the stream are encoded into bytes using the
095     * specified charset. The writer is configured with the factory
096     * configuration.
097     *
098     * @param out to which JSON object or array is written
099     * @param charset a charset
100     * @return a JSON writer
101     */
102    JsonWriter createWriter(OutputStream out, Charset charset);
103
104    /**
105     * Returns read-only map of supported provider specific configuration
106     * properties that are used to configure the created JSON writer objects.
107     * If there are any specified configuration properties that are not
108     * supported by the provider, they won't be part of the returned map.
109     *
110     * @return a map of supported provider specific properties that are used
111     * to configure the created writers. The map may be empty but not null.
112     */
113    Map<String, ?> getConfigInUse();
114
115}