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

Last change on this file since 6869 was 6756, checked in by Don-vip, 11 years ago

fix #9590 - replace org.json with GPL-compliant jsonp + remove mention of old world image removed in r1680

File size: 5.3 KB
Line 
1/*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright (c) 2012-2013 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://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
12 * or packager/legal/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 packager/legal/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 * <a id="JsonWriterExample1"/>
54 * The following example demonstrates how write an empty JSON object:
55 * <pre>
56 * <code>
57 * JsonWriter jsonWriter = Json.createWriter(...);
58 * jsonWriter.writeObject(Json.createObjectBuilder().build());
59 * jsonWriter.close();
60 * </code>
61 * </pre>
62 *
63 * <p>
64 * The class {@link JsonWriterFactory} also contains methods to create
65 * {@code JsonWriter} instances. A factory instance can be used to create
66 * multiple writer instances with the same configuration. This the preferred
67 * way to create multiple instances. A sample usage is shown in the following
68 * example:
69 * <pre>
70 * <code>
71 * JsonWriterFactory factory = Json.createWriterFactory(config);
72 * JsonWriter writer1 = factory.createWriter(...);
73 * JsonWriter writer2 = factory.createWriter(...);
74 * </code>
75 * </pre>
76 *
77 * @author Jitendra Kotamraju
78 */
79public interface JsonWriter extends /*Auto*/Closeable {
80
81 /**
82 * Writes the specified JSON {@link JsonArray array} to the output
83 * source. This method needs to be called only once for a writer instance.
84 *
85 * @param array JSON array that is to be written to the output source
86 * @throws JsonException if the specified JSON object cannot be
87 * written due to i/o error (IOException would be cause of
88 * JsonException)
89 * @throws IllegalStateException if writeArray, writeObject, write or close
90 * method is already called
91 */
92 void writeArray(JsonArray array);
93
94 /**
95 * Writes the specified JSON {@link JsonObject object} to the output
96 * source. This method needs to be called only once for a writer instance.
97 *
98 * @param object JSON object that is to be written to the output source
99 * @throws JsonException if the specified JSON object cannot be
100 * written due to i/o error (IOException would be cause of JsonException)
101 * @throws IllegalStateException if writeArray, writeObject, write or close
102 * method is already called
103 */
104 void writeObject(JsonObject object);
105
106 /**
107 * Writes the specified JSON {@link JsonObject object} or
108 * {@link JsonArray array} to the output source. This method needs
109 * to be called only once for a writer instance.
110 *
111 * @param value JSON array or object that is to be written to the output
112 * source
113 * @throws JsonException if the specified JSON object cannot be
114 * written due to i/o error (IOException would be cause of
115 * JsonException)
116 * @throws IllegalStateException if writeArray, writeObject, write
117 * or close method is already called
118 */
119 void write(JsonStructure value);
120
121 /**
122 * Closes this JSON writer and frees any resources associated with the
123 * writer. This method closes the underlying output source.
124 *
125 * @throws JsonException if an i/o error occurs (IOException would be
126 * cause of JsonException)
127 */
128 @Override
129 void close();
130
131}
Note: See TracBrowser for help on using the repository browser.