Index: trunk/src/javax/json/EmptyArray.java =================================================================== --- trunk/src/javax/json/EmptyArray.java (revision 13231) +++ trunk/src/javax/json/EmptyArray.java (revision 13231) @@ -0,0 +1,136 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 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; + +import java.io.Serializable; +import java.util.AbstractList; +import java.util.Collections; +import java.util.List; +import java.util.RandomAccess; + +/** + * Private implementation of immutable {@link JsonArray}. + * + * @author Lukas Jungmann + */ +final class EmptyArray extends AbstractList implements JsonArray, Serializable, RandomAccess { + + private static final long serialVersionUID = 7295439472061642859L; + + @Override + public JsonValue get(int index) { + throw new IndexOutOfBoundsException("Index: " + index); + } + + @Override + public int size() { + return 0; + } + + @Override + public JsonObject getJsonObject(int index) { + return (JsonObject) get(index); + } + + @Override + public JsonArray getJsonArray(int index) { + return (JsonArray) get(index); + } + + @Override + public JsonNumber getJsonNumber(int index) { + return (JsonNumber) get(index); + } + + @Override + public JsonString getJsonString(int index) { + return (JsonString) get(index); + } + + @Override + public List getValuesAs(Class clazz) { + return Collections.emptyList(); + } + + @Override + public String getString(int index) { + return getJsonString(index).getString(); + } + + @Override + public String getString(int index, String defaultValue) { + return defaultValue; + } + + @Override + public int getInt(int index) { + return getJsonNumber(index).intValue(); + } + + @Override + public int getInt(int index, int defaultValue) { + return defaultValue; + } + + @Override + public boolean getBoolean(int index) { + return get(index) == JsonValue.TRUE; + } + + @Override + public boolean getBoolean(int index, boolean defaultValue) { + return defaultValue; + } + + @Override + public boolean isNull(int index) { + return get(index) == JsonValue.NULL; + } + + @Override + public ValueType getValueType() { + return ValueType.ARRAY; + } + + // Preserves singleton property + private Object readResolve() { + return JsonValue.EMPTY_JSON_ARRAY; + } +} Index: trunk/src/javax/json/EmptyObject.java =================================================================== --- trunk/src/javax/json/EmptyObject.java (revision 13231) +++ trunk/src/javax/json/EmptyObject.java (revision 13231) @@ -0,0 +1,126 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 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; + +import java.io.Serializable; +import java.util.AbstractMap; +import java.util.Collections; +import java.util.Set; + +/** + * Private implementation of immutable {@link JsonObject}. + * + * @author Lukas Jungmann + */ +final class EmptyObject extends AbstractMap implements JsonObject, Serializable { + + private static final long serialVersionUID = -1461653546889072583L; + + @Override + public Set> entrySet() { + return Collections.>emptySet(); + } + + @Override + public JsonArray getJsonArray(String name) { + return (JsonArray) get(name); + } + + @Override + public JsonObject getJsonObject(String name) { + return (JsonObject) get(name); + } + + @Override + public JsonNumber getJsonNumber(String name) { + return (JsonNumber) get(name); + } + + @Override + public JsonString getJsonString(String name) { + return (JsonString) get(name); + } + + @Override + public String getString(String name) { + return getJsonString(name).getString(); + } + + @Override + public String getString(String name, String defaultValue) { + return defaultValue; + } + + @Override + public int getInt(String name) { + return getJsonNumber(name).intValue(); + } + + @Override + public int getInt(String name, int defaultValue) { + return defaultValue; + } + + @Override + public boolean getBoolean(String name) { + throw new NullPointerException(); + } + + @Override + public boolean getBoolean(String name, boolean defaultValue) { + return defaultValue; + } + + @Override + public boolean isNull(String name) { + throw new NullPointerException(); + } + + @Override + public ValueType getValueType() { + return ValueType.OBJECT; + } + + // Preserves singleton property + private Object readResolve() { + return JsonValue.EMPTY_JSON_OBJECT; + } +} Index: trunk/src/javax/json/Json.java =================================================================== --- trunk/src/javax/json/Json.java (revision 6756) +++ trunk/src/javax/json/Json.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: @@ -41,4 +41,13 @@ package javax.json; +import java.io.InputStream; +import java.io.OutputStream; +import java.io.Reader; +import java.io.Writer; +import java.math.BigDecimal; +import java.math.BigInteger; +import java.util.Collection; +import java.util.Map; +import java.util.Optional; import javax.json.spi.JsonProvider; import javax.json.stream.JsonGenerator; @@ -46,6 +55,4 @@ import javax.json.stream.JsonParser; import javax.json.stream.JsonParserFactory; -import java.io.*; -import java.util.Map; /** @@ -73,8 +80,6 @@ * All the methods in this class are safe for use by multiple concurrent * threads. - * - * @author Jitendra Kotamraju */ -public class Json { +public final class Json { private Json() { @@ -93,6 +98,6 @@ /** * Creates a JSON parser from a byte stream. - * The character encoding of the stream is determined as specified in - * RFC 4627. + * The character encoding of the stream is determined as specified in + * RFC 7159. * * @param in i/o stream from which JSON is to be read @@ -212,5 +217,5 @@ * Creates a JSON reader from a byte stream. The character encoding of * the stream is determined as described in - * RFC 4627. + * RFC 7159. * * @param in a byte stream from which JSON is to be read @@ -259,4 +264,32 @@ /** + * Creates a JSON array builder, initialized with the specified array + * + * @param array the initial array in the builder + * @return a JSON array builder + * + * @since 1.1 + */ + public static JsonArrayBuilder createArrayBuilder(JsonArray array) { + return JsonProvider.provider().createArrayBuilder(array); + } + + /** + * Creates a JSON array builder, initialized with the content of specified {@code collection}. + * If the @{code collection} contains {@link Optional}s then resulting JSON array builder + * contains the value from the {@code collection} only if the {@link Optional} is not empty. + * + * @param collection the initial data for the builder + * @return a JSON array builder + * @exception IllegalArgumentException if the value from the {@code collection} cannot be converted + * to the corresponding {@link JsonValue} + * + * @since 1.1 + */ + public static JsonArrayBuilder createArrayBuilder(Collection collection) { + return JsonProvider.provider().createArrayBuilder(collection); + } + + /** * Creates a JSON object builder * @@ -265,4 +298,132 @@ public static JsonObjectBuilder createObjectBuilder() { return JsonProvider.provider().createObjectBuilder(); + } + + /** + * Creates a JSON object builder, initialized with the specified object. + * + * @param object the initial object in the builder + * @return a JSON object builder + * + * @since 1.1 + */ + public static JsonObjectBuilder createObjectBuilder(JsonObject object) { + return JsonProvider.provider().createObjectBuilder(object); + } + + /** + * Creates a JSON object builder, initialized with the data from specified {@code map}. + * If the @{code map} contains {@link Optional}s then resulting JSON object builder + * contains the key from the {@code map} only if the {@link Optional} is not empty. + * + * @param map the initial object in the builder + * @return a JSON object builder + * @exception IllegalArgumentException if the value from the {@code map} cannot be converted + * to the corresponding {@link JsonValue} + * + * @since 1.1 + */ + public static JsonObjectBuilder createObjectBuilder(Map map) { + return JsonProvider.provider().createObjectBuilder(map); + } + + /** + * Creates JSON Pointer (RFC 6901) + * from given {@code jsonPointer} string. + *
    + *
  • An empty {@code jsonPointer} string defines a reference to the target itself.
    • + *
  • If the {@code jsonPointer} string is non-empty, it must be a sequence of '{@code /}' prefixed tokens.
    • + *
+ * + * @param jsonPointer the valid escaped JSON Pointer string + * @throws NullPointerException if {@code jsonPointer} is {@code null} + * @throws JsonException if {@code jsonPointer} is not a valid JSON Pointer + * @return a JSON Pointer + * + * @since 1.1 + */ + public static JsonPointer createPointer(String jsonPointer) { + return JsonProvider.provider().createPointer(jsonPointer); + } + + /** + * Creates a JSON Patch builder (RFC 6902). + * + * @return a JSON Patch builder + * + * @since 1.1 + */ + public static JsonPatchBuilder createPatchBuilder() { + return JsonProvider.provider().createPatchBuilder(); + } + + /** + * Creates a JSON Patch builder + * (RFC 6902), + * initialized with the specified operations. + * + * @param array the initial patch operations + * @return a JSON Patch builder + * + * @since 1.1 + */ + public static JsonPatchBuilder createPatchBuilder(JsonArray array) { + return JsonProvider.provider().createPatchBuilder(array); + } + + /** + * Creates a JSON Patch (RFC 6902) + * from the specified operations. + * + * @param array patch operations + * @return a JSON Patch + * + * @since 1.1 + */ + public static JsonPatch createPatch(JsonArray array) { + return JsonProvider.provider().createPatch(array); + } + + /** + * Generates a JSON Patch (RFC 6902) + * from the source and target {@code JsonStructure}. + * The generated JSON Patch need not be unique. + * + * @param source the source + * @param target the target, must be the same type as the source + * @return a JSON Patch which when applied to the source, yields the target + * + * @since 1.1 + */ + public static JsonPatch createDiff(JsonStructure source, JsonStructure target) { + return JsonProvider.provider().createDiff(source, target); + } + + /** + * Creates JSON Merge Patch (RFC 7396) + * from specified {@code JsonValue}. + * + * @param patch the patch + * @return a JSON Merge Patch + * + * @since 1.1 + */ + public static JsonMergePatch createMergePatch(JsonValue patch) { + return JsonProvider.provider().createMergePatch(patch); + } + + /** + * Generates a JSON Merge Patch (RFC 7396) + * from the source and target {@code JsonValue}s + * which when applied to the {@code source}, yields the {@code target}. + * + * @param source the source + * @param target the target + * @return a JSON Merge Patch + * + * @since 1.1 + */ + public static JsonMergePatch createMergeDiff(JsonValue source, JsonValue target) { + return JsonProvider.provider().createMergeDiff(source, target); } @@ -283,3 +444,101 @@ } + /** + * Creates a JsonString. + * + * @param value a JSON string + * @return the JsonString for the string + * + * @since 1.1 + */ + public static JsonString createValue(String value) { + return JsonProvider.provider().createValue(value); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public static JsonNumber createValue(int value) { + return JsonProvider.provider().createValue(value); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public static JsonNumber createValue(long value) { + return JsonProvider.provider().createValue(value); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public static JsonNumber createValue(double value) { + return JsonProvider.provider().createValue(value); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public static JsonNumber createValue(BigDecimal value) { + return JsonProvider.provider().createValue(value); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public static JsonNumber createValue(BigInteger value) { + return JsonProvider.provider().createValue(value); + } + + /** + * Encodes (escapes) a passed string as defined by RFC 6901. + * This method doesn't validate the passed JSON-pointer string. + * + * @param pointer the JSON-pointer string to encode + * @return encoded JSON-pointer string + * + * @since 1.1 + */ + public static String encodePointer(String pointer) { + return pointer.replace("~", "~0").replace("/", "~1"); + } + + /** + * Decodes a passed JSON-pointer string as defined by RFC 6901. + * This method doesn't validate the passed JSON-pointer string. + * + * @param escaped the JSON-pointer string to decode + * @return decoded JSON-pointer string + * + * @since 1.1 + */ + public static String decodePointer(String escaped) { + return escaped.replace("~1", "/").replace("~0", "~"); + } + } Index: trunk/src/javax/json/JsonArray.java =================================================================== --- trunk/src/javax/json/JsonArray.java (revision 6756) +++ trunk/src/javax/json/JsonArray.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: @@ -42,4 +42,7 @@ import java.util.List; +import java.util.function.Function; +import java.util.stream.Collectors; +import java.util.stream.Stream; /** @@ -111,6 +114,4 @@ * whether directly or using its collection views, results in an * {@code UnsupportedOperationException}. - * - * @author Jitendra Kotamraju */ public interface JsonArray extends JsonStructure, List { @@ -165,5 +166,5 @@ /** - * Returns a list a view of the specified type for the array. This method + * Returns a list view of the specified type for the array. This method * does not verify if there is a value of wrong type in the array. Providing * this typesafe view dynamically may cause a program fail with a @@ -172,8 +173,35 @@ * method returns. * + * @param The type of the List for the array * @param clazz a JsonValue type - * @return a list view of the specified type + * @return a list view of the specified type */ List getValuesAs(Class clazz); + + /** + * Returns a list view for the array. The value and the type of the elements + * in the list is specified by the {@code func} argument. + *

This method can be used to obtain a list of the unwrapped types, such as + * 

{@code
+     *     List strings = ary1.getValuesAs(JsonString::getString);
+     *     List ints = ary2.getValuesAs(JsonNumber::intValue);
+     * }
+ * or a list of simple projections, such as + * 
 {@code
+     *     List stringsizes = ary1.getValueAs((JsonString v)->v.getString().length();
+     * }
+ * @param The element type (must be a subtype of JsonValue) of this JsonArray. + * @param The element type of the returned List + * @param func The function that maps the elements of this JsonArray to the target elements. + * @return A List of the specified values and type. + * @throws ClassCastException if the {@code JsonArray} contains a value of wrong type + * + * @since 1.1 + */ + default List getValuesAs(Function func) { + @SuppressWarnings("unchecked") + Stream stream = (Stream) stream(); + return stream.map(func).collect(Collectors.toList()); + } /** @@ -195,5 +223,7 @@ * the specified default value is returned. * - * @param index index of the JsonString value + * @param index index of the {@code JsonString} value + * @param defaultValue the String to return if the {@code JsonValue} at the + * specified position is not a {@code JsonString} * @return the String value at the specified position in this array, * or the specified default value @@ -220,4 +250,6 @@ * * @param index index of the {@code JsonNumber} value + * @param defaultValue the int value to return if the {@code JsonValue} at + * the specified position is not a {@code JsonNumber} * @return the int value at the specified position in this array, * or the specified default value @@ -247,4 +279,6 @@ * * @param index index of the JSON boolean value + * @param defaultValue the boolean value to return if the {@code JsonValue} + * at the specified position is neither TRUE nor FALSE * @return the boolean value at the specified position, * or the specified default value @@ -258,8 +292,7 @@ * @param index index of the JSON null value * @return return true if the value at the specified location is - * {@code JsonValue.NUL}, otherwise false + * {@code JsonValue.NULL}, otherwise false * @throws IndexOutOfBoundsException if the index is out of range */ boolean isNull(int index); - } Index: trunk/src/javax/json/JsonArrayBuilder.java =================================================================== --- trunk/src/javax/json/JsonArrayBuilder.java (revision 6756) +++ trunk/src/javax/json/JsonArrayBuilder.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: @@ -45,8 +45,11 @@ /** - * A builder for creating {@link JsonArray} models from scratch. This - * interface initializes an empty JSON array model and provides methods to add - * values to the array model and to return the resulting array. The methods - * in this class can be chained to add multiple values to the array. + * A builder for creating {@link JsonArray} models from scratch, and for + * modifying a existing {@code JsonArray}. + *

A {@code JsonArrayBuilder} can start with an empty or a non-empty + * JSON array model. This interface provides methods to add, insert, remove + * and replace values in the JSON array model.

+ *

Methods in this class can be chained to perform multiple values to + * the array.

* *

The class {@link javax.json.Json} contains methods to create the builder @@ -64,5 +67,4 @@ * way to create multiple instances. * - * * The example code below shows how to build a {@code JsonArray} object * that represents the following JSON array: @@ -165,5 +167,5 @@ * @param value the number value * @return this array builder - * @throws NumberFormatException if the value is Not-a-Number(NaN) or + * @throws NumberFormatException if the value is Not-a-Number (NaN) or * infinity * @@ -207,4 +209,432 @@ /** + * Adds all elements of the array in the specified array builder to the array. + * + * @param builder the array builder + * @return this array builder + * @throws NullPointerException if the specified builder is null + * + @since 1.1 + */ + default JsonArrayBuilder addAll(JsonArrayBuilder builder) { + throw new UnsupportedOperationException(); + } + + /** + * Inserts a value to the array at the specified position. Shifts the value + * currently at that position (if any) and any subsequent values to the right + * (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param value the JSON value + * @return this array builder + * @throws NullPointerException if the specified value is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, JsonValue value) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a value to the array as a {@link JsonString} at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param value the string value + * @return this array builder + * @throws NullPointerException if the specified value is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, String value) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a value to the array as a {@link JsonNumber} at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws NullPointerException if the specified value is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, BigDecimal value) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a value to the array as a {@link JsonNumber} at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws NullPointerException if the specified value is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, BigInteger value) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a value to the array as a {@link JsonNumber} at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, int value) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a value to the array as a {@link JsonNumber} at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, long value) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a value to the array as a {@link JsonNumber} at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws NumberFormatException if the value is Not-a-Number (NaN) or + * infinity + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, double value) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value to the + * array at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param value the boolean value + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, boolean value) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a {@link JsonValue#NULL} value to the array at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder addNull(int index) { + return add(index, JsonValue.NULL); + } + + /** + * Adds a {@link JsonObject} from an object builder to the array at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param builder the object builder + * @return this array builder + * @throws NullPointerException if the specified builder is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, JsonObjectBuilder builder) { + throw new UnsupportedOperationException(); + } + + /** + * Adds a {@link JsonArray} from an array builder to the array at the specified position. + * Shifts the value currently at that position (if any) and any subsequent values + * to the right (adds one to their indices). Index starts with 0. + * + * @param index the position in the array + * @param builder the array builder + * @return this array builder + * @throws NullPointerException if the specified builder is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index > array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder add(int index, JsonArrayBuilder builder) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with the specified value at the + * specified position. + * + * @param index the position in the array + * @param value the JSON value + * @return this array builder + * @throws NullPointerException if the specified value is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, JsonValue value) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with the specified value as a + * {@link JsonString} at the specified position. + * + * @param index the position in the array + * @param value the string value + * @return this array builder + * @throws NullPointerException if the specified value is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, String value) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with the specified value as a + * {@link JsonNumber} at the specified position. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws NullPointerException if the specified value is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, BigDecimal value) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with the specified value as a + * {@link JsonNumber} at the specified position. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws NullPointerException if the specified value is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, BigInteger value) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with the specified value as a + * {@link JsonNumber} at the specified position. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, int value) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with the specified value as a + * {@link JsonNumber} at the specified position. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, long value) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with the specified value as a + * {@link JsonNumber} at the specified position. + * + * @param index the position in the array + * @param value the number value + * @return this array builder + * @throws NumberFormatException if the value is Not-a-Number (NaN) or + * infinity + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @see JsonNumber + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, double value) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with + * a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value + * at the specified position. + * + * @param index the position in the array + * @param value the boolean value + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, boolean value) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with + * a {@link JsonValue#NULL} value at the specified position. + * + * @param index the position in the array + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder setNull(int index) { + return set(index, JsonValue.NULL); + } + + /** + * Replaces a value in the array with the specified value as a + * {@link JsonObject} from an object builder at the specified position. + * + * @param index the position in the array + * @param builder the object builder + * @return this array builder + * @throws NullPointerException if the specified builder is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, JsonObjectBuilder builder) { + throw new UnsupportedOperationException(); + } + + /** + * Replaces a value in the array with the specified value as a + * {@link JsonArray} from an array builder at the specified position. + * + * @param index the position in the array + * @param builder the array builder + * @return this array builder + * @throws NullPointerException if the specified builder is null + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder set(int index, JsonArrayBuilder builder) { + throw new UnsupportedOperationException(); + } + + /** + * Remove the value in the array at the specified position. + * Shift any subsequent values to the left (subtracts one from their + * indices. + * + * @param index the position in the array + * @return this array builder + * @throws IndexOutOfBoundsException if the index is out of range + * {@code (index < 0 || index >= array size)} + * + * @since 1.1 + */ + default JsonArrayBuilder remove(int index) { + throw new UnsupportedOperationException(); + } + + /** * Returns the current array. * Index: trunk/src/javax/json/JsonBuilderFactory.java =================================================================== --- trunk/src/javax/json/JsonBuilderFactory.java (revision 6756) +++ trunk/src/javax/json/JsonBuilderFactory.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: @@ -41,4 +41,5 @@ package javax.json; +import java.util.Collection; import java.util.Map; @@ -71,6 +72,4 @@ *

All the methods in this class are safe for use by multiple concurrent * threads. - * - * @author Jitendra Kotamraju */ public interface JsonBuilderFactory { @@ -85,4 +84,30 @@ /** + * Creates a {@code JsonObjectBuilder} instance, initialized with an object. + * + * @param object the initial object in the builder + * @return a JSON object builder + * @throws NullPointerException if specified object is {@code null} + * + * @since 1.1 + */ + default JsonObjectBuilder createObjectBuilder(JsonObject object) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a {@code JsonObjectBuilder} instance, initialized with the specified object. + * + * @param object the initial object in the builder + * @return a JSON object builder + * @throws NullPointerException if specified object is {@code null} + * + * @since 1.1 + */ + default JsonObjectBuilder createObjectBuilder(Map object) { + throw new UnsupportedOperationException(); + } + + /** * Creates a {@code JsonArrayBuilder} instance that is used to build * {@link JsonArray} @@ -91,4 +116,31 @@ */ JsonArrayBuilder createArrayBuilder(); + + /** + * Creates a {@code JsonArrayBuilder} instance, initialized with an array. + * + * @param array the initial array in the builder + * @return a JSON array builder + * @throws NullPointerException if specified array is {@code null} + * + * @since 1.1 + */ + default JsonArrayBuilder createArrayBuilder(JsonArray array) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a {@code JsonArrayBuilder} instance, + * initialized with the content of specified collection. + * + * @param collection the initial data for the builder + * @return a JSON array builder + * @throws NullPointerException if specified collection is {@code null} + * + * @since 1.1 + */ + default JsonArrayBuilder createArrayBuilder(Collection collection) { + throw new UnsupportedOperationException(); + } /** Index: trunk/src/javax/json/JsonException.java =================================================================== --- trunk/src/javax/json/JsonException.java (revision 6756) +++ trunk/src/javax/json/JsonException.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,6 +44,4 @@ * JsonException indicates that some exception happened during * JSON processing. - * - * @author Jitendra Kotamraju */ public class JsonException extends RuntimeException { Index: trunk/src/javax/json/JsonMergePatch.java =================================================================== --- trunk/src/javax/json/JsonMergePatch.java (revision 13231) +++ trunk/src/javax/json/JsonMergePatch.java (revision 13231) @@ -0,0 +1,87 @@ +/* + * 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; + +/** + *

This interface represents an implementation of a JSON Merge Patch + * as defined by RFC 7396. + *

+ *

A {@code JsonMergePatch} can be instantiated with {@link Json#createMergePatch(JsonValue)} + * by specifying the patch operations in a JSON Merge Patch or using {@link Json#createMergeDiff(JsonValue, JsonValue)} + * to create a JSON Merge Patch based on the difference between two {@code JsonValue}s. + *

+ * The following illustrates both approaches. + *

1. Construct a JsonMergePatch with an existing JSON Merge Patch. + * 

{@code
+ *   JsonValue contacts = ... ; // The target to be patched
+ *   JsonValue patch = ...  ; // JSON Merge Patch
+ *   JsonMergePatch mergePatch = Json.createMergePatch(patch);
+ *   JsonValue result = mergePatch.apply(contacts);
+ * }
+ * 2. Construct a JsonMergePatch from a difference between two {@code JsonValue}s. + * 
{@code
+ *   JsonValue source = ... ; // The source object
+ *   JsonValue target = ... ; // The modified object
+ *   JsonMergePatch mergePatch = Json.createMergeDiff(source, target); // The diff between source and target in a Json Merge Patch format
+ * }
+ * + * @see RFC 7396 + * + * @since 1.1 + */ +public interface JsonMergePatch { + + /** + * Applies the JSON Merge Patch to the specified {@code target}. + * The target is not modified by the patch. + * + * @param target the target to apply the merge patch + * @return the transformed target after the patch + */ + JsonValue apply(JsonValue target); + + /** + * Returns the {@code JsonMergePatch} as {@code JsonValue}. + * + * @return this {@code JsonMergePatch} as {@code JsonValue} + */ + JsonValue toJsonValue(); +} Index: trunk/src/javax/json/JsonNumber.java =================================================================== --- trunk/src/javax/json/JsonNumber.java (revision 6756) +++ trunk/src/javax/json/JsonNumber.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: @@ -51,13 +51,11 @@ * value internally. * The {@code BigDecimal} object can be constructed from the following types: - * {@link BigDecimal#BigDecimal(int) int}, - * {@link BigDecimal#BigDecimal(long) long}, - * {@link BigDecimal#BigDecimal(BigInteger) BigInteger}, - * {@link BigDecimal#valueOf(double) double}, and - * {@link BigDecimal#BigDecimal(String) String}. + * int {@link BigDecimal#BigDecimal(int)}, + * long {@link BigDecimal#BigDecimal(long)}, + * BigInteger {@link BigDecimal#BigDecimal(BigInteger)}, + * double {@link BigDecimal#valueOf(double)}, and + * String {@link BigDecimal#BigDecimal(String)}. * Some of the method semantics in this class are defined using the * {@code BigDecimal} semantics. - * - * @author Jitendra Kotamraju */ public interface JsonNumber extends JsonValue { @@ -138,5 +136,5 @@ /** - * Returns this JSON number as a {@link BigDecimal} object. This is a + * Returns this JSON number as a {@link BigInteger} object. This is a * convenience method for {@code bigDecimalValue().toBigIntegerExact()}. * @@ -167,4 +165,15 @@ /** + * Returns this JSON number as a {@link Number} object. + * + * @return a {@link Number} representation of the JSON number + * + * @since 1.1 + */ + default Number numberValue() { + throw new UnsupportedOperationException(); + } + + /** * Returns a JSON text representation of the JSON number. The * representation is equivalent to {@link BigDecimal#toString()}. @@ -181,7 +190,7 @@ * objects are equal * - * @param obj the object to be compared for equality with + * @param obj the object to be compared for equality with * this {@code JsonNumber} - * @return {@code true} if the specified object is equal to this + * @return {@code true} if the specified object is equal to this * {@code JsonNumber} */ Index: trunk/src/javax/json/JsonObject.java =================================================================== --- trunk/src/javax/json/JsonObject.java (revision 6756) +++ trunk/src/javax/json/JsonObject.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: @@ -125,6 +125,4 @@ * name/value pairs are added to the corresponding builder or the order * in which name/value pairs appear in the corresponding stream. - * - * @author Jitendra Kotamraju */ public interface JsonObject extends JsonStructure, Map { @@ -266,5 +264,5 @@ * * @param name name whose associated value is checked - * @return return true if the associated value is {@code JsonValue.NUL}, + * @return return true if the associated value is {@code JsonValue.NULL}, * otherwise false * @throws NullPointerException if the specified name doesn't have any Index: trunk/src/javax/json/JsonObjectBuilder.java =================================================================== --- trunk/src/javax/json/JsonObjectBuilder.java (revision 6756) +++ trunk/src/javax/json/JsonObjectBuilder.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: @@ -65,5 +65,4 @@ * way to create multiple instances. * - * * The example code below shows how to build a {@code JsonObject} model that * represents the following JSON object: @@ -207,5 +206,5 @@ * @param value value in the name/value pair * @return this object builder - * @throws NumberFormatException if the value is Not-a-Number(NaN) or + * @throws NumberFormatException if the value is Not-a-Number (NaN) or * infinity * @throws NullPointerException if the specified name is null @@ -269,4 +268,32 @@ /** + * Adds all name/value pairs in the JSON object associated with the specified + * object builder to the JSON object associated with this object builder. + * The newly added name/value pair will replace any existing name/value pair with + * the same name. + * + * @param builder the specified object builder + * @return this object builder + * @throws NullPointerException if the specified builder is null + * @since 1.1 + */ + default JsonObjectBuilder addAll(JsonObjectBuilder builder) { + throw new UnsupportedOperationException(); + } + + /** + * Remove the name/value pair from the JSON object associated with this + * object builder if it is present. + * + * @param name the name in the name/value pair to be removed + * @return this object builder + * @throws NullPointerException if the specified name is null + * @since 1.1 + */ + default JsonObjectBuilder remove(String name) { + throw new UnsupportedOperationException(); + } + + /** * Returns the JSON object associated with this object builder. * The iteration order for the {@code JsonObject} is based Index: trunk/src/javax/json/JsonPatch.java =================================================================== --- trunk/src/javax/json/JsonPatch.java (revision 13231) +++ trunk/src/javax/json/JsonPatch.java (revision 13231) @@ -0,0 +1,163 @@ +/* + * 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; + +/** + *

This interface represents an immutable implementation of a JSON Patch + * as defined by RFC 6902. + *

+ *

A {@code JsonPatch} can be instantiated with {@link Json#createPatch(JsonArray)} + * by specifying the patch operations in a JSON Patch. Alternately, it + * can also be constructed with a {@link JsonPatchBuilder}. + *

+ * The following illustrates both approaches. + *

1. Construct a JsonPatch with a JSON Patch. + * 

{@code
+ *   JsonArray contacts = ... // The target to be patched
+ *   JsonArray patch = ...  ; // JSON Patch
+ *   JsonPatch jsonpatch = Json.createPatch(patch);
+ *   JsonArray result = jsonpatch.apply(contacts);
+ * }
+ * 2. Construct a JsonPatch with JsonPatchBuilder. + * 
{@code
+ *   JsonPatchBuilder builder = Json.createPatchBuilder();
+ *   JsonArray result = builder.add("/John/phones/office", "1234-567")
+ *                             .remove("/Amy/age")
+ *                             .build()
+ *                             .apply(contacts);
+ * }
+ * + * @see RFC 6902 + * + * @since 1.1 + */ +public interface JsonPatch { + + /** + * This enum represents the list of valid JSON Patch operations + * as defined by RFC 6902. + * + * @see RFC 6902 + */ + enum Operation { + + /** + * "add" operation. + */ + ADD("add"), + + /** + * "remove" operation. + */ + REMOVE("remove"), + + /** + * "remove" operation. + */ + REPLACE("replace"), + + /** + * "move" operation. + */ + MOVE("move"), + + /** + * "copy" operation. + */ + COPY("copy"), + + /** + * "test" operation. + */ + TEST("test"); + + private final String operationName; + + private Operation(String operationName) { + this.operationName = operationName; + } + + /** + * Returns enum constant name as lower case string. + * + * @return lower case name of the enum constant + */ + public String operationName() { + return operationName; + } + + /** + * Returns the enum constant with the specified name. + * + * @param operationName {@code operationName} to convert to the enum constant. + * @return the enum constant for given {@code operationName} + * @throws JsonException if given {@code operationName} is not recognized + */ + public static Operation fromOperationName(String operationName) { + for (Operation op : values()) { + if (op.operationName().equalsIgnoreCase(operationName)) { + return op; + } + } + throw new JsonException("Illegal value for the operationName of the JSON patch operation: " + operationName); + } + } + + /** + * Applies the patch operations to the specified {@code target}. + * The target is not modified by the patch. + * + * @param the target type, must be a subtype of {@link JsonStructure} + * @param target the target to apply the patch operations + * @return the transformed target after the patch + * @throws JsonException if the supplied JSON Patch is malformed or if + * it contains references to non-existing members + */ + T apply(T target); + + /** + * Returns the {@code JsonPatch} as {@code JsonArray}. + * + * @return this {@code JsonPatch} as {@code JsonArray} + */ + JsonArray toJsonArray(); + +} Index: trunk/src/javax/json/JsonPatchBuilder.java =================================================================== --- trunk/src/javax/json/JsonPatchBuilder.java (revision 13231) +++ trunk/src/javax/json/JsonPatchBuilder.java (revision 13231) @@ -0,0 +1,210 @@ +/* + * 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; + +/** + * A builder for constructing a JSON Patch as defined by + * RFC 6902 by adding + * JSON Patch operations incrementally. + *

+ * The following illustrates the approach. + * 

+ *   JsonPatchBuilder builder = Json.createPatchBuilder();
+ *   JsonPatch patch = builder.add("/John/phones/office", "1234-567")
+ *                            .remove("/Amy/age")
+ *                            .build();
+ *
+ * The result is equivalent to the following JSON Patch. + * 
+ * [
+ *    {"op" = "add", "path" = "/John/phones/office", "value" = "1234-567"},
+ *    {"op" = "remove", "path" = "/Amy/age"}
+ * ]
+ * + * @see RFC 6902 + * + * @since 1.1 + */ +public interface JsonPatchBuilder { + + /** + * Adds an "add" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder add(String path, JsonValue value); + + /** + * Adds an "add" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder add(String path, String value); + + /** + * Adds an "add" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder add(String path, int value); + + /** + * Adds an "add" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder add(String path, boolean value); + + /** + * Adds a "remove" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. + * @return this JsonPatchBuilder + */ + JsonPatchBuilder remove(String path); + + /** + * Adds a "replace" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder replace(String path, JsonValue value); + + /** + * Adds a "replace" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder replace(String path, String value); + + /** + * Adds a "replace" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder replace(String path, int value); + + /** + * Adds a "replace" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder replace(String path, boolean value); + + /** + * Adds a "move" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param from the "from" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder move(String path, String from); + + /** + * Adds a "copy" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param from the "from" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder copy(String path, String from); + + /** + * Adds a "test" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder test(String path, JsonValue value); + + /** + * Adds a "test" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder test(String path, String value); + + /** + * Adds a "test" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder test(String path, int value); + + /** + * Adds a "test" JSON Patch operation. + * + * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. + * @param value the "value" member of the operation + * @return this JsonPatchBuilder + */ + JsonPatchBuilder test(String path, boolean value); + + + /** + * Returns the JSON Patch. + * + * @return a JSON Patch + */ + JsonPatch build(); + +} Index: trunk/src/javax/json/JsonPointer.java =================================================================== --- trunk/src/javax/json/JsonPointer.java (revision 13231) +++ trunk/src/javax/json/JsonPointer.java (revision 13231) @@ -0,0 +1,140 @@ +/* + * 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; + +/** + *

This interface represents an immutable implementation of a JSON Pointer + * as defined by RFC 6901. + *

+ *

A JSON Pointer, when applied to a target {@link JsonValue}, + * defines a reference location in the target.

+ *

An empty JSON Pointer string defines a reference to the target itself.

+ *

If the JSON Pointer string is non-empty, it must be a sequence + * of '/' prefixed tokens, and the target must either be a {@link JsonArray} + * or {@link JsonObject}. If the target is a {@code JsonArray}, the pointer + * defines a reference to an array element, and the last token specifies the index. + * If the target is a {@link JsonObject}, the pointer defines a reference to a + * name/value pair, and the last token specifies the name. + *

+ *

The method {@link #getValue getValue()} returns the referenced value. + * Methods {@link #add add()}, {@link #replace replace()}, + * and {@link #remove remove()} execute operations specified in + * RFC 6902.

+ * + * @see RFC 6901 + * @see RFC 6902 + * + * @since 1.1 + */ +public interface JsonPointer { + + /** + * Adds or replaces a value at the referenced location in the specified + * {@code target} with the specified {@code value}. + *
    + *
  1. If the reference is the target (empty JSON Pointer string), + * the specified {@code value}, which must be the same type as + * specified {@code target}, is returned.
    2. + *
  2. If the reference is an array element, the specified {@code value} is inserted + * into the array, at the referenced index. The value currently at that location, and + * any subsequent values, are shifted to the right (adds one to the indices). + * Index starts with 0. If the reference is specified with a "-", or if the + * index is equal to the size of the array, the value is appended to the array.
    3. + *
  3. If the reference is a name/value pair of a {@code JsonObject}, and the + * referenced value exists, the value is replaced by the specified {@code value}. + * If the value does not exist, a new name/value pair is added to the object.
    4. + *
+ * + * @param the target type, must be a subtype of {@link JsonValue} + * @param target the target referenced by this {@code JsonPointer} + * @param value the value to be added + * @return the transformed {@code target} after the value is added. + * @throws NullPointerException if {@code target} is {@code null} + * @throws JsonException if the reference is an array element and + * the index is out of range ({@code index < 0 || index > array size}), + * or if the pointer contains references to non-existing objects or arrays. + */ + T add(T target, JsonValue value); + + /** + * Removes the value at the reference location in the specified {@code target}. + * + * @param the target type, must be a subtype of {@link JsonValue} + * @param target the target referenced by this {@code JsonPointer} + * @return the transformed {@code target} after the value is removed. + * @throws NullPointerException if {@code target} is {@code null} + * @throws JsonException if the referenced value does not exist, + * or if the reference is the target. + */ + T remove(T target); + + /** + * Replaces the value at the referenced location in the specified + * {@code target} with the specified {@code value}. + * + * @param the target type, must be a subtype of {@link JsonValue} + * @param target the target referenced by this {@code JsonPointer} + * @param value the value to be stored at the referenced location + * @return the transformed {@code target} after the value is replaced. + * @throws NullPointerException if {@code target} is {@code null} + * @throws JsonException if the referenced value does not exist, + * or if the reference is the target. + */ + T replace(T target, JsonValue value); + + /** + * Returns {@code true} if there is a value at the referenced location in the specified {@code target}. + * + * @param target the target referenced by this {@code JsonPointer} + * @return {@code true} if this pointer points to a value in a specified {@code target}. + */ + boolean containsValue(JsonStructure target); + + /** + * Returns the value at the referenced location in the specified {@code target}. + * + * @param target the target referenced by this {@code JsonPointer} + * @return the referenced value in the target. + * @throws NullPointerException if {@code target} is null + * @throws JsonException if the referenced value does not exist + */ + JsonValue getValue(JsonStructure target); +} Index: trunk/src/javax/json/JsonReader.java =================================================================== --- trunk/src/javax/json/JsonReader.java (revision 6756) +++ trunk/src/javax/json/JsonReader.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: @@ -51,5 +51,4 @@ * *

- * * The following example demonstrates how to read an empty JSON array from * a string: @@ -75,6 +74,4 @@ * * - * - * @author Jitendra Kotamraju */ public interface JsonReader extends /*Auto*/Closeable { @@ -91,6 +88,6 @@ * @throws javax.json.stream.JsonParsingException if a JSON object or array * cannot be created due to incorrect representation - * @throws IllegalStateException if read, readObject, readArray or - * close method is already called + * @throws IllegalStateException if read, readObject, readArray, + * readValue or close method is already called */ JsonStructure read(); @@ -107,6 +104,6 @@ * @throws javax.json.stream.JsonParsingException if a JSON object cannot * be created due to incorrect representation - * @throws IllegalStateException if read, readObject, readArray or - * close method is already called + * @throws IllegalStateException if read, readObject, readArray, + * readValue or close method is already called */ JsonObject readObject(); @@ -123,8 +120,28 @@ * @throws javax.json.stream.JsonParsingException if a JSON array cannot * be created due to incorrect representation - * @throws IllegalStateException if read, readObject, readArray or - * close method is already called + * @throws IllegalStateException if read, readObject, readArray, + * readValue or close method is already called */ JsonArray readArray(); + + /** + * Returns a JSON value that is represented in + * the input source. This method needs to be called + * only once for a reader instance. + * + * @return a JSON value + * @throws JsonException if a JSON value + * be created due to i/o error (IOException would be + * cause of JsonException) + * @throws javax.json.stream.JsonParsingException if a JSON value + * cannot be created due to incorrect representation + * @throws IllegalStateException if read, readObject, readArray, + * readValue or close method is already called + * + * @since 1.1 + */ + default JsonValue readValue() { + throw new UnsupportedOperationException(); + } /** Index: trunk/src/javax/json/JsonReaderFactory.java =================================================================== --- trunk/src/javax/json/JsonReaderFactory.java (revision 6756) +++ trunk/src/javax/json/JsonReaderFactory.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: @@ -68,6 +68,4 @@ *

All the methods in this class are safe for use by multiple concurrent * threads. - * - * @author Jitendra Kotamraju */ public interface JsonReaderFactory { @@ -85,5 +83,5 @@ * Creates a JSON reader from a byte stream. The character encoding of * the stream is determined as described in - * RFC 4627. + * RFC 7159. * The reader is configured with the factory configuration. * Index: trunk/src/javax/json/JsonString.java =================================================================== --- trunk/src/javax/json/JsonString.java (revision 6756) +++ trunk/src/javax/json/JsonString.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: @@ -43,6 +43,4 @@ /** * An immutable JSON string value. - * - * @author Jitendra Kotamraju */ public interface JsonString extends JsonValue { Index: trunk/src/javax/json/JsonStructure.java =================================================================== --- trunk/src/javax/json/JsonStructure.java (revision 6756) +++ trunk/src/javax/json/JsonStructure.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: @@ -44,7 +44,19 @@ * Super type for the two structured types in JSON ({@link JsonObject object}s * and {@link JsonArray array}s). - * - * @author Jitendra Kotamraju */ public interface JsonStructure extends JsonValue { + + /** + * Get the value referenced by the provided JSON Pointer in the JsonStructure. + * + * @param jsonPointer the JSON Pointer + * @return the {@code JsonValue} at the referenced location + * @throws JsonException if the JSON Pointer is malformed, or if it references + * a non-existing member or value. + * + * @since 1.1 + */ + default public JsonValue getValue(String jsonPointer) { + return Json.createPointer(jsonPointer).getValue(this); + } } Index: trunk/src/javax/json/JsonValue.java =================================================================== --- trunk/src/javax/json/JsonValue.java (revision 6756) +++ trunk/src/javax/json/JsonValue.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,15 +44,27 @@ * JsonValue represents an immutable JSON value. * - * + * *

A JSON value is one of the following: * an object ({@link JsonObject}), an array ({@link JsonArray}), * a number ({@link JsonNumber}), a string ({@link JsonString}), - * {@code true} ({@link JsonValue#TRUE JsonValue.TRUE}), {@code false} + * {@code true} ({@link JsonValue#TRUE JsonValue.TRUE}), {@code false} * ({@link JsonValue#FALSE JsonValue.FALSE}), * or {@code null} ({@link JsonValue#NULL JsonValue.NULL}). - * - * @author Jitendra Kotamraju */ public interface JsonValue { + + /** + * The empty JSON object. + * + * @since 1.1 + */ + static final JsonObject EMPTY_JSON_OBJECT = new EmptyObject(); + + /** + * The empty JSON array. + * + * @since 1.1 + */ + static final JsonArray EMPTY_JSON_ARRAY = new EmptyArray(); /** @@ -99,149 +111,15 @@ * JSON null value. */ - static final JsonValue NULL = new JsonValue() { - @Override - public ValueType getValueType() { - return ValueType.NULL; - } - - /** - * Compares the specified object with this {@link JsonValue#NULL} - * object for equality. Returns {@code true} if and only if the - * specified object is also a {@code JsonValue}, and their - * {@link #getValueType()} objects are equal. - * - * @param obj the object to be compared for equality with this - * {@code JsonValue} - * @return {@code true} if the specified object is equal to this - * {@code JsonValue} - */ - @Override - public boolean equals(Object obj) { - if (obj instanceof JsonValue) { - return getValueType().equals(((JsonValue)obj).getValueType()); - } - return false; - } - - /** - * Returns the hash code value for this {@link JsonValue#NULL} object. - * The hash code of the {@link JsonValue#NULL} object is defined to be - * its {@link #getValueType()} object's hash code. - * - * @return the hash code value for this JsonString object - */ - @Override - public int hashCode() { - return ValueType.NULL.hashCode(); - } - - /** - * Returns a "null" string. - * - * @return "null" - */ - @Override - public String toString() { - return "null"; - } - }; + static final JsonValue NULL = new JsonValueImpl(ValueType.NULL); /** * JSON true value. */ - static final JsonValue TRUE = new JsonValue() { - @Override - public ValueType getValueType() { - return ValueType.TRUE; - } - - /** - * Compares the specified object with this {@link JsonValue#TRUE} - * object for equality. Returns {@code true} if and only if the - * specified object is also a JsonValue, and their - * {@link #getValueType()} objects are equal. - * - * @param obj the object to be compared for equality with this JsonValue. - * @return {@code true} if the specified object is equal to this JsonValue. - */ - @Override - public boolean equals(Object obj) { - if (obj instanceof JsonValue) { - return getValueType().equals(((JsonValue)obj).getValueType()); - } - return false; - } - - /** - * Returns the hash code value for this {@link JsonValue#TRUE} object. - * The hash code of the {@link JsonValue#TRUE} object is defined to be - * its {@link #getValueType()} object's hash code. - * - * @return the hash code value for this JsonString object - */ - @Override - public int hashCode() { - return ValueType.TRUE.hashCode(); - } - - /** - * Returns "true" string - * - * @return "true" - */ - @Override - public String toString() { - return "true"; - } - }; + static final JsonValue TRUE = new JsonValueImpl(ValueType.TRUE); /** - * JSON false value + * JSON false value. */ - static final JsonValue FALSE = new JsonValue() { - @Override - public ValueType getValueType() { - return ValueType.FALSE; - } - - /** - * Compares the specified object with this {@link JsonValue#FALSE} - * object for equality. Returns {@code true} if and only if the - * specified object is also a JsonValue, and their - * {@link #getValueType()} objects are equal. - * - * @param obj the object to be compared for equality with this JsonValue - * @return {@code true} if the specified object is equal to this JsonValue - */ - @Override - public boolean equals(Object obj) { - if (obj instanceof JsonValue) { - return getValueType().equals(((JsonValue)obj).getValueType()); - } - return false; - } - - /** - * Returns the hash code value for this {@link JsonValue#FALSE} object. - * The hash code of the {@link JsonValue#FALSE} object is defined to be - * its {@link #getValueType()} object's hash code. - * - * @return the hash code value for this JsonString object - */ - @Override - public int hashCode() { - return ValueType.FALSE.hashCode(); - } - - /** - * Returns "false" string - * - * @return "false" - */ - @Override - public String toString() { - return "false"; - } - }; + static final JsonValue FALSE = new JsonValueImpl(ValueType.FALSE); /** @@ -251,4 +129,28 @@ */ ValueType getValueType(); + + /** + * Return the JsonValue as a JsonObject + * + * @return the JsonValue as a JsonObject + * @throws ClassCastException if the JsonValue is not a JsonObject + * + * @since 1.1 + */ + default JsonObject asJsonObject() { + return JsonObject.class.cast(this); + } + + /** + * Return the JsonValue as a JsonArray + * + * @return the JsonValue as a JsonArray + * @throws ClassCastException if the JsonValue is not a JsonArray + * + * @since 1.1 + */ + default JsonArray asJsonArray() { + return JsonArray.class.cast(this); + } /** Index: trunk/src/javax/json/JsonValueImpl.java =================================================================== --- trunk/src/javax/json/JsonValueImpl.java (revision 13231) +++ trunk/src/javax/json/JsonValueImpl.java (revision 13231) @@ -0,0 +1,107 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright (c) 2016-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; + +import java.io.Serializable; + +/** + * Private implementation of {@link JsonValue} for simple {@link ValueType}s + * allowing their usage in constants which are better to implement {@link Serializable}. + * + * @author Lukas Jungmann + */ +final class JsonValueImpl implements JsonValue, Serializable { + + private final ValueType valueType; + + JsonValueImpl(ValueType valueType) { + this.valueType = valueType; + } + + /** + * Returns the value type of this JSON value. + * + * @return JSON value type + */ + @Override + public ValueType getValueType() { + return valueType; + } + + /** + * Compares the specified object with this {@link JsonValue} + * object for equality. Returns {@code true} if and only if the + * specified object is also a JsonValue, and their + * {@link #getValueType()} objects are equal. + * + * @param obj the object to be compared for equality with this JsonValue + * @return {@code true} if the specified object is equal to this + * JsonValue + */ + @Override + public boolean equals(Object obj) { + if (this == obj) { + return true; + } + if (obj instanceof JsonValue) { + return getValueType().equals(((JsonValue) obj).getValueType()); + } + return false; + } + + /** + * Returns the hash code value for this {@link JsonValue} object. + * The hash code of the {@link JsonValue} object is defined to be + * its {@link #getValueType()} object's hash code. + * + * @return the hash code value for this {@link JsonValue} object + */ + @Override + public int hashCode() { + return valueType.hashCode(); + } + + @Override + public String toString() { + return valueType.name().toLowerCase(); + } + +} Index: trunk/src/javax/json/JsonWriter.java =================================================================== --- trunk/src/javax/json/JsonWriter.java (revision 6756) +++ trunk/src/javax/json/JsonWriter.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: @@ -51,5 +51,4 @@ * *

- * * The following example demonstrates how write an empty JSON object: * 

@@ -74,6 +73,4 @@
  * 
  *
- * - * @author Jitendra Kotamraju */ public interface JsonWriter extends /*Auto*/Closeable { @@ -126,4 +123,23 @@ * cause of JsonException) */ + + /** + * Writes the specified {@link JsonValue} to the output source. + * method needs to be called only once for a write instance. + * + * @param value a {@code JsonValue} to be written to the output + * source + * @throws JsonException if the specified JSON object cannot be + * written due to i/o error (IOException would be cause of + * JsonException) + * @throws IllegalStateException if writeArray, writeObject, write + * or close method is already called + * + * @since 1.1 + */ + default void write(JsonValue value) { + throw new UnsupportedOperationException(); + } + @Override void close(); Index: trunk/src/javax/json/JsonWriterFactory.java =================================================================== --- trunk/src/javax/json/JsonWriterFactory.java (revision 6756) +++ trunk/src/javax/json/JsonWriterFactory.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: @@ -68,6 +68,4 @@ *

All the methods in this class are safe for use by multiple concurrent * threads. - * - * @author Jitendra Kotamraju */ public interface JsonWriterFactory { Index: trunk/src/javax/json/package-info.java =================================================================== --- trunk/src/javax/json/package-info.java (revision 6756) +++ trunk/src/javax/json/package-info.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: @@ -51,7 +51,7 @@ * ordered sequence of zero or more values from the model. * - *

The object model API uses builder patterns to create these object models. - * The classes {@link javax.json.JsonObjectBuilder} and - * {@link javax.json.JsonArrayBuilder} provide methods to create models + *

The object model API uses builder patterns to create and modify + * these object models. The classes {@link javax.json.JsonObjectBuilder} and + * {@link javax.json.JsonArrayBuilder} provide methods to create and modify models * of type {@code JsonObject} and {@code JsonArray} respectively. * @@ -59,7 +59,11 @@ * the class {@link javax.json.JsonReader}. Similarly, these object models * can be written to an output source using the class {@link javax.json.JsonWriter}. - * - * @since JSON Processing 1.0 - * @author Jitendra Kotamraju + *

+ * This package includes several classes that implement other JSON related + * standards: JSON Pointer, + * JSON Patch, and + * JSON Merge Patch. + * They can be used to retrieve, transform or manipulate values in an + * object model. */ package javax.json; Index: trunk/src/javax/json/spi/JsonProvider.java =================================================================== --- trunk/src/javax/json/spi/JsonProvider.java (revision 6756) +++ trunk/src/javax/json/spi/JsonProvider.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: @@ -50,7 +50,11 @@ import java.io.Reader; import java.io.Writer; +import java.util.Collection; import java.util.Iterator; import java.util.Map; import java.util.ServiceLoader; +import java.math.BigDecimal; +import java.math.BigInteger; +import java.util.Optional; /** @@ -61,5 +65,4 @@ * * @see ServiceLoader - * @author Jitendra Kotamraju */ public abstract class JsonProvider { @@ -76,8 +79,8 @@ /** - * * Creates a JSON provider object. The provider is loaded using the * {@link ServiceLoader#load(Class)} method. If there are no available * service providers, this method returns the default service provider. + * Users are recommended to cache the result of this method. * * @see ServiceLoader @@ -90,8 +93,7 @@ return it.next(); } - try { Class clazz = Class.forName(DEFAULT_PROVIDER); - return (JsonProvider)clazz.newInstance(); + return (JsonProvider) clazz.newInstance(); } catch (ClassNotFoundException x) { throw new JsonException( @@ -115,5 +117,5 @@ * Creates a JSON parser from the specified byte stream. * The character encoding of the stream is determined - * as defined in RFC 4627 + * as defined in RFC 7159 * . * @@ -193,5 +195,5 @@ * Creates a JSON reader from a byte stream. The character encoding of * the stream is determined as described in - * RFC 4627. + * RFC 7159. * * @param in a byte stream from which JSON is to be read @@ -246,5 +248,5 @@ /** - * Creates a JSON object builder + * Creates a JSON object builder. * * @return a JSON object builder @@ -253,9 +255,166 @@ /** - * Creates a JSON array builder + * Creates a JSON object builder, initialized with the specified object. + * + * @param object the initial JSON object in the builder + * @return a JSON object builder + * + * @since 1.1 + */ + public JsonObjectBuilder createObjectBuilder(JsonObject object) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JSON object builder, initialized with the data from specified {@code map}. + * If the @{code map} contains {@link Optional}s then resulting JSON object builder + * contains the key from the {@code map} only if the {@link Optional} is not empty. + * + * @param map the initial object in the builder + * @return a JSON object builder + * @exception IllegalArgumentException if the value from the {@code map} cannot be converted + * to the corresponding {@link JsonValue} + * + * @since 1.1 + */ + public JsonObjectBuilder createObjectBuilder(Map map) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JSON array builder. * * @return a JSON array builder */ public abstract JsonArrayBuilder createArrayBuilder(); + + /** + * Creates a JSON array builder, initialized with the specified array. + * + * @param array the initial JSON array in the builder + * @return a JSON array builder + * + * @since 1.1 + */ + public JsonArrayBuilder createArrayBuilder(JsonArray array) { + throw new UnsupportedOperationException(); + } + + /** + * Creates JSON Pointer (RFC 6901) + * from given {@code jsonPointer} string. + *

    + *
  • An empty {@code jsonPointer} string defines a reference to the target itself.
    • + *
  • If the {@code jsonPointer} string is non-empty, it must be a sequence of '{@code /}' prefixed tokens.
    • + *
+ * + * @param jsonPointer the JSON Pointer string + * @throws NullPointerException if {@code jsonPointer} is {@code null} + * @throws JsonException if {@code jsonPointer} is not a valid JSON Pointer + * @return a JSON Pointer + * + * @since 1.1 + */ + public JsonPointer createPointer(String jsonPointer) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JSON Patch builder (RFC 6902). + * + * @return a JSON Patch builder + * + * @since 1.1 + */ + public JsonPatchBuilder createPatchBuilder() { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JSON Patch builder + * (RFC 6902), + * initialized with the specified operations. + * + * @param array the initial patch operations + * @return a JSON Patch builder + * + * @since 1.1 + */ + public JsonPatchBuilder createPatchBuilder(JsonArray array) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JSON Patch (RFC 6902) + * from the specified operations. + * + * @param array patch operations + * @return a JSON Patch + * + * @since 1.1 + */ + public JsonPatch createPatch(JsonArray array) { + throw new UnsupportedOperationException(); + } + + /** + * Generates a JSON Patch (RFC 6902) + * from the source and target {@code JsonStructure}. + * The generated JSON Patch need not be unique. + * + * @param source the source + * @param target the target, must be the same type as the source + * @return a JSON Patch which when applied to the source, yields the target + * + * @since 1.1 + */ + public JsonPatch createDiff(JsonStructure source, JsonStructure target) { + throw new UnsupportedOperationException(); + } + + /** + * Creates JSON Merge Patch (RFC 7396) + * from specified {@code JsonValue}. + * + * @param patch the patch + * @return a JSON Merge Patch + * + * @since 1.1 + */ + public JsonMergePatch createMergePatch(JsonValue patch) { + throw new UnsupportedOperationException(); + } + + /** + * Generates a JSON Merge Patch (RFC 7396) + * from the source and target {@code JsonValue}s + * which when applied to the {@code source}, yields the {@code target}. + * + * @param source the source + * @param target the target + * @return a JSON Merge Patch + * + * @since 1.1 + */ + public JsonMergePatch createMergeDiff(JsonValue source, JsonValue target) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JSON array builder, initialized with the content of specified {@code collection}. + * If the @{code collection} contains {@link Optional}s then resulting JSON array builder + * contains the value from the {@code collection} only if the {@link Optional} is not empty. + * + * @param collection the initial data for the builder + * @return a JSON array builder + * @exception IllegalArgumentException if the value from the {@code collection} cannot be converted + * to the corresponding {@link JsonValue} + * + * @since 1.1 + */ + public JsonArrayBuilder createArrayBuilder(Collection collection) { + throw new UnsupportedOperationException(); + } + /** @@ -272,3 +431,74 @@ public abstract JsonBuilderFactory createBuilderFactory(Map config); + /** + * Creates a JsonString. + * + * @param value a JSON string + * @return the JsonString for the string + * + * @since 1.1 + */ + public JsonString createValue(String value) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public JsonNumber createValue(int value) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public JsonNumber createValue(long value) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public JsonNumber createValue(double value) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public JsonNumber createValue(BigDecimal value) { + throw new UnsupportedOperationException(); + } + + /** + * Creates a JsonNumber. + * + * @param value a JSON number + * @return the JsonNumber for the number + * + * @since 1.1 + */ + public JsonNumber createValue(BigInteger value) { + throw new UnsupportedOperationException(); + } } Index: trunk/src/javax/json/spi/package-info.java =================================================================== --- trunk/src/javax/json/spi/package-info.java (revision 6756) +++ trunk/src/javax/json/spi/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: @@ -53,5 +53,4 @@ * * @since JSON Processing 1.0 - * @author Jitendra Kotamraju */ package javax.json.spi; 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;