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 javax.json.JsonValue;
044import java.io.Closeable;
045import java.io.Flushable;
046import java.math.BigDecimal;
047import java.math.BigInteger;
048
049/**
050 * Writes JSON data to an output source in a streaming way. The class
051 * {@link javax.json.Json} contains methods to create generators for character
052 * or output streams ({@link java.io.Writer} and {@link java.io.OutputStream}).
053 *
054 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonGenerator>
055 * 
056 * <BR /><BR />
057 * The following example shows how to create a JSON generator:
058 * 
059 * <BR /><DIV CLASS=SNIP>{@code
060 * JsonGenerator generator = Json.createGenerator(...);
061 * }</DIV>
062 *
063 * <BR /><BR />
064 * The class {@link JsonGeneratorFactory} also contains methods to create
065 * {@code JsonGenerator} instances. {@link JsonGeneratorFactory} should be used
066 * when creating multiple generator instances, as in the following example:
067 * 
068 * <BR /><DIV CLASS=SNIP>{@code
069 * JsonGeneratorFactory factory     = Json.createGeneratorFactory();
070 * JsonGenerator        generator1  = factory.createGenerator(...);
071 * JsonGenerator        generator2  = factory.createGenerator(...);
072 * }</DIV>
073 *
074 * <BR /><BR />
075 * JSON objects can be created using {@code JsonGenerator} by calling the
076 * {@link #writeStartObject()} method and then adding name/value pairs with the
077 * {@code write} method.
078 * 
079 * <BR /><BR />
080 * The following example shows how to generate an empty JSON object:
081 * 
082 * <BR /><DIV CLASS=SNIP>{@code
083 * JsonGenerator generator = ...;
084 * generator.writeStartObject().writeEnd().close();
085 * }</DIV>
086 *
087 * <BR /><BR />JSON arrays can be created using {@code JsonGenerator} by calling the
088 * {@link #writeStartArray()} method and then adding values with the
089 * {@code write} method.
090 *
091 * <BR /><BR />The following example shows how to generate an empty JSON array:
092 * 
093 * <BR /><DIV CLASS=SNIP>{@code
094 * JsonGenerator generator = ...;
095 * generator.writeStartArray().writeEnd().close();
096 * }</DIV>
097 *
098 * <BR /><BR />
099 * Other JSON values (that are not JSON objects or arrays) can be created
100 * by calling the appropiate {@code write} methods.
101 * 
102 * <BR /><BR />The following example shows how to generate a JSON string:
103 * 
104 * <BR /><DIV CLASS=SNIP>{@code
105 * JsonGenerator generator = ...;
106 * generator.write("message").close();
107 * }</DIV>
108 *
109 * <BR /><BR />{@code JsonGenerator} methods can be chained as in the following example:
110 * 
111 * <DIV CLASS=EXAMPLE>{@code
112 * generator
113 *      .writeStartObject()
114 *          .write("firstName", "John")
115 *          .write("lastName", "Smith")
116 *          .write("age", 25)
117 *          .writeStartObject("address")
118 *              .write("streetAddress", "21 2nd Street")
119 *              .write("city", "New York")
120 *              .write("state", "NY")
121 *              .write("postalCode", "10021")
122 *          .writeEnd()
123 *          .writeStartArray("phoneNumber")
124 *              .writeStartObject()
125 *                  .write("type", "home")
126 *                  .write("number", "212 555-1234")
127 *              .writeEnd()
128 *              .writeStartObject()
129 *                  .write("type", "fax")
130 *                  .write("number", "646 555-4567")
131 *              .writeEnd()
132 *          .writeEnd()
133 *      .writeEnd();
134 * 
135 * generator.close();
136 * }</DIV>
137 *
138 * <BR />The example code above generates the following JSON (or equivalent):
139 * 
140 * <DIV CLASS=JSON>{@code
141 * {
142 *   "firstName": "John", "lastName": "Smith", "age": 25,
143 *   "address" : {
144 *       "streetAddress": "21 2nd Street",
145 *       "city": "New York",
146 *       "state": "NY",
147 *       "postalCode": "10021"
148 *   },
149 *   "phoneNumber": [
150 *       {"type": "home", "number": "212 555-1234"},
151 *       {"type": "fax", "number": "646 555-4567"}
152 *    ]
153 * }
154 * }</DIV>
155 *
156 * <BR />The generated JSON text must strictly conform to the grammar defined in
157 * <a target=_blank href="http://www.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
158 *
159 * @see javax.json.Json
160 * @see JsonGeneratorFactory
161 */
162public interface JsonGenerator extends Flushable, /*Auto*/Closeable {
163    /**
164     * Configuration property to generate JSON prettily. All providers
165     * must support this property. The value of the property could be
166     * be anything.
167     */
168    String PRETTY_PRINTING = "javax.json.stream.JsonGenerator.prettyPrinting" ;
169
170    /**
171     * Writes the JSON start object character. It starts a new child object
172     * context within which JSON name/value pairs can be written to the object.
173     * This method is valid only in an array context, field context or in no context (when a
174     * context is not yet started). This method can only be called once in
175     * no context.
176     *
177     * @return this generator
178     * @throws javax.json.JsonException if an i/o error occurs (IOException
179     * would be cause of JsonException)
180     * @throws JsonGenerationException if this method is called within an
181     *      object context or if it is called more than once in no context.
182     */
183    JsonGenerator writeStartObject();
184
185    /**
186     * Writes the JSON name/start object character pair in the current
187     * object context. It starts a new child object context within which JSON
188     * name/value pairs can be written to the object.
189     *
190     * @param name a name within the JSON name/object pair to be written
191     * @return this generator
192     * @throws javax.json.JsonException if an i/o error occurs (IOException
193     * would be cause of JsonException)
194     * @throws JsonGenerationException if this method is not called within an
195     *     object context
196     */
197    JsonGenerator writeStartObject(String name);
198
199    /**
200     * Writes the JSON name with a colon. It starts a field context, in which valid
201     * options are writing a value, starting an object or an array.
202     *
203     * Writing value closes field context, if object or array is started after field name,
204     * field context will be closed after object/array close.
205     *
206     * @param name name of json field
207     * @return this generator
208     * @throws javax.json.JsonException if an i/o error occurs (IOException
209     * would be cause of JsonException)
210     * @throws JsonGenerationException if this method is not called within an
211     *     object context
212     *
213     * @since 1.1
214     */
215    JsonGenerator writeKey(String name);
216
217    /**
218     * Writes the JSON start array character. It starts a new child array
219     * context within which JSON values can be written to the array. This
220     * method is valid only in an array context, field context or in no context (when a
221     * context is not yet started). This method can only be called once in
222     * no context.
223     *
224     * @return this generator
225     * @throws javax.json.JsonException if an i/o error occurs (IOException
226     * would be cause of JsonException)
227     * @throws JsonGenerationException if this method is called within an
228     *      object context or if called more than once in no context
229     */
230    JsonGenerator writeStartArray();
231
232    /**
233     * Writes the JSON name/start array character pair with in the current
234     * object context. It starts a new child array context within which JSON
235     * values can be written to the array.
236     *
237     * @param name a name within the JSON name/array pair to be written
238     * @return this generator
239     * @throws javax.json.JsonException if an i/o error occurs (IOException
240     * would be cause of JsonException)
241     * @throws JsonGenerationException if this method is not called within
242     *      an object context
243     */
244    JsonGenerator writeStartArray(String name);
245
246    /**
247     * Writes a JSON name/value pair in the current object context.
248     *
249     * @param name a name in the JSON name/value pair to be written in
250     *             current JSON object
251     * @param value a value in the JSON name/value pair to be written in
252     *             current JSON object
253     * @return this generator
254     * @throws javax.json.JsonException if an i/o error occurs (IOException
255     * would be cause of JsonException)
256     * @throws JsonGenerationException if this method is not called within an
257     *      object context
258     */
259    JsonGenerator write(String name, JsonValue value);
260
261    /**
262     * Writes a JSON name/string value pair in the current object context.
263     * The specified value is written as JSON string value.
264     *
265     * @param name a name in the JSON name/string pair to be written in
266     *             current JSON object
267     * @param value a value in the JSON name/string pair to be written in
268     *             current JSON object
269     * @return this generator
270     * @throws javax.json.JsonException if an i/o error occurs (IOException
271     * would be cause of JsonException)
272     * @throws JsonGenerationException if this method is not called within an
273     *      object context
274     */
275    JsonGenerator write(String name, String value);
276
277    /**
278     * Writes a JSON name/number value pair in the current object context.
279     * The specified value is written as a JSON number value. The string
280     * {@code new BigDecimal(value).toString()}
281     * is used as the text value for writing.
282     *
283     * @param name a name in the JSON name/number pair to be written in
284     *             current JSON object
285     * @param value a value in the JSON name/number pair to be written in
286     *             current JSON object
287     * @return this generator
288     * @throws javax.json.JsonException if an i/o error occurs (IOException
289     * would be cause of JsonException)
290     * @throws JsonGenerationException if this method is not called within an
291     *      object context.
292     */
293    JsonGenerator write(String name, BigInteger value);
294
295    /**
296     * Writes a JSON name/number value pair in the current object context.
297     * The specified value is written as a JSON number value. The specified
298     * value's {@code toString()} is used as the text value for writing.
299     *
300     * @param name a name in the JSON name/number pair to be written in
301     *             current JSON object
302     * @param value a value in the JSON name/number pair to be written in
303     *             current JSON object
304     * @return this generator
305     * @throws javax.json.JsonException if an i/o error occurs (IOException
306     * would be cause of JsonException)
307     * @throws JsonGenerationException if this method is not called within an
308     *      object context.
309     */
310    JsonGenerator write(String name, BigDecimal value);
311
312    /**
313     * Writes a JSON name/number value pair in the current object context.
314     * The specified value is written as a JSON number value. The string
315     * {@code new BigDecimal(value).toString()} is used as the text value
316     * for writing.
317     *
318     * @param name a name in the JSON name/number pair to be written in
319     *             current JSON object
320     * @param value a value in the JSON name/number pair to be written in
321     *             current JSON object
322     * @return this generator
323     * @throws javax.json.JsonException if an i/o error occurs (IOException
324     * would be cause of JsonException)
325     * @throws JsonGenerationException if this method is not called within an
326     *      object context.
327     */
328    JsonGenerator write(String name, int value);
329
330    /**
331     * Writes a JSON name/number value pair in the current object context.
332     * The specified value is written as a JSON number value. The string
333     * {@code new BigDecimal(value).toString()} is used as the text
334     * value for writing.
335     *
336     * @param name a name in the JSON name/number pair to be written in
337     *             current JSON object
338     * @param value a value in the JSON name/number pair to be written in
339     *             current JSON object
340     * @return this generator
341     * @throws javax.json.JsonException if an i/o error occurs (IOException
342     * would be cause of JsonException)
343     * @throws JsonGenerationException if this method is not called within an
344     *      object context.
345     */
346    JsonGenerator write(String name, long value);
347
348    /**
349     * Writes a JSON name/number value pair in the current object context.
350     * The specified value is written as a JSON number value. The string
351     * {@code BigDecimal.valueOf(double).toString()}
352     * is used as the text value for writing.
353     *
354     * @param name a name in the JSON name/number pair to be written in
355     *             current JSON object
356     * @param value a value in the JSON name/number pair to be written in
357     *             current JSON object
358     * @return this generator
359     * @throws javax.json.JsonException if an i/o error occurs (IOException
360     * would be cause of JsonException)
361     * @throws NumberFormatException if the value is Not-a-Number (NaN) or infinity.
362     * @throws JsonGenerationException if this method is not called within an
363     *      object context
364     */
365    JsonGenerator write(String name, double value);
366
367    /**
368     * Writes a JSON name/boolean value pair in the current object context.
369     * If value is true, it writes the JSON {@code true} value, otherwise
370     * it writes the JSON {@code false} value.
371     *
372     * @param name a name in the JSON name/boolean pair to be written in
373     *             current JSON object
374     * @param value a value in the JSON name/boolean pair to be written in
375     *             current JSON object
376     * @return this generator
377     * @throws javax.json.JsonException if an i/o error occurs (IOException
378     * would be cause of JsonException)
379     * @throws JsonGenerationException if this method is not called within an
380     *      object context.
381     */
382    JsonGenerator write(String name, boolean value);
383
384
385    /**
386     * Writes a JSON name/null value pair in an current object context.
387     *
388     * @param name a name in the JSON name/null pair to be written in
389     *             current JSON object
390     * @return this generator
391     * @throws javax.json.JsonException if an i/o error occurs (IOException
392     * would be cause of JsonException)
393     * @throws JsonGenerationException if this method is not called within an
394     *      object context
395     */
396    JsonGenerator writeNull(String name);
397
398    /**
399     * Writes the end of the current context. If the current context is
400     * an array context, this method writes the end-of-array character (']').
401     * If the current context is an object context, this method writes the
402     * end-of-object character ('}'). After writing the end of the current
403     * context, the parent context becomes the new current context.
404     * If parent context is field context, it is closed.
405     *
406     * @return this generator
407     * @throws javax.json.JsonException if an i/o error occurs (IOException
408     * would be cause of JsonException)
409     * @throws JsonGenerationException if this method is called in no context.
410     */
411    JsonGenerator writeEnd();
412
413    /**
414     * Writes the specified value as a JSON value within
415     * the current array, field or root context.
416     *
417     * @param value a value to be written in current JSON array
418     * @return this generator
419     * @throws javax.json.JsonException if an i/o error occurs (IOException
420     * would be cause of JsonException)
421     * @throws JsonGenerationException if this method is not called within an
422     *      array or root context.
423     */
424    JsonGenerator write(JsonValue value);
425
426    /**
427     * Writes the specified value as a JSON string value within
428     * the current array, field or root context.
429     *
430     * @param value a value to be written in current JSON array
431     * @return this generator
432     * @throws javax.json.JsonException if an i/o error occurs (IOException
433     * would be cause of JsonException)
434     * @throws JsonGenerationException if this method is not called within an
435     *      array or root context.
436     */
437    JsonGenerator write(String value);
438
439    /**
440     * Writes the specified value as a JSON number value within
441     * the current array, field or root context. The specified value's {@code toString()}
442     * is used as the the text value for writing.
443     *
444     * @param value a value to be written in current JSON array
445     * @return this generator
446     * @throws javax.json.JsonException if an i/o error occurs (IOException
447     * would be cause of JsonException)
448     * @throws JsonGenerationException if this method is not called within an
449     *      array or root context.
450     *
451     * @see javax.json.JsonNumber
452     */
453    JsonGenerator write(BigDecimal value);
454
455    /**
456     * Writes the specified value as a JSON number value within
457     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
458     * is used as the text value for writing.
459     *
460     * @param value a value to be written in current JSON array
461     * @return this generator.
462     * @throws javax.json.JsonException if an i/o error occurs (IOException
463     * would be cause of JsonException)
464     * @throws JsonGenerationException if this method is not called within an
465     *      array or root context.
466     *
467     * @see javax.json.JsonNumber
468     */
469    JsonGenerator write(BigInteger value);
470
471    /**
472     * Writes the specified value as a JSON number value within
473     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
474     * is used as the text value for writing.
475     *
476     * @param value a value to be written in current JSON array
477     * @return this generator
478     * @throws javax.json.JsonException if an i/o error occurs (IOException
479     * would be cause of JsonException)
480     * @throws JsonGenerationException if this method is not called within an
481     *      array or root context.
482     */
483    JsonGenerator write(int value);
484
485    /**
486     * Writes the specified value as a JSON number value within
487     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
488     * is used as the text value for writing.
489     *
490     * @param value a value to be written in current JSON array
491     * @return this generator
492     * @throws javax.json.JsonException if an i/o error occurs (IOException
493     * would be cause of JsonException)
494     * @throws JsonGenerationException if this method is not called within an
495     *      array or root context.
496     */
497    JsonGenerator write(long value);
498
499    /**
500     * Writes the specified value as a JSON number value within the current
501     * array, field or root context. The string {@code BigDecimal.valueOf(value).toString()}
502     * is used as the text value for writing.
503     *
504     * @param value a value to be written in current JSON array
505     * @return this generator
506     * @throws javax.json.JsonException if an i/o error occurs (IOException
507     * would be cause of JsonException)
508     * @throws JsonGenerationException if this method is not called within an
509     *      array or root context.
510     * @throws NumberFormatException if the value is Not-a-Number (NaN) or infinity.
511     */
512    JsonGenerator write(double value);
513
514    /**
515     * Writes a JSON true or false value within the current array, field or root context.
516     * If value is true, this method writes the JSON {@code true} value,
517     * otherwise it writes the JSON {@code false} value.
518     *
519     * @param value a {@code boolean} value
520     * @return this generator
521     * @throws javax.json.JsonException if an i/o error occurs (IOException
522     * would be cause of JsonException)
523     * @throws JsonGenerationException if this method is not called within an
524     *      array or root context.
525     */
526    JsonGenerator write(boolean value);
527
528    /**
529     * Writes a JSON null value within the current array, field or root context.
530     *
531     * @return this generator
532     * @throws javax.json.JsonException if an i/o error occurs (IOException
533     * would be cause of JsonException)
534     * @throws JsonGenerationException if this method is not called within an
535     *      array or root context.
536     */
537    JsonGenerator writeNull();
538
539    /**
540     * Closes this generator and frees any resources associated with it.
541     * This method closes the underlying output source.
542     *
543     * @throws javax.json.JsonException if an i/o error occurs (IOException
544     * would be cause of JsonException)
545     * @throws JsonGenerationException if an incomplete JSON is generated
546     */
547    @Override
548    void close();
549
550    /**
551     * Flushes the underlying output source. If the generator has saved
552     * any characters in a buffer, writes them immediately to the underlying
553     * output source before flushing it.
554     *
555     * @throws javax.json.JsonException if an i/o error occurs (IOException
556     * would be cause of JsonException)
557     */
558    @Override
559    void flush();
560
561}