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}