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}