Index: trunk/src/javax/json/stream/JsonCollectors.java =================================================================== --- trunk/src/javax/json/stream/JsonCollectors.java (revision 13231) +++ trunk/src/javax/json/stream/JsonCollectors.java (revision 13231) @@ -0,0 +1,184 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2015-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 java.util.Map; +import java.util.HashMap; +import java.util.stream.Collector; +import java.util.function.BinaryOperator; +import java.util.function.Function; +import java.util.function.BiConsumer; + +import javax.json.Json; +import javax.json.JsonArray; +import javax.json.JsonArrayBuilder; +import javax.json.JsonObject; +import javax.json.JsonObjectBuilder; +import javax.json.JsonValue; +import javax.json.JsonException; + +/** + * This class contains some implementations of {@code java.util.stream.Collector} for accumulating + * {@link JsonValue}s into {@link JsonArray} and {@link JsonObject}. + * + * @since 1.1 + */ + +public final class JsonCollectors { + + private JsonCollectors() { + } + + /** + * Constructs a {@code java.util.stream.Collector} that accumulates the input {@code JsonValue} + * elements into a {@code JsonArray}. + * + * @return the constructed Collector + */ + public static Collector toJsonArray() { + return Collector.of( + Json::createArrayBuilder, + JsonArrayBuilder::add, + JsonArrayBuilder::addAll, + JsonArrayBuilder::build); + } + + /** + * Constructs a {@code java.util.stream.Collector} that accumulates the input {@code Map.Entry} + * elements into a {@code JsonObject}. + * + * @return the constructed Collector + */ + public static Collector, JsonObjectBuilder, JsonObject> toJsonObject() { + return Collector.of( + Json::createObjectBuilder, + (JsonObjectBuilder b, Map.Entry v) -> b.add(v.getKey(), v.getValue()), + JsonObjectBuilder::addAll, + JsonObjectBuilder::build); + } + + /** + * Constructs a {@code java.util.stream.Collector} that accumulates the input {@code JsonValue} + * elements into a {@code JsonObject}. The name/value pairs of the {@code JsonObject} are computed + * by applying the provided mapping functions. + * + * @param keyMapper a mapping function to produce names. + * @param valueMapper a mapping function to produce values + * @return the constructed Collector + */ + public static Collector + toJsonObject(Function keyMapper, + Function valueMapper) { + return Collector.of( + Json::createObjectBuilder, + (b, v) -> b.add(keyMapper.apply(v), valueMapper.apply(v)), + JsonObjectBuilder::addAll, + JsonObjectBuilder::build, + Collector.Characteristics.UNORDERED); + } + + /** + * Constructs a {@code java.util.stream.Collector} that implements a "group by" operation on the + * input {@code JsonValue} elements. A classifier function maps the input {@code JsonValue}s to keys, and + * the {@code JsonValue}s are partitioned into groups according to the value of the key. + * A reduction operation is performed on the {@code JsonValue}s in each group, using the + * downstream {@code Collector}. For each group, the key and the results of the reduction operation + * become the name/value pairs of the resultant {@code JsonObject}. + * + * @param the intermediate accumulation {@code JsonArrayBuilder} of the downstream collector + * @param classifier a function mapping the input {@code JsonValue}s to a String, producing keys + * @param downstream a {@code Collector} that implements a reduction operation on the + * {@code JsonValue}s in each group. + * @return the constructed {@code Collector} + */ + public static Collector, JsonObject> + groupingBy(Function classifier, + Collector downstream) { + + BiConsumer, JsonValue> accumulator = + (map, value) -> { + String key = classifier.apply(value); + if (key == null) { + throw new JsonException("element cannot be mapped to a null key"); + } + // Build a map of key to JsonArrayBuilder + T arrayBuilder = + map.computeIfAbsent(key, v->downstream.supplier().get()); + // Add elements from downstream Collector to the arrayBuilder. + downstream.accumulator().accept(arrayBuilder, value); + }; + Function, JsonObject> finisher = + map -> { + // transform the map of name: JsonArrayBuilder to + // name: JsonArray + // using the downstream collector for reducing the JsonArray + JsonObjectBuilder objectBuilder = Json.createObjectBuilder(); + map.forEach((k, v) -> { + JsonArray array = downstream.finisher().apply(v); + objectBuilder.add(k, array); + }); + return objectBuilder.build(); + }; + BinaryOperator> combiner = + (map1, map2) -> { + map1.putAll(map2); + return map1; + }; + return Collector.of(HashMap::new, accumulator, combiner, finisher, + Collector.Characteristics.UNORDERED); + } + + /** + * Constructs a {@code java.util.stream.Collector} that implements a "group by" operation on the + * input {@code JsonValue} elements. A classifier function maps the input {@code JsonValue}s to keys, and + * the {@code JsonValue}s are partitioned into groups according to the value of the key. + * The {@code JsonValue}s in each group are added to a {@code JsonArray}. The key and the + * {@code JsonArray} in each group becomes the name/value pair of the resultant {@code JsonObject}. + * + * @param classifier a function mapping the input {@code JsonValue}s to a String, producing keys + * @return the constructed {@code Collector} + */ + public static Collector, JsonObject> + groupingBy(Function classifier) { + return groupingBy(classifier, toJsonArray()); + } +} + Index: trunk/src/javax/json/stream/JsonGenerationException.java =================================================================== --- trunk/src/javax/json/stream/JsonGenerationException.java (revision 6756) +++ trunk/src/javax/json/stream/JsonGenerationException.java (revision 13231) @@ -2,5 +2,5 @@ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * - * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012-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: @@ -46,6 +46,4 @@ * {@code JsonGenerationException} indicates an incorrect JSON is * being generated. - * - * @author Jitendra Kotamraju */ public class JsonGenerationException extends JsonException { 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.
      *
Index: trunk/src/javax/json/stream/JsonGeneratorFactory.java
===================================================================
--- trunk/src/javax/json/stream/JsonGeneratorFactory.java	(revision 6756)
+++ trunk/src/javax/json/stream/JsonGeneratorFactory.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:
@@ -67,6 +67,4 @@
  * 
 All the methods in this class are safe for use by multiple concurrent
  * threads.
- *
- * @author Jitendra Kotamraju
  */
 public interface JsonGeneratorFactory {
@@ -77,4 +75,5 @@
      *
      * @param writer i/o writer to which JSON is written
+     * @return the created JSON generator
      */
     JsonGenerator createGenerator(Writer writer);
@@ -86,4 +85,5 @@
      *
      * @param out i/o stream to which JSON is written
+     * @return the created JSON generator
      */
     JsonGenerator createGenerator(OutputStream out);
@@ -96,4 +96,5 @@
      * @param out i/o stream to which JSON is written
      * @param charset a charset
+     * @return the created JSON generator
      */
     JsonGenerator createGenerator(OutputStream out, Charset charset);
Index: trunk/src/javax/json/stream/JsonLocation.java
===================================================================
--- trunk/src/javax/json/stream/JsonLocation.java	(revision 6756)
+++ trunk/src/javax/json/stream/JsonLocation.java	(revision 13231)
@@ -2,5 +2,5 @@
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013-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:
@@ -52,6 +52,4 @@
  * {@link javax.json.JsonArray JsonArray} input source, all the methods in
  * this class return -1.
- *
- * @author Jitendra Kotamraju
  * @see JsonParser
  * @see JsonParsingException
@@ -60,14 +58,14 @@
 
     /**
-     * Return the line number for the current JSON event in the input source.
+     * Return the line number (starts with 1 for the first line) for the current JSON event in the input source.
      *
-     * @return the line number or -1 if none is available
+     * @return the line number (starts with 1 for the first line) or -1 if none is available
      */
     long getLineNumber();
 
     /**
-     * Return the column number for the current JSON event in the input source.
+     * Return the column number (starts with 1 for the first column) for the current JSON event in the input source.
      *
-     * @return the column number or -1 if none is available
+     * @return the column number (starts with 1 for the first column) or -1 if none is available
      */
     long getColumnNumber();
Index: trunk/src/javax/json/stream/JsonParser.java
===================================================================
--- trunk/src/javax/json/stream/JsonParser.java	(revision 6756)
+++ trunk/src/javax/json/stream/JsonParser.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:
@@ -44,8 +44,16 @@
 import java.io.Closeable;
 import java.math.BigDecimal;
+import java.util.stream.Stream;
+import java.util.Map;
+
+import javax.json.JsonValue;
+import javax.json.JsonObject;
+import javax.json.JsonArray;
 
 /**
  * Provides forward, read-only access to JSON data in a streaming way. This
- * is the most efficient way for reading JSON data. The class
+ * is the most efficient way for reading JSON data.
+ * This is the only way to parse and process JSON data that are too big to be loaded in memory.
+ * 
The class
  * {@link javax.json.Json} contains methods to create parsers from input
  * sources ({@link java.io.InputStream} and {@link java.io.Reader}).
@@ -97,6 +105,4 @@
  *
  * 

- * 
- * 

  * For example, for the following JSON:
  * 
@@ -113,5 +119,4 @@
  * locations below (marked in bold):
  *
- * 

  * 
  * {START_OBJECT
@@ -124,11 +129,9 @@
  * 

  *
- * 

- * The methods {@code next()} and {@code hasNext()} enable iteration over
+ * The methods {@link #next()} and {@link #hasNext()} enable iteration over
  * parser events to process JSON data. {@code JsonParser} provides get methods
  * to obtain the value at the current state of the parser. For example, the
  * following code shows how to obtain the value "John" from the JSON above:
  *
- * 

  * 
  * 
@@ -140,7 +143,54 @@
  * 

  *
+ * Starting in version 1.1, it is possible to build a partial JSON object
+ * model from the stream, at the current parser position.
+ * The methods {@link #getArray} and {@link #getObject} can be used to read in
+ * a {@code JsonArray} or {@code JsonObject}.  For example, the following code
+ * shows how to obtain the phoneNumber in a JsonArray, from the JSON above:
+ *
+ * 

+ * while (parser.hasNext() {
+ *     Event event = parser.next();
+ *     if (event == JsonParser.Event.KEY_NAME ) {
+ *         String key = getString();
+ *         event = parser.next();
+ *         if (key.equals("phoneNumber") {
+ *             JsonArray phones = parser.getArray();
+ *         }
+ *     }
+ * }
+ * 

+ *
+ * The methods {@link #getArrayStream} and {@link #getObjectStream} can be used
+ * to get a stream of the elements of a {@code JsonArray} or {@code JsonObject}.
+ * For example, the following code shows another way to obtain John's phoneNumber
+ * in a {@code JsonArray} :
+ *
+ * 
{@code
+ * Event event = parser.next(); // START_OBJECT
+ * JsonArray phones = (JsonArray)
+ *     parser.getObjectStream().filter(e->e.getKey().equals("phoneNumber"))
+ *                             .map(e->e.getValue())
+ *                             .findFirst()
+ *                             .get();
+ * }

+ *
+ * The methods {@link #skipArray} and {@link #skipObject} can be used to
+ * skip tokens and position the parser to {@code END_ARRAY} or
+ * {@code END_OBJECT}.
+ * 

+ * {@code JsonParser} can be used to parse sequence of JSON values that are not
+ * enclosed in a JSON array, e.g. { } { }. The following code demonstrates how
+ * to parse such sequence.
+ * 

+ * JsonParser parser = Json.createParser(...);
+ * while (parser.hasNext) {
+ *     parser.next(); // advance parser state
+ *     JsonValue value = parser.getValue();
+ * }
+ * 

+ *
  * @see javax.json.Json
  * @see JsonParserFactory
- * @author Jitendra Kotamraju
  */
 public interface JsonParser extends /*Auto*/Closeable {
@@ -223,4 +273,5 @@
      * @throws java.util.NoSuchElementException if there are no more parsing
      * states.
+     * @return the event for the next parsing state
      */
     Event next();
@@ -319,19 +370,133 @@
 
     /**
-     * getJsonValue(JsonObject.class) is valid in the START_OBJECT state and
-     * moves the cursor to END_OBJECT.
-     *
-     * getJsonValue(JsonArray.class) is valid in the START_ARRAY state
-     * and moves the cursor to END_ARRAY.
-     *
-     * getJsonValue(JsonString.class) is valid in the VALUE_STRING state.
-     *
-     * getJsonValue(JsonNumber.class) is valid in the VALUE_NUMBER state.
-     *
-     * @param clazz
-     * @return
-     *
-    public  T getJsonValue(Class clazz);
-     */
+     * Returns a {@code JsonObject} and advances the parser to the
+     * corresponding {@code END_OBJECT}.
+     *
+     * @return the {@code JsonObject} at the current parser position
+     *
+     * @throws IllegalStateException when the parser state is not
+     *     {@code START_OBJECT}
+     *
+     * @since 1.1
+     */
+    default public JsonObject getObject() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Returns a {@code JsonValue} at the current parser position.
+     * If the parser state is {@code START_ARRAY}, the behavior is
+     * the same as {@link #getArray}. If the parser state is
+     * {@code START_OBJECT}, the behavior is the same as
+     * {@link #getObject}. For all other cases, if applicable, the JSON value is
+     * read and returned.
+     *
+     * @return the {@code JsonValue} at the current parser position.
+     * @throws IllegalStateException when the parser state is
+     *     {@code END_OBJECT} or {@code END_ARRAY}
+     *
+     * @since 1.1
+     */
+    default public JsonValue getValue() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Returns a {@code JsonArray} and advance the parser to the
+     * the corresponding {@code END_ARRAY}.
+     *
+     * @return the {@code JsonArray} at the current parser position
+     *
+     * @throws IllegalStateException when the parser state is not
+     *     {@code START_ARRAY}
+     *
+     * @since 1.1
+     */
+    default public JsonArray getArray() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Returns a stream of the {@code JsonArray} elements.
+     * The parser state must be {@code START_ARRAY}.
+     * The elements are read lazily, on an as-needed basis, as
+     * required by the stream operations.
+     * If the stream operations do not consume
+     * all of the array elements, {@link skipArray} can be used to
+     * skip the unprocessed array elements.
+     *
+     * @return a stream of elements of the {@code JsonArray}
+     *
+     * @throws IllegalStateException when the parser state is not
+     *     {@code START_ARRAY}
+     *
+     * @since 1.1
+     */
+    default public Stream getArrayStream() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Returns a stream of the {@code JsonObject}'s
+     * name/value pairs. The parser state must be {@code START_OBJECT}.
+     * The name/value pairs are read lazily, on an as-needed basis, as
+     * required by the stream operations.
+     * If the stream operations do not consume
+     * all of the object's name/value pairs, {@link skipObject} can be
+     * used to skip the unprocessed elements.
+     *
+     * @return a stream of name/value pairs of the {@code JsonObject}
+     *
+     * @throws IllegalStateException when the parser state is not
+     *     {@code START_OBJECT}
+     *
+     * @since 1.1
+     */
+    default public Stream> getObjectStream() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Returns a stream of {@code JsonValue} from a sequence of
+     * JSON values. The values are read lazily, on an as-needed basis,
+     * as needed by the stream operations.
+     *
+     * @return a Stream of {@code JsonValue}
+     *
+     * @throws IllegalStateException if the parser is in an array or object.
+     *
+     * @since 1.1
+     */
+    default public Stream getValueStream() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Advance the parser to {@code END_ARRAY}.
+     * If the parser is in array context, i.e. it has previously
+     * encountered a {@code START_ARRAY} without encountering the
+     * corresponding {@code END_ARRAY}, the parser is advanced to
+     * the corresponding {@code END_ARRAY}.
+     * If the parser is not in any array context, nothing happens.
+     *
+     * @since 1.1
+     */
+    default public void skipArray() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Advance the parser to {@code END_OBJECT}.
+     * If the parser is in object context, i.e. it has previously
+     * encountered a {@code START_OBJECT} without encountering the
+     * corresponding {@code END_OBJECT}, the parser is advanced to
+     * the corresponding {@code END_OBJECT}.
+     * If the parser is not in any object context, nothing happens.
+     *
+     * @since 1.1
+     */
+    default public void skipObject() {
+        throw new UnsupportedOperationException();
+    }
 
     /**
@@ -344,4 +509,3 @@
     @Override
     void close();
-
 }
Index: trunk/src/javax/json/stream/JsonParserFactory.java
===================================================================
--- trunk/src/javax/json/stream/JsonParserFactory.java	(revision 6756)
+++ trunk/src/javax/json/stream/JsonParserFactory.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:
@@ -69,6 +69,4 @@
  * 
 All the methods in this class are safe for use by multiple concurrent
  * threads.
- *
- * @author Jitendra Kotamraju
  */
 public interface JsonParserFactory {
@@ -78,4 +76,5 @@
      *
      * @param reader a i/o reader from which JSON is to be read
+     * @return the created JSON parser
      */
     JsonParser createParser(Reader reader);
@@ -84,7 +83,8 @@
      * Creates a JSON parser from the specified byte stream.
      * The character encoding of the stream is determined
-     * as specified in RFC 4627.
+     * as specified in RFC 7159.
      *
      * @param in i/o stream from which JSON is to be read
+     * @return the created JSON parser
      * @throws javax.json.JsonException if encoding cannot be determined
      *         or i/o error (IOException would be cause of JsonException)
@@ -99,4 +99,5 @@
      * @param in i/o stream from which JSON is to be read
      * @param charset a charset
+     * @return the created JSON parser
      */
     JsonParser createParser(InputStream in, Charset charset);
@@ -106,4 +107,5 @@
      *
      * @param obj a JSON object
+     * @return the created JSON parser
      */
     JsonParser createParser(JsonObject obj);
@@ -113,4 +115,5 @@
      *
      * @param array a JSON array
+     * @return the created JSON parser
      */
     JsonParser createParser(JsonArray array);
Index: trunk/src/javax/json/stream/JsonParsingException.java
===================================================================
--- trunk/src/javax/json/stream/JsonParsingException.java	(revision 6756)
+++ trunk/src/javax/json/stream/JsonParsingException.java	(revision 13231)
@@ -2,5 +2,5 @@
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012-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:
@@ -46,6 +46,4 @@
  * {@code JsonParsingException} is used when an incorrect JSON is
  * being parsed.
- *
- * @author Jitendra Kotamraju
  */
 public class JsonParsingException extends JsonException {
Index: trunk/src/javax/json/stream/package-info.java
===================================================================
--- trunk/src/javax/json/stream/package-info.java	(revision 6756)
+++ trunk/src/javax/json/stream/package-info.java	(revision 13231)
@@ -2,5 +2,5 @@
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012-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:
@@ -68,5 +68,4 @@
  *
  * @since JSON Processing 1.0
- * @author Jitendra Kotamraju
  */
 package javax.json.stream;