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}