Index: trunk/src/javax/json/stream/JsonGenerator.java =================================================================== --- trunk/src/javax/json/stream/JsonGenerator.java (revision 6756) +++ trunk/src/javax/json/stream/JsonGenerator.java (revision 13231) @@ -2,5 +2,5 @@ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * - * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved. + * 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 @@ -9,10 +9,10 @@ * may not use this file except in compliance with the License. You can * obtain a copy of the License at - * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html - * or packager/legal/LICENSE.txt. See the License for the specific + * 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 packager/legal/LICENSE.txt. + * file and include the License file at LICENSE.txt. * * GPL Classpath Exception: @@ -98,7 +98,15 @@ * * + *

+ * Other JSON values (that are not JSON objects or arrays) can be created + * by calling the appropiate {@code write} methods. + *

+ * The following example shows how to generate a JSON string: + * 


+ * JsonGenerator generator = ...;
+ * generator.write("message").close();
+ *
+ * * {@code JsonGenerator} methods can be chained as in the following example: - *

- * * 

  * 
@@ -130,5 +138,4 @@
  *
  * The example code above generates the following JSON (or equivalent):
- * 

  * 
  * 
@@ -150,9 +157,8 @@
  *
  * The generated JSON text must strictly conform to the grammar defined in
- * RFC 4627.
+ * RFC 7159.
  *
  * @see javax.json.Json
  * @see JsonGeneratorFactory
- * @author Jitendra Kotamraju
  */
 public interface JsonGenerator extends Flushable, /*Auto*/Closeable {
@@ -167,5 +173,5 @@
      * 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 or in no context (when a
+     * 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.
@@ -174,5 +180,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is called within an
      *      object context or if it is called more than once in no context.
      */
@@ -188,13 +194,31 @@
      * @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 
+     * @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 or in no context (when a
+     * 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.
@@ -203,5 +227,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is called within an
      *      object context or if called more than once in no context
      */
@@ -217,5 +241,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is not called within
      *      an object context
      */
@@ -232,5 +256,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is not called within an
      *      object context
      */
@@ -248,5 +272,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is not called within an
      *      object context
      */
@@ -266,5 +290,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is not called within an
      *      object context.
      */
@@ -283,5 +307,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is not called within an
      *      object context.
      */
@@ -301,5 +325,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is not called within an
      *      object context.
      */
@@ -319,5 +343,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is not called within an
      *      object context.
      */
@@ -337,5 +361,5 @@
      * @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 NumberFormatException if the value is Not-a-Number (NaN) or infinity.
      * @throws JsonGenerationException if this method is not called within an
      *      object context
@@ -345,5 +369,5 @@
     /**
      * Writes a JSON name/boolean value pair in the current object context.
-     * If value is true, it writes the JSON {@code true} value, otherwise 
+     * If value is true, it writes the JSON {@code true} value, otherwise
      * it writes the JSON {@code false} value.
      *
@@ -369,5 +393,5 @@
      * @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 
+     * @throws JsonGenerationException if this method is not called within an
      *      object context
      */
@@ -376,8 +400,9 @@
     /**
      * Writes the end of the current context. If the current context is
-     * an array context, this method writes the end-of-array character (']'). 
+     * 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
@@ -390,12 +415,12 @@
     /**
      * Writes the specified value as a JSON value within
-     * the current array 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 context.
+     * 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);
@@ -403,12 +428,12 @@
     /**
      * Writes the specified value as a JSON string value within
-     * the current array 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 context
+     * 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);
@@ -416,5 +441,5 @@
     /**
      * Writes the specified value as a JSON number value within
-     * the current array context. The specified value's {@code toString()}
+     * the current array, field or root context. The specified value's {@code toString()}
      * is used as the the text value for writing.
      *
@@ -423,6 +448,6 @@
      * @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 context
+     * @throws JsonGenerationException if this method is not called within an
+     *      array or root context.
      *
      * @see javax.json.JsonNumber
@@ -432,5 +457,5 @@
     /**
      * Writes the specified value as a JSON number value within
-     * the current array context. The string {@code new BigDecimal(value).toString()}
+     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
      * is used as the text value for writing.
      *
@@ -439,6 +464,6 @@
      * @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 context
+     * @throws JsonGenerationException if this method is not called within an
+     *      array or root context.
      *
      * @see javax.json.JsonNumber
@@ -448,5 +473,5 @@
     /**
      * Writes the specified value as a JSON number value within
-     * the current array context. The string {@code new BigDecimal(value).toString()}
+     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
      * is used as the text value for writing.
      *
@@ -455,6 +480,6 @@
      * @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 context
+     * @throws JsonGenerationException if this method is not called within an
+     *      array or root context.
      */
     JsonGenerator write(int value);
@@ -462,5 +487,5 @@
     /**
      * Writes the specified value as a JSON number value within
-     * the current array context. The string {@code new BigDecimal(value).toString()}
+     * the current array, field or root context. The string {@code new BigDecimal(value).toString()}
      * is used as the text value for writing.
      *
@@ -469,6 +494,6 @@
      * @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 context
+     * @throws JsonGenerationException if this method is not called within an
+     *      array or root context.
      */
     JsonGenerator write(long value);
@@ -476,5 +501,5 @@
     /**
      * Writes the specified value as a JSON number value within the current
-     * array context. The string {@code BigDecimal.valueOf(value).toString()}
+     * array, field or root context. The string {@code BigDecimal.valueOf(value).toString()}
      * is used as the text value for writing.
      *
@@ -483,13 +508,13 @@
      * @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 context
-     * @throws NumberFormatException if the value is Not-a-Number(NaN) or infinity.
+     * @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 context.
-     * If value is true, this method writes the JSON {@code true} 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.
      *
@@ -498,22 +523,22 @@
      * @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 context.
+     * @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 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 context
+     * 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. 
+     * Closes this generator and frees any resources associated with it.
      * This method closes the underlying output source.
      *