001/* 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2012-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.Closeable; 044 045/** 046 * Writes a JSON {@link JsonObject object} or {@link JsonArray array} structure 047 * to an output source. 048 * 049 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonWriter> 050 * 051 * <BR /><BR />The class {@link javax.json.Json} contains methods to create writers from 052 * output sources ({@link java.io.OutputStream} and {@link java.io.Writer}). 053 * 054 * <BR /><BR />The following example demonstrates how write an empty JSON object: 055 * 056 * <BR /><DIV CLASS=SNIP>{@code 057 * JsonWriter jsonWriter = Json.createWriter(...); 058 * jsonWriter.writeObject(Json.createObjectBuilder().build()); 059 * jsonWriter.close(); 060 * }</DIV> 061 * 062 * <BR /><BR />The class {@link JsonWriterFactory} also contains methods to create 063 * {@code JsonWriter} instances. A factory instance can be used to create 064 * multiple writer instances with the same configuration. This the preferred 065 * way to create multiple instances. A sample usage is shown in the following 066 * example: 067 * 068 * <BR /><DIV CLASS=SNIP>{@code 069 * JsonWriterFactory factory = Json.createWriterFactory(config); 070 * JsonWriter writer1 = factory.createWriter(...); 071 * JsonWriter writer2 = factory.createWriter(...); 072 * }</DIV> 073 */ 074public interface JsonWriter extends /*Auto*/Closeable { 075 076 /** 077 * Writes the specified JSON {@link JsonArray array} to the output 078 * source. This method needs to be called only once for a writer instance. 079 * 080 * @param array JSON array that is to be written to the output source 081 * @throws JsonException if the specified JSON object cannot be 082 * written due to i/o error (IOException would be cause of 083 * JsonException) 084 * @throws IllegalStateException if writeArray, writeObject, write or close 085 * method is already called 086 */ 087 void writeArray(JsonArray array); 088 089 /** 090 * Writes the specified JSON {@link JsonObject object} to the output 091 * source. This method needs to be called only once for a writer instance. 092 * 093 * @param object JSON object that is to be written to the output source 094 * @throws JsonException if the specified JSON object cannot be 095 * written due to i/o error (IOException would be cause of JsonException) 096 * @throws IllegalStateException if writeArray, writeObject, write or close 097 * method is already called 098 */ 099 void writeObject(JsonObject object); 100 101 /** 102 * Writes the specified JSON {@link JsonObject object} or 103 * {@link JsonArray array} to the output source. This method needs 104 * to be called only once for a writer instance. 105 * 106 * @param value JSON array or object that is to be written to the output 107 * source 108 * @throws JsonException if the specified JSON object cannot be 109 * written due to i/o error (IOException would be cause of 110 * JsonException) 111 * @throws IllegalStateException if writeArray, writeObject, write 112 * or close method is already called 113 */ 114 void write(JsonStructure value); 115 116 /** 117 * Closes this JSON writer and frees any resources associated with the 118 * writer. This method closes the underlying output source. 119 * 120 * @throws JsonException if an i/o error occurs (IOException would be 121 * cause of JsonException) 122 */ 123 124 /** 125 * Writes the specified {@link JsonValue} to the output source. 126 * method needs to be called only once for a write instance. 127 * 128 * @param value a {@code JsonValue} to be written to the output 129 * source 130 * @throws JsonException if the specified JSON object cannot be 131 * written due to i/o error (IOException would be cause of 132 * JsonException) 133 * @throws IllegalStateException if writeArray, writeObject, write 134 * or close method is already called 135 * 136 * @since 1.1 137 */ 138 default void write(JsonValue value) { 139 throw new UnsupportedOperationException(); 140 } 141 142 @Override 143 void close(); 144 145}