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}