source: josm/trunk/src/javax/json/JsonWriter.java@ 13611

Last change on this file since 13611 was 13231, checked in by Don-vip, 7 years ago

see #15682 - upgrade to JSR 374 (JSON Processing) API 1.1.2

File size: 5.7 KB
Line 
1/*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can
10 * obtain a copy of the License at
11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
12 * or LICENSE.txt. See the License for the specific
13 * language governing permissions and limitations under the License.
14 *
15 * When distributing the software, include this License Header Notice in each
16 * file and include the License file at LICENSE.txt.
17 *
18 * GPL Classpath Exception:
19 * Oracle designates this particular file as subject to the "Classpath"
20 * exception as provided by Oracle in the GPL Version 2 section of the License
21 * file that accompanied this code.
22 *
23 * Modifications:
24 * If applicable, add the following below the License Header, with the fields
25 * enclosed by brackets [] replaced by your own identifying information:
26 * "Portions Copyright [year] [name of copyright owner]"
27 *
28 * Contributor(s):
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41package javax.json;
42
43import java.io.Closeable;
44
45/**
46 * Writes a JSON {@link JsonObject object} or {@link JsonArray array} structure
47 * to an output source.
48 *
49 * <p>The class {@link javax.json.Json} contains methods to create writers from
50 * output sources ({@link java.io.OutputStream} and {@link java.io.Writer}).
51 *
52 * <p>
53 * The following example demonstrates how write an empty JSON object:
54 * <pre>
55 * <code>
56 * JsonWriter jsonWriter = Json.createWriter(...);
57 * jsonWriter.writeObject(Json.createObjectBuilder().build());
58 * jsonWriter.close();
59 * </code>
60 * </pre>
61 *
62 * <p>
63 * The class {@link JsonWriterFactory} also contains methods to create
64 * {@code JsonWriter} instances. A factory instance can be used to create
65 * multiple writer instances with the same configuration. This the preferred
66 * way to create multiple instances. A sample usage is shown in the following
67 * example:
68 * <pre>
69 * <code>
70 * JsonWriterFactory factory = Json.createWriterFactory(config);
71 * JsonWriter writer1 = factory.createWriter(...);
72 * JsonWriter writer2 = factory.createWriter(...);
73 * </code>
74 * </pre>
75 */
76public interface JsonWriter extends /*Auto*/Closeable {
77
78 /**
79 * Writes the specified JSON {@link JsonArray array} to the output
80 * source. This method needs to be called only once for a writer instance.
81 *
82 * @param array JSON array that is to be written to the output source
83 * @throws JsonException if the specified JSON object cannot be
84 * written due to i/o error (IOException would be cause of
85 * JsonException)
86 * @throws IllegalStateException if writeArray, writeObject, write or close
87 * method is already called
88 */
89 void writeArray(JsonArray array);
90
91 /**
92 * Writes the specified JSON {@link JsonObject object} to the output
93 * source. This method needs to be called only once for a writer instance.
94 *
95 * @param object JSON object that is to be written to the output source
96 * @throws JsonException if the specified JSON object cannot be
97 * written due to i/o error (IOException would be cause of JsonException)
98 * @throws IllegalStateException if writeArray, writeObject, write or close
99 * method is already called
100 */
101 void writeObject(JsonObject object);
102
103 /**
104 * Writes the specified JSON {@link JsonObject object} or
105 * {@link JsonArray array} to the output source. This method needs
106 * to be called only once for a writer instance.
107 *
108 * @param value JSON array or object that is to be written to the output
109 * source
110 * @throws JsonException if the specified JSON object cannot be
111 * written due to i/o error (IOException would be cause of
112 * JsonException)
113 * @throws IllegalStateException if writeArray, writeObject, write
114 * or close method is already called
115 */
116 void write(JsonStructure value);
117
118 /**
119 * Closes this JSON writer and frees any resources associated with the
120 * writer. This method closes the underlying output source.
121 *
122 * @throws JsonException if an i/o error occurs (IOException would be
123 * cause of JsonException)
124 */
125
126 /**
127 * Writes the specified {@link JsonValue} to the output source.
128 * method needs to be called only once for a write instance.
129 *
130 * @param value a {@code JsonValue} to be written to the output
131 * source
132 * @throws JsonException if the specified JSON object cannot be
133 * written due to i/o error (IOException would be cause of
134 * JsonException)
135 * @throws IllegalStateException if writeArray, writeObject, write
136 * or close method is already called
137 *
138 * @since 1.1
139 */
140 default void write(JsonValue value) {
141 throw new UnsupportedOperationException();
142 }
143
144 @Override
145 void close();
146
147}
Note: See TracBrowser for help on using the repository browser.