1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 | /* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved. * * The contents of this file are subject to the terms of either the GNU * General Public License Version 2 only ("GPL") or the Common Development * and Distribution License("CDDL") (collectively, the "License"). You * may not use this file except in compliance with the License. You can * obtain a copy of the License at * https://oss.oracle.com/licenses/CDDL+GPL-1.1 * or LICENSE.txt. See the License for the specific * language governing permissions and limitations under the License. * * When distributing the software, include this License Header Notice in each * file and include the License file at LICENSE.txt. * * GPL Classpath Exception: * Oracle designates this particular file as subject to the "Classpath" * exception as provided by Oracle in the GPL Version 2 section of the License * file that accompanied this code. * * Modifications: * If applicable, add the following below the License Header, with the fields * enclosed by brackets [] replaced by your own identifying information: * "Portions Copyright [year] [name of copyright owner]" * * Contributor(s): * If you wish your version of this file to be governed by only the CDDL or * only the GPL Version 2, indicate your decision by adding "[Contributor] * elects to include this software in this distribution under the [CDDL or GPL * Version 2] license." If you don't indicate a single choice of license, a * recipient has the option to distribute your version of this file under * either the CDDL, the GPL Version 2 or to extend the choice of license to * its licensees as provided above. However, if you add GPL Version 2 code * and therefore, elected the GPL Version 2 license, then the option applies * only if the new code is made subject to such option by the copyright * holder. */ package javax.json.stream; import javax.json.JsonValue; import java.io.Closeable; import java.io.Flushable; import java.math.BigDecimal; import java.math.BigInteger; /** * Writes JSON data to an output source in a streaming way. The class * {@link javax.json.Json} contains methods to create generators for character * or output streams ({@link java.io.Writer} and {@link java.io.OutputStream}). * * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonGenerator> * * <BR /><BR /> * The following example shows how to create a JSON generator: * * <BR /><DIV CLASS=SNIP>{@code * JsonGenerator generator = Json.createGenerator(...); * }</DIV> * * <BR /><BR /> * The class {@link JsonGeneratorFactory} also contains methods to create * {@code JsonGenerator} instances. {@link JsonGeneratorFactory} should be used * when creating multiple generator instances, as in the following example: * * <BR /><DIV CLASS=SNIP>{@code * JsonGeneratorFactory factory = Json.createGeneratorFactory(); * JsonGenerator generator1 = factory.createGenerator(...); * JsonGenerator generator2 = factory.createGenerator(...); * }</DIV> * * <BR /><BR /> * JSON objects can be created using {@code JsonGenerator} by calling the * {@link #writeStartObject()} method and then adding name/value pairs with the * {@code write} method. * * <BR /><BR /> * The following example shows how to generate an empty JSON object: * * <BR /><DIV CLASS=SNIP>{@code * JsonGenerator generator = ...; * generator.writeStartObject().writeEnd().close(); * }</DIV> * * <BR /><BR />JSON arrays can be created using {@code JsonGenerator} by calling the * {@link #writeStartArray()} method and then adding values with the * {@code write} method. * * <BR /><BR />The following example shows how to generate an empty JSON array: * * <BR /><DIV CLASS=SNIP>{@code * JsonGenerator generator = ...; * generator.writeStartArray().writeEnd().close(); * }</DIV> * * <BR /><BR /> * Other JSON values (that are not JSON objects or arrays) can be created * by calling the appropiate {@code write} methods. * * <BR /><BR />The following example shows how to generate a JSON string: * * <BR /><DIV CLASS=SNIP>{@code * JsonGenerator generator = ...; * generator.write("message").close(); * }</DIV> * * <BR /><BR />{@code JsonGenerator} methods can be chained as in the following example: * * <DIV CLASS=EXAMPLE>{@code * generator * .writeStartObject() * .write("firstName", "John") * .write("lastName", "Smith") * .write("age", 25) * .writeStartObject("address") * .write("streetAddress", "21 2nd Street") * .write("city", "New York") * .write("state", "NY") * .write("postalCode", "10021") * .writeEnd() * .writeStartArray("phoneNumber") * .writeStartObject() * .write("type", "home") * .write("number", "212 555-1234") * .writeEnd() * .writeStartObject() * .write("type", "fax") * .write("number", "646 555-4567") * .writeEnd() * .writeEnd() * .writeEnd(); * * generator.close(); * }</DIV> * * <BR />The example code above generates the following JSON (or equivalent): * * <DIV CLASS=JSON>{@code * { * "firstName": "John", "lastName": "Smith", "age": 25, * "address" : { * "streetAddress": "21 2nd Street", * "city": "New York", * "state": "NY", * "postalCode": "10021" * }, * "phoneNumber": [ * {"type": "home", "number": "212 555-1234"}, * {"type": "fax", "number": "646 555-4567"} * ] * } * }</DIV> * * <BR />The generated JSON text must strictly conform to the grammar defined in * <a target=_blank href="http://www.ietf.org/rfc/rfc7159.txt">RFC 7159</a>. * * @see javax.json.Json * @see JsonGeneratorFactory */ public interface JsonGenerator extends Flushable, /*Auto*/Closeable { /** * Configuration property to generate JSON prettily. All providers * must support this property. The value of the property could be * be anything. */ String PRETTY_PRINTING = "javax.json.stream.JsonGenerator.prettyPrinting" ; /** * Writes the JSON start object character. It starts a new child object * context within which JSON name/value pairs can be written to the object. * This method is valid only in an array context, field context or in no context (when a * context is not yet started). This method can only be called once in * no context. * * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is called within an * object context or if it is called more than once in no context. */ JsonGenerator writeStartObject(); /** * Writes the JSON name/start object character pair in the current * object context. It starts a new child object context within which JSON * name/value pairs can be written to the object. * * @param name a name within the JSON name/object pair to be written * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context */ JsonGenerator writeStartObject(String name); /** * Writes the JSON name with a colon. It starts a field context, in which valid * options are writing a value, starting an object or an array. * * Writing value closes field context, if object or array is started after field name, * field context will be closed after object/array close. * * @param name name of json field * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context * * @since 1.1 */ JsonGenerator writeKey(String name); /** * Writes the JSON start array character. It starts a new child array * context within which JSON values can be written to the array. This * method is valid only in an array context, field context or in no context (when a * context is not yet started). This method can only be called once in * no context. * * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is called within an * object context or if called more than once in no context */ JsonGenerator writeStartArray(); /** * Writes the JSON name/start array character pair with in the current * object context. It starts a new child array context within which JSON * values can be written to the array. * * @param name a name within the JSON name/array pair to be written * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within * an object context */ JsonGenerator writeStartArray(String name); /** * Writes a JSON name/value pair in the current object context. * * @param name a name in the JSON name/value pair to be written in * current JSON object * @param value a value in the JSON name/value pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context */ JsonGenerator write(String name, JsonValue value); /** * Writes a JSON name/string value pair in the current object context. * The specified value is written as JSON string value. * * @param name a name in the JSON name/string pair to be written in * current JSON object * @param value a value in the JSON name/string pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context */ JsonGenerator write(String name, String value); /** * Writes a JSON name/number value pair in the current object context. * The specified value is written as a JSON number value. The string * {@code new BigDecimal(value).toString()} * is used as the text value for writing. * * @param name a name in the JSON name/number pair to be written in * current JSON object * @param value a value in the JSON name/number pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context. */ JsonGenerator write(String name, BigInteger value); /** * Writes a JSON name/number value pair in the current object context. * The specified value is written as a JSON number value. The specified * value's {@code toString()} is used as the text value for writing. * * @param name a name in the JSON name/number pair to be written in * current JSON object * @param value a value in the JSON name/number pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context. */ JsonGenerator write(String name, BigDecimal value); /** * Writes a JSON name/number value pair in the current object context. * The specified value is written as a JSON number value. The string * {@code new BigDecimal(value).toString()} is used as the text value * for writing. * * @param name a name in the JSON name/number pair to be written in * current JSON object * @param value a value in the JSON name/number pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context. */ JsonGenerator write(String name, int value); /** * Writes a JSON name/number value pair in the current object context. * The specified value is written as a JSON number value. The string * {@code new BigDecimal(value).toString()} is used as the text * value for writing. * * @param name a name in the JSON name/number pair to be written in * current JSON object * @param value a value in the JSON name/number pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context. */ JsonGenerator write(String name, long value); /** * Writes a JSON name/number value pair in the current object context. * The specified value is written as a JSON number value. The string * {@code BigDecimal.valueOf(double).toString()} * is used as the text value for writing. * * @param name a name in the JSON name/number pair to be written in * current JSON object * @param value a value in the JSON name/number pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws NumberFormatException if the value is Not-a-Number (NaN) or infinity. * @throws JsonGenerationException if this method is not called within an * object context */ JsonGenerator write(String name, double value); /** * Writes a JSON name/boolean value pair in the current object context. * If value is true, it writes the JSON {@code true} value, otherwise * it writes the JSON {@code false} value. * * @param name a name in the JSON name/boolean pair to be written in * current JSON object * @param value a value in the JSON name/boolean pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context. */ JsonGenerator write(String name, boolean value); /** * Writes a JSON name/null value pair in an current object context. * * @param name a name in the JSON name/null pair to be written in * current JSON object * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * object context */ JsonGenerator writeNull(String name); /** * Writes the end of the current context. If the current context is * an array context, this method writes the end-of-array character (']'). * If the current context is an object context, this method writes the * end-of-object character ('}'). After writing the end of the current * context, the parent context becomes the new current context. * If parent context is field context, it is closed. * * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is called in no context. */ JsonGenerator writeEnd(); /** * Writes the specified value as a JSON value within * the current array, field or root context. * * @param value a value to be written in current JSON array * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. */ JsonGenerator write(JsonValue value); /** * Writes the specified value as a JSON string value within * the current array, field or root context. * * @param value a value to be written in current JSON array * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. */ JsonGenerator write(String value); /** * Writes the specified value as a JSON number value within * the current array, field or root context. The specified value's {@code toString()} * is used as the the text value for writing. * * @param value a value to be written in current JSON array * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. * * @see javax.json.JsonNumber */ JsonGenerator write(BigDecimal value); /** * Writes the specified value as a JSON number value within * the current array, field or root context. The string {@code new BigDecimal(value).toString()} * is used as the text value for writing. * * @param value a value to be written in current JSON array * @return this generator. * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. * * @see javax.json.JsonNumber */ JsonGenerator write(BigInteger value); /** * Writes the specified value as a JSON number value within * the current array, field or root context. The string {@code new BigDecimal(value).toString()} * is used as the text value for writing. * * @param value a value to be written in current JSON array * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. */ JsonGenerator write(int value); /** * Writes the specified value as a JSON number value within * the current array, field or root context. The string {@code new BigDecimal(value).toString()} * is used as the text value for writing. * * @param value a value to be written in current JSON array * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. */ JsonGenerator write(long value); /** * Writes the specified value as a JSON number value within the current * array, field or root context. The string {@code BigDecimal.valueOf(value).toString()} * is used as the text value for writing. * * @param value a value to be written in current JSON array * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. * @throws NumberFormatException if the value is Not-a-Number (NaN) or infinity. */ JsonGenerator write(double value); /** * Writes a JSON true or false value within the current array, field or root context. * If value is true, this method writes the JSON {@code true} value, * otherwise it writes the JSON {@code false} value. * * @param value a {@code boolean} value * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. */ JsonGenerator write(boolean value); /** * Writes a JSON null value within the current array, field or root context. * * @return this generator * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if this method is not called within an * array or root context. */ JsonGenerator writeNull(); /** * Closes this generator and frees any resources associated with it. * This method closes the underlying output source. * * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) * @throws JsonGenerationException if an incomplete JSON is generated */ @Override void close(); /** * Flushes the underlying output source. If the generator has saved * any characters in a buffer, writes them immediately to the underlying * output source before flushing it. * * @throws javax.json.JsonException if an i/o error occurs (IOException * would be cause of JsonException) */ @Override void flush(); } |