Ignore:
Timestamp:
2017-12-23T02:40:43+01:00 (8 years ago)
Author:
Don-vip
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/javax/json/stream/JsonGenerator.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * 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
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    9898 * </pre>
    9999 *
     100 * <p>
     101 * Other JSON values (that are not JSON objects or arrays) can be created
     102 * by calling the appropiate {@code write} methods.
     103 * <p>
     104 * The following example shows how to generate a JSON string:
     105 * <pre><code>
     106 * JsonGenerator generator = ...;
     107 * generator.write("message").close();
     108 * </code></pre>
     109 *
    100110 * {@code JsonGenerator} methods can be chained as in the following example:
    101  * <p>
    102  * <a id="JsonGeneratorExample3"/>
    103111 * <pre>
    104112 * <code>
    … …  
    130138 *
    131139 * The example code above generates the following JSON (or equivalent):
    132  * <p>
    133140 * <pre>
    134141 * <code>
    … …  
    150157 *
    151158 * The generated JSON text must strictly conform to the grammar defined in
    152  * <a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
     159 * <a href="http://www.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
    153160 *
    154161 * @see javax.json.Json
    155162 * @see JsonGeneratorFactory
    156  * @author Jitendra Kotamraju
    157163 */
    158164public interface JsonGenerator extends Flushable, /*Auto*/Closeable {
    … …  
    167173     * Writes the JSON start object character. It starts a new child object
    168174     * context within which JSON name/value pairs can be written to the object.
    169      * This method is valid only in an array context or in no context (when a
     175     * This method is valid only in an array context, field context or in no context (when a
    170176     * context is not yet started). This method can only be called once in
    171177     * no context.
    … …  
    174180     * @throws javax.json.JsonException if an i/o error occurs (IOException
    175181     * would be cause of JsonException)
    176      * @throws JsonGenerationException if this method is called within an 
     182     * @throws JsonGenerationException if this method is called within an
    177183     *      object context or if it is called more than once in no context.
    178184     */
    … …  
    188194     * @throws javax.json.JsonException if an i/o error occurs (IOException
    189195     * would be cause of JsonException)
    190      * @throws JsonGenerationException if this method is not called within an 
     196     * @throws JsonGenerationException if this method is not called within an
    191197     *     object context
    192198     */
    193199    JsonGenerator writeStartObject(String name);
     200
     201    /**
     202     * Writes the JSON name with a colon. It starts a field context, in which valid
     203     * options are writing a value, starting an object or an array.
     204     *
     205     * Writing value closes field context, if object or array is started after field name,
     206     * field context will be closed after object/array close.
     207     *
     208     * @param name name of json field
     209     * @return this generator
     210     * @throws javax.json.JsonException if an i/o error occurs (IOException
     211     * would be cause of JsonException)
     212     * @throws JsonGenerationException if this method is not called within an
     213     *     object context
     214     *
     215     * @since 1.1
     216     */
     217    JsonGenerator writeKey(String name);
    194218
    195219    /**
    196220     * Writes the JSON start array character. It starts a new child array
    197221     * context within which JSON values can be written to the array. This
    198      * method is valid only in an array context or in no context (when a
     222     * method is valid only in an array context, field context or in no context (when a
    199223     * context is not yet started). This method can only be called once in
    200224     * no context.
    … …  
    203227     * @throws javax.json.JsonException if an i/o error occurs (IOException
    204228     * would be cause of JsonException)
    205      * @throws JsonGenerationException if this method is called within an 
     229     * @throws JsonGenerationException if this method is called within an
    206230     *      object context or if called more than once in no context
    207231     */
    … …  
    217241     * @throws javax.json.JsonException if an i/o error occurs (IOException
    218242     * would be cause of JsonException)
    219      * @throws JsonGenerationException if this method is not called within 
     243     * @throws JsonGenerationException if this method is not called within
    220244     *      an object context
    221245     */
    … …  
    232256     * @throws javax.json.JsonException if an i/o error occurs (IOException
    233257     * would be cause of JsonException)
    234      * @throws JsonGenerationException if this method is not called within an 
     258     * @throws JsonGenerationException if this method is not called within an
    235259     *      object context
    236260     */
    … …  
    248272     * @throws javax.json.JsonException if an i/o error occurs (IOException
    249273     * would be cause of JsonException)
    250      * @throws JsonGenerationException if this method is not called within an 
     274     * @throws JsonGenerationException if this method is not called within an
    251275     *      object context
    252276     */
    … …  
    266290     * @throws javax.json.JsonException if an i/o error occurs (IOException
    267291     * would be cause of JsonException)
    268      * @throws JsonGenerationException if this method is not called within an 
     292     * @throws JsonGenerationException if this method is not called within an
    269293     *      object context.
    270294     */
    … …  
    283307     * @throws javax.json.JsonException if an i/o error occurs (IOException
    284308     * would be cause of JsonException)
    285      * @throws JsonGenerationException if this method is not called within an 
     309     * @throws JsonGenerationException if this method is not called within an
    286310     *      object context.
    287311     */
    … …  
    301325     * @throws javax.json.JsonException if an i/o error occurs (IOException
    302326     * would be cause of JsonException)
    303      * @throws JsonGenerationException if this method is not called within an 
     327     * @throws JsonGenerationException if this method is not called within an
    304328     *      object context.
    305329     */
    … …  
    319343     * @throws javax.json.JsonException if an i/o error occurs (IOException
    320344     * would be cause of JsonException)
    321      * @throws JsonGenerationException if this method is not called within an 
     345     * @throws JsonGenerationException if this method is not called within an
    322346     *      object context.
    323347     */
    … …  
    337361     * @throws javax.json.JsonException if an i/o error occurs (IOException
    338362     * would be cause of JsonException)
    339      * @throws NumberFormatException if the value is Not-a-Number(NaN) or infinity.
     363     * @throws NumberFormatException if the value is Not-a-Number (NaN) or infinity.
    340364     * @throws JsonGenerationException if this method is not called within an
    341365     *      object context
    … …  
    345369    /**
    346370     * Writes a JSON name/boolean value pair in the current object context.
    347      * If value is true, it writes the JSON {@code true} value, otherwise 
     371     * If value is true, it writes the JSON {@code true} value, otherwise
    348372     * it writes the JSON {@code false} value.
    349373     *
    … …  
    369393     * @throws javax.json.JsonException if an i/o error occurs (IOException
    370394     * would be cause of JsonException)
    371      * @throws JsonGenerationException if this method is not called within an 
     395     * @throws JsonGenerationException if this method is not called within an
    372396     *      object context
    373397     */
    … …  
    376400    /**
    377401     * Writes the end of the current context. If the current context is
    378      * an array context, this method writes the end-of-array character (']'). 
     402     * an array context, this method writes the end-of-array character (']').
    379403     * If the current context is an object context, this method writes the
    380404     * end-of-object character ('}'). After writing the end of the current
    381405     * context, the parent context becomes the new current context.
     406     * If parent context is field context, it is closed.
    382407     *
    383408     * @return this generator
    … …  
    390415    /**
    391416     * Writes the specified value as a JSON value within
    392      * the current array context.
    393      *
    394      * @param value a value to be written in current JSON array
    395      * @return this generator
    396      * @throws javax.json.JsonException if an i/o error occurs (IOException
    397      * would be cause of JsonException)
    398      * @throws JsonGenerationException if this method is not called within an 
    399      *      array context.
     417     * the current array, field or root context.
     418     *
     419     * @param value a value to be written in current JSON array
     420     * @return this generator
     421     * @throws javax.json.JsonException if an i/o error occurs (IOException
     422     * would be cause of JsonException)
     423     * @throws JsonGenerationException if this method is not called within an
     424     *      array or root context.
    400425     */
    401426    JsonGenerator write(JsonValue value);
    … …  
    403428    /**
    404429     * Writes the specified value as a JSON string value within
    405      * the current array context.
    406      *
    407      * @param value a value to be written in current JSON array
    408      * @return this generator
    409      * @throws javax.json.JsonException if an i/o error occurs (IOException
    410      * would be cause of JsonException)
    411      * @throws JsonGenerationException if this method is not called within an 
    412      *      array context
     430     * the current array, field or root context.
     431     *
     432     * @param value a value to be written in current JSON array
     433     * @return this generator
     434     * @throws javax.json.JsonException if an i/o error occurs (IOException
     435     * would be cause of JsonException)
     436     * @throws JsonGenerationException if this method is not called within an
     437     *      array or root context.
    413438     */
    414439    JsonGenerator write(String value);
    … …  
    416441    /**
    417442     * Writes the specified value as a JSON number value within
    418      * the current array context. The specified value's {@code toString()}
     443     * the current array, field or root context. The specified value's {@code toString()}
    419444     * is used as the the text value for writing.
    420445     *
    … …  
    423448     * @throws javax.json.JsonException if an i/o error occurs (IOException
    424449     * would be cause of JsonException)
    425      * @throws JsonGenerationException if this method is not called within an 
    426      *      array context
     450     * @throws JsonGenerationException if this method is not called within an
     451     *      array or root context.
    427452     *
    428453     * @see javax.json.JsonNumber
    … …  
    432457    /**
    433458     * Writes the specified value as a JSON number value within
    434      * the current array context. The string {@code new BigDecimal(value).toString()}
     459     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
    435460     * is used as the text value for writing.
    436461     *
    … …  
    439464     * @throws javax.json.JsonException if an i/o error occurs (IOException
    440465     * would be cause of JsonException)
    441      * @throws JsonGenerationException if this method is not called within an 
    442      *      array context
     466     * @throws JsonGenerationException if this method is not called within an
     467     *      array or root context.
    443468     *
    444469     * @see javax.json.JsonNumber
    … …  
    448473    /**
    449474     * Writes the specified value as a JSON number value within
    450      * the current array context. The string {@code new BigDecimal(value).toString()}
     475     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
    451476     * is used as the text value for writing.
    452477     *
    … …  
    455480     * @throws javax.json.JsonException if an i/o error occurs (IOException
    456481     * would be cause of JsonException)
    457      * @throws JsonGenerationException if this method is not called within an 
    458      *      array context
     482     * @throws JsonGenerationException if this method is not called within an
     483     *      array or root context.
    459484     */
    460485    JsonGenerator write(int value);
    … …  
    462487    /**
    463488     * Writes the specified value as a JSON number value within
    464      * the current array context. The string {@code new BigDecimal(value).toString()}
     489     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
    465490     * is used as the text value for writing.
    466491     *
    … …  
    469494     * @throws javax.json.JsonException if an i/o error occurs (IOException
    470495     * would be cause of JsonException)
    471      * @throws JsonGenerationException if this method is not called within an 
    472      *      array context
     496     * @throws JsonGenerationException if this method is not called within an
     497     *      array or root context.
    473498     */
    474499    JsonGenerator write(long value);
    … …  
    476501    /**
    477502     * Writes the specified value as a JSON number value within the current
    478      * array context. The string {@code BigDecimal.valueOf(value).toString()}
     503     * array, field or root context. The string {@code BigDecimal.valueOf(value).toString()}
    479504     * is used as the text value for writing.
    480505     *
    … …  
    483508     * @throws javax.json.JsonException if an i/o error occurs (IOException
    484509     * would be cause of JsonException)
    485      * @throws JsonGenerationException if this method is not called within an 
    486      *      array context
    487      * @throws NumberFormatException if the value is Not-a-Number(NaN) or infinity.
     510     * @throws JsonGenerationException if this method is not called within an
     511     *      array or root context.
     512     * @throws NumberFormatException if the value is Not-a-Number (NaN) or infinity.
    488513     */
    489514    JsonGenerator write(double value);
    490515
    491516    /**
    492      * Writes a JSON true or false value within the current array context.
    493      * If value is true, this method writes the JSON {@code true} value, 
     517     * Writes a JSON true or false value within the current array, field or root context.
     518     * If value is true, this method writes the JSON {@code true} value,
    494519     * otherwise it writes the JSON {@code false} value.
    495520     *
    … …  
    498523     * @throws javax.json.JsonException if an i/o error occurs (IOException
    499524     * would be cause of JsonException)
    500      * @throws JsonGenerationException if this method is not called within an 
    501      *      array context.
     525     * @throws JsonGenerationException if this method is not called within an
     526     *      array or root context.
    502527     */
    503528    JsonGenerator write(boolean value);
    504529
    505530    /**
    506      * Writes a JSON null value within the current array context.
    507      *
    508      * @return this generator
    509      * @throws javax.json.JsonException if an i/o error occurs (IOException
    510      * would be cause of JsonException)
    511      * @throws JsonGenerationException if this method is not called within an 
    512      *      array context
     531     * Writes a JSON null value within the current array, field or root context.
     532     *
     533     * @return this generator
     534     * @throws javax.json.JsonException if an i/o error occurs (IOException
     535     * would be cause of JsonException)
     536     * @throws JsonGenerationException if this method is not called within an
     537     *      array or root context.
    513538     */
    514539    JsonGenerator writeNull();
    515540
    516541    /**
    517      * Closes this generator and frees any resources associated with it. 
     542     * Closes this generator and frees any resources associated with it.
    518543     * This method closes the underlying output source.
    519544     *
Note: See TracChangeset for help on using the changeset viewer.