Changeset 13231 in josm for trunk/src/javax


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

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

Location:
trunk/src/javax/json
Files:
8 added
26 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/javax/json/Json.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4141package javax.json;
    4242
     43import java.io.InputStream;
     44import java.io.OutputStream;
     45import java.io.Reader;
     46import java.io.Writer;
     47import java.math.BigDecimal;
     48import java.math.BigInteger;
     49import java.util.Collection;
     50import java.util.Map;
     51import java.util.Optional;
    4352import javax.json.spi.JsonProvider;
    4453import javax.json.stream.JsonGenerator;
    … …  
    4655import javax.json.stream.JsonParser;
    4756import javax.json.stream.JsonParserFactory;
    48 import java.io.*;
    49 import java.util.Map;
    5057
    5158/**
    … …  
    7380 * All the methods in this class are safe for use by multiple concurrent
    7481 * threads.
    75  *
    76  * @author Jitendra Kotamraju
    7782 */
    78 public class Json {
     83public final class Json {
    7984
    8085    private Json() {
    … …  
    9398    /**
    9499     * Creates a JSON parser from a byte stream.
    95      * The character encoding of the stream is determined as specified in 
    96      * <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
     100     * The character encoding of the stream is determined as specified in
     101     * <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
    97102     *
    98103     * @param in i/o stream from which JSON is to be read
    … …  
    212217     * Creates a JSON reader from a byte stream. The character encoding of
    213218     * the stream is determined as described in
    214      * <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
     219     * <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
    215220     *
    216221     * @param in a byte stream from which JSON is to be read
    … …  
    259264
    260265    /**
     266     * Creates a JSON array builder, initialized with the specified array
     267     *
     268     * @param array the initial array in the builder
     269     * @return a JSON array builder
     270     *
     271     * @since 1.1
     272     */
     273    public static JsonArrayBuilder createArrayBuilder(JsonArray array) {
     274        return JsonProvider.provider().createArrayBuilder(array);
     275    }
     276
     277    /**
     278     * Creates a JSON array builder, initialized with the content of specified {@code collection}.
     279     * If the @{code collection} contains {@link Optional}s then resulting JSON array builder
     280     * contains the value from the {@code collection} only if the {@link Optional} is not empty.
     281     *
     282     * @param collection the initial data for the builder
     283     * @return a JSON array builder
     284     * @exception IllegalArgumentException if the value from the {@code collection} cannot be converted
     285     *            to the corresponding {@link JsonValue}
     286     *
     287     * @since 1.1
     288     */
     289    public static JsonArrayBuilder createArrayBuilder(Collection<?> collection) {
     290        return JsonProvider.provider().createArrayBuilder(collection);
     291    }
     292
     293    /**
    261294     * Creates a JSON object builder
    262295     *
    … …  
    265298    public static JsonObjectBuilder createObjectBuilder() {
    266299        return JsonProvider.provider().createObjectBuilder();
     300    }
     301
     302    /**
     303     * Creates a JSON object builder, initialized with the specified object.
     304     *
     305     * @param object the initial object in the builder
     306     * @return a JSON object builder
     307     *
     308     * @since 1.1
     309     */
     310    public static JsonObjectBuilder createObjectBuilder(JsonObject object) {
     311        return JsonProvider.provider().createObjectBuilder(object);
     312    }
     313
     314    /**
     315     * Creates a JSON object builder, initialized with the data from specified {@code map}.
     316     * If the @{code map} contains {@link Optional}s then resulting JSON object builder
     317     * contains the key from the {@code map} only if the {@link Optional} is not empty.
     318     *
     319     * @param map the initial object in the builder
     320     * @return a JSON object builder
     321     * @exception IllegalArgumentException if the value from the {@code map} cannot be converted
     322     *            to the corresponding {@link JsonValue}
     323     *
     324     * @since 1.1
     325     */
     326    public static JsonObjectBuilder createObjectBuilder(Map<String, Object> map) {
     327        return JsonProvider.provider().createObjectBuilder(map);
     328    }
     329
     330    /**
     331     * Creates JSON Pointer (<a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>)
     332     * from given {@code jsonPointer} string.
     333     * <ul>
     334     *     <li>An empty {@code jsonPointer} string defines a reference to the target itself.</li>
     335     *     <li>If the {@code jsonPointer} string is non-empty, it must be a sequence of '{@code /}' prefixed tokens.</li>
     336     * </ul>
     337     *
     338     * @param jsonPointer the valid escaped JSON Pointer string
     339     * @throws NullPointerException if {@code jsonPointer} is {@code null}
     340     * @throws JsonException if {@code jsonPointer} is not a valid JSON Pointer
     341     * @return a JSON Pointer
     342     *
     343     * @since 1.1
     344     */
     345    public static JsonPointer createPointer(String jsonPointer) {
     346        return JsonProvider.provider().createPointer(jsonPointer);
     347    }
     348
     349    /**
     350     * Creates a JSON Patch builder (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>).
     351     *
     352     * @return a JSON Patch builder
     353     *
     354     * @since 1.1
     355     */
     356    public static JsonPatchBuilder createPatchBuilder() {
     357        return JsonProvider.provider().createPatchBuilder();
     358    }
     359
     360    /**
     361     * Creates a JSON Patch builder
     362     * (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>),
     363     * initialized with the specified operations.
     364     *
     365     * @param array the initial patch operations
     366     * @return a JSON Patch builder
     367     *
     368     * @since 1.1
     369     */
     370    public static JsonPatchBuilder createPatchBuilder(JsonArray array) {
     371        return JsonProvider.provider().createPatchBuilder(array);
     372    }
     373
     374    /**
     375     * Creates a JSON Patch (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>)
     376     * from the specified operations.
     377     *
     378     * @param array patch operations
     379     * @return a JSON Patch
     380     *
     381     * @since 1.1
     382     */
     383    public static JsonPatch createPatch(JsonArray array) {
     384        return JsonProvider.provider().createPatch(array);
     385    }
     386
     387    /**
     388     * Generates a JSON Patch (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>)
     389     * from the source and target {@code JsonStructure}.
     390     * The generated JSON Patch need not be unique.
     391     *
     392     * @param source the source
     393     * @param target the target, must be the same type as the source
     394     * @return a JSON Patch which when applied to the source, yields the target
     395     *
     396     * @since 1.1
     397     */
     398    public static JsonPatch createDiff(JsonStructure source, JsonStructure target) {
     399        return JsonProvider.provider().createDiff(source, target);
     400    }
     401
     402    /**
     403     * Creates JSON Merge Patch (<a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>)
     404     * from specified {@code JsonValue}.
     405     *
     406     * @param patch the patch
     407     * @return a JSON Merge Patch
     408     *
     409     * @since 1.1
     410     */
     411    public static JsonMergePatch createMergePatch(JsonValue patch) {
     412        return JsonProvider.provider().createMergePatch(patch);
     413    }
     414
     415    /**
     416     * Generates a JSON Merge Patch (<a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>)
     417     * from the source and target {@code JsonValue}s
     418     * which when applied to the {@code source}, yields the {@code target}.
     419     *
     420     * @param source the source
     421     * @param target the target
     422     * @return a JSON Merge Patch
     423     *
     424     * @since 1.1
     425     */
     426    public static JsonMergePatch createMergeDiff(JsonValue source, JsonValue target) {
     427        return JsonProvider.provider().createMergeDiff(source, target);
    267428    }
    268429
    … …  
    283444    }
    284445
     446    /**
     447     * Creates a JsonString.
     448     *
     449     * @param value a JSON string
     450     * @return the JsonString for the string
     451     *
     452     * @since 1.1
     453     */
     454    public static JsonString createValue(String value) {
     455        return JsonProvider.provider().createValue(value);
     456    }
     457
     458    /**
     459     * Creates a JsonNumber.
     460     *
     461     * @param value a JSON number
     462     * @return the JsonNumber for the number
     463     *
     464     * @since 1.1
     465     */
     466    public static JsonNumber createValue(int value) {
     467        return JsonProvider.provider().createValue(value);
     468    }
     469
     470    /**
     471     * Creates a JsonNumber.
     472     *
     473     * @param value a JSON number
     474     * @return the JsonNumber for the number
     475     *
     476     * @since 1.1
     477     */
     478    public static JsonNumber createValue(long value) {
     479        return JsonProvider.provider().createValue(value);
     480    }
     481
     482    /**
     483     * Creates a JsonNumber.
     484     *
     485     * @param value a JSON number
     486     * @return the JsonNumber for the number
     487     *
     488     * @since 1.1
     489     */
     490    public static JsonNumber createValue(double value) {
     491        return JsonProvider.provider().createValue(value);
     492    }
     493
     494    /**
     495     * Creates a JsonNumber.
     496     *
     497     * @param value a JSON number
     498     * @return the JsonNumber for the number
     499     *
     500     * @since 1.1
     501     */
     502    public static JsonNumber createValue(BigDecimal value) {
     503        return JsonProvider.provider().createValue(value);
     504    }
     505
     506    /**
     507     * Creates a JsonNumber.
     508     *
     509     * @param value a JSON number
     510     * @return the JsonNumber for the number
     511     *
     512     * @since 1.1
     513     */
     514    public static JsonNumber createValue(BigInteger value) {
     515        return JsonProvider.provider().createValue(value);
     516    }
     517
     518    /**
     519     * Encodes (escapes) a passed string as defined by <a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>.
     520     * This method doesn't validate the passed JSON-pointer string.
     521     *
     522     * @param pointer the JSON-pointer string to encode
     523     * @return encoded JSON-pointer string
     524     *
     525     * @since 1.1
     526     */
     527    public static String encodePointer(String pointer) {
     528        return pointer.replace("~", "~0").replace("/", "~1");
     529    }
     530
     531    /**
     532     * Decodes a passed JSON-pointer string as defined by <a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>.
     533     * This method doesn't validate the passed JSON-pointer string.
     534     *
     535     * @param escaped the JSON-pointer string to decode
     536     * @return decoded JSON-pointer string
     537     *     
     538     * @since 1.1
     539     */
     540    public static String decodePointer(String escaped) {
     541        return escaped.replace("~1", "/").replace("~0", "~");
     542    }
     543
    285544}

  • trunk/src/javax/json/JsonArray.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4242
    4343import java.util.List;
     44import java.util.function.Function;
     45import java.util.stream.Collectors;
     46import java.util.stream.Stream;
    4447
    4548/**
    … …  
    111114 * whether directly or using its collection views, results in an
    112115 * {@code UnsupportedOperationException}.
    113  *
    114  * @author Jitendra Kotamraju
    115116 */
    116117public interface JsonArray extends JsonStructure, List<JsonValue> {
    … …  
    165166
    166167    /**
    167      * Returns a list a view of the specified type for the array. This method
     168     * Returns a list view of the specified type for the array. This method
    168169     * does not verify if there is a value of wrong type in the array. Providing
    169170     * this typesafe view dynamically may cause a program fail with a
    … …  
    172173     * method returns.
    173174     *
     175     * @param <T> The type of the List for the array
    174176     * @param clazz a JsonValue type
    175      * @return a list view of the  specified type
     177     * @return a list view of the specified type
    176178     */
    177179    <T extends JsonValue> List<T> getValuesAs(Class<T> clazz);
     180
     181    /**
     182     * Returns a list view for the array. The value and the type of the elements
     183     * in the list is specified by the {@code func} argument.
     184     * <p>This method can be used to obtain a list of the unwrapped types, such as
     185     * <pre>{@code
     186     *     List<String> strings = ary1.getValuesAs(JsonString::getString);
     187     *     List<Integer> ints = ary2.getValuesAs(JsonNumber::intValue);
     188     * } </pre>
     189     * or a list of simple projections, such as
     190     * <pre> {@code
     191     *     List<Integer> stringsizes = ary1.getValueAs((JsonString v)->v.getString().length();
     192     * } </pre>
     193     * @param <K> The element type (must be a subtype of JsonValue) of this JsonArray.
     194     * @param <T> The element type of the returned List
     195     * @param func The function that maps the elements of this JsonArray to the target elements.
     196     * @return A List of the specified values and type.
     197     * @throws ClassCastException if the {@code JsonArray} contains a value of wrong type
     198     *
     199     * @since 1.1
     200     */
     201    default <T, K extends JsonValue> List<T> getValuesAs(Function<K, T> func) {
     202        @SuppressWarnings("unchecked")
     203        Stream<K> stream = (Stream<K>) stream();
     204        return stream.map(func).collect(Collectors.toList());
     205    }
    178206
    179207    /**
    … …  
    195223     * the specified default value is returned.
    196224     *
    197      * @param index index of the JsonString value
     225     * @param index index of the {@code JsonString} value
     226     * @param defaultValue the String to return if the {@code JsonValue} at the
     227     *    specified position is not a {@code JsonString}
    198228     * @return the String value at the specified position in this array,
    199229     * or the specified default value
    … …  
    220250     *
    221251     * @param index index of the {@code JsonNumber} value
     252     * @param defaultValue the int value to return if the {@code JsonValue} at
     253     *     the specified position is not a {@code JsonNumber}
    222254     * @return the int value at the specified position in this array,
    223255     * or the specified default value
    … …  
    247279     *
    248280     * @param index index of the JSON boolean value
     281     * @param defaultValue the boolean value to return if the {@code JsonValue}
     282     *    at the specified position is neither TRUE nor FALSE
    249283     * @return the boolean value at the specified position,
    250284     * or the specified default value
    … …  
    258292     * @param index index of the JSON null value
    259293     * @return return true if the value at the specified location is
    260      * {@code JsonValue.NUL}, otherwise false
     294     * {@code JsonValue.NULL}, otherwise false
    261295     * @throws IndexOutOfBoundsException if the index is out of range
    262296     */
    263297    boolean isNull(int index);
    264 
    265298}

  • trunk/src/javax/json/JsonArrayBuilder.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4545
    4646/**
    47  * A builder for creating {@link JsonArray} models from scratch. This
    48  * interface initializes an empty JSON array model and provides methods to add
    49  * values to the array model and to return the resulting array. The methods
    50  * in this class can be chained to add multiple values to the array.
     47 * A builder for creating {@link JsonArray} models from scratch, and for
     48 * modifying a existing {@code JsonArray}.
     49 * <p>A {@code JsonArrayBuilder} can start with an empty or a non-empty
     50 * JSON array model. This interface provides methods to add, insert, remove
     51 * and replace values in the JSON array model.</p>
     52 * <p>Methods in this class can be chained to perform multiple values to
     53 * the array.</p>
    5154 *
    5255 * <p>The class {@link javax.json.Json} contains methods to create the builder
    … …  
    6467 * way to create multiple instances.
    6568 *
    66  * <a id="JsonArrayBuilderExample1"/>
    6769 * The example code below shows how to build a {@code JsonArray} object
    6870 * that represents the following JSON array:
    … …  
    165167     * @param value the number value
    166168     * @return this array builder
    167      * @throws NumberFormatException if the value is Not-a-Number(NaN) or
     169     * @throws NumberFormatException if the value is Not-a-Number (NaN) or
    168170     *      infinity
    169171     *
    … …  
    207209
    208210    /**
     211     * Adds all elements of the array in the specified array builder to the array.
     212     *
     213     * @param builder the array builder
     214     * @return this array builder
     215     * @throws NullPointerException if the specified builder is null
     216     *
     217     @since 1.1
     218     */
     219    default JsonArrayBuilder addAll(JsonArrayBuilder builder) {
     220        throw new UnsupportedOperationException();
     221    }
     222
     223    /**
     224     * Inserts a value to the array at the specified position. Shifts the value
     225     * currently at that position (if any) and any subsequent values to the right
     226     * (adds one to their indices).  Index starts with 0.
     227     *
     228     * @param index the position in the array
     229     * @param value the JSON value
     230     * @return this array builder
     231     * @throws NullPointerException if the specified value is null
     232     * @throws IndexOutOfBoundsException if the index is out of range
     233     *   {@code (index < 0 || index > array size)}
     234     *
     235     * @since 1.1
     236     */
     237    default JsonArrayBuilder add(int index, JsonValue value) {
     238        throw new UnsupportedOperationException();
     239    }
     240
     241    /**
     242     * Adds a value to the array as a {@link JsonString} at the specified position.
     243     * Shifts the value currently at that position (if any) and any subsequent values
     244     * to the right (adds one to their indices).  Index starts with 0.
     245     *
     246     * @param index the position in the array
     247     * @param value the string value
     248     * @return this array builder
     249     * @throws NullPointerException if the specified value is null
     250     * @throws IndexOutOfBoundsException if the index is out of range
     251     *   {@code (index < 0 || index > array size)}
     252     *
     253     * @since 1.1
     254     */
     255    default JsonArrayBuilder add(int index, String value) {
     256        throw new UnsupportedOperationException();
     257    }
     258
     259    /**
     260     * Adds a value to the array as a {@link JsonNumber} at the specified position.
     261     * Shifts the value currently at that position (if any) and any subsequent values
     262     * to the right (adds one to their indices).  Index starts with 0.
     263     *
     264     * @param index the position in the array
     265     * @param value the number value
     266     * @return this array builder
     267     * @throws NullPointerException if the specified value is null
     268     * @throws IndexOutOfBoundsException if the index is out of range
     269     *   {@code (index < 0 || index > array size)}
     270     *
     271     * @see JsonNumber
     272     *
     273     * @since 1.1
     274     */
     275    default JsonArrayBuilder add(int index, BigDecimal value) {
     276        throw new UnsupportedOperationException();
     277    }
     278
     279    /**
     280     * Adds a value to the array as a {@link JsonNumber} at the specified position.
     281     * Shifts the value currently at that position (if any) and any subsequent values
     282     * to the right (adds one to their indices).  Index starts with 0.
     283     *
     284     * @param index the position in the array
     285     * @param value the number value
     286     * @return this array builder
     287     * @throws NullPointerException if the specified value is null
     288     * @throws IndexOutOfBoundsException if the index is out of range
     289     *   {@code (index < 0 || index > array size)}
     290     *
     291     * @see JsonNumber
     292     *
     293     * @since 1.1
     294     */
     295    default JsonArrayBuilder add(int index, BigInteger value) {
     296        throw new UnsupportedOperationException();
     297    }
     298
     299    /**
     300     * Adds a value to the array as a {@link JsonNumber} at the specified position.
     301     * Shifts the value currently at that position (if any) and any subsequent values
     302     * to the right (adds one to their indices).  Index starts with 0.
     303     *
     304     * @param index the position in the array
     305     * @param value the number value
     306     * @return this array builder
     307     * @throws IndexOutOfBoundsException if the index is out of range
     308     *   {@code (index < 0 || index > array size)}
     309     *
     310     * @see JsonNumber
     311     *
     312     * @since 1.1
     313     */
     314    default JsonArrayBuilder add(int index, int value) {
     315        throw new UnsupportedOperationException();
     316    }
     317
     318    /**
     319     * Adds a value to the array as a {@link JsonNumber} at the specified position.
     320     * Shifts the value currently at that position (if any) and any subsequent values
     321     * to the right (adds one to their indices).  Index starts with 0.
     322     *
     323     * @param index the position in the array
     324     * @param value the number value
     325     * @return this array builder
     326     * @throws IndexOutOfBoundsException if the index is out of range
     327     *   {@code (index < 0 || index > array size)}
     328     *
     329     * @see JsonNumber
     330     *
     331     * @since 1.1
     332     */
     333    default JsonArrayBuilder add(int index, long value) {
     334        throw new UnsupportedOperationException();
     335    }
     336
     337    /**
     338     * Adds a value to the array as a {@link JsonNumber} at the specified position.
     339     * Shifts the value currently at that position (if any) and any subsequent values
     340     * to the right (adds one to their indices).  Index starts with 0.
     341     *
     342     * @param index the position in the array
     343     * @param value the number value
     344     * @return this array builder
     345     * @throws NumberFormatException if the value is Not-a-Number (NaN) or
     346     *      infinity
     347     * @throws IndexOutOfBoundsException if the index is out of range
     348     *   {@code (index < 0 || index > array size)}
     349     *
     350     * @see JsonNumber
     351     *
     352     * @since 1.1
     353     */
     354    default JsonArrayBuilder add(int index, double value) {
     355        throw new UnsupportedOperationException();
     356    }
     357
     358    /**
     359     * Adds a {@link JsonValue#TRUE}  or {@link JsonValue#FALSE} value to the
     360     * array at the specified position.
     361     * Shifts the value currently at that position (if any) and any subsequent values
     362     * to the right (adds one to their indices).  Index starts with 0.
     363     *
     364     * @param index the position in the array
     365     * @param value the boolean value
     366     * @return this array builder
     367     * @throws IndexOutOfBoundsException if the index is out of range
     368     *   {@code (index < 0 || index > array size)}
     369     *
     370     * @since 1.1
     371     */
     372    default JsonArrayBuilder add(int index, boolean value) {
     373        throw new UnsupportedOperationException();
     374    }
     375
     376    /**
     377     * Adds a {@link JsonValue#NULL} value to the array at the specified position.
     378     * Shifts the value currently at that position (if any) and any subsequent values
     379     * to the right (adds one to their indices).  Index starts with 0.
     380     *
     381     * @param index the position in the array
     382     * @return this array builder
     383     * @throws IndexOutOfBoundsException if the index is out of range
     384     *   {@code (index < 0 || index > array size)}
     385     *
     386     * @since 1.1
     387     */
     388    default JsonArrayBuilder addNull(int index) {
     389        return add(index, JsonValue.NULL);
     390    }
     391
     392    /**
     393     * Adds a {@link JsonObject} from an object builder to the array at the specified position.
     394     * Shifts the value currently at that position (if any) and any subsequent values
     395     * to the right (adds one to their indices).  Index starts with 0.
     396     *
     397     * @param index the position in the array
     398     * @param builder the object builder
     399     * @return this array builder
     400     * @throws NullPointerException if the specified builder is null
     401     * @throws IndexOutOfBoundsException if the index is out of range
     402     *   {@code (index < 0 || index > array size)}
     403     *
     404     * @since 1.1
     405     */
     406    default JsonArrayBuilder add(int index, JsonObjectBuilder builder) {
     407        throw new UnsupportedOperationException();
     408    }
     409
     410    /**
     411     * Adds a {@link JsonArray} from an array builder to the array at the specified position.
     412     * Shifts the value currently at that position (if any) and any subsequent values
     413     * to the right (adds one to their indices).  Index starts with 0.
     414     *
     415     * @param index the position in the array
     416     * @param builder the array builder
     417     * @return this array builder
     418     * @throws NullPointerException if the specified builder is null
     419     * @throws IndexOutOfBoundsException if the index is out of range
     420     *   {@code (index < 0 || index > array size)}
     421     *
     422     * @since 1.1
     423     */
     424    default JsonArrayBuilder add(int index, JsonArrayBuilder builder) {
     425        throw new UnsupportedOperationException();
     426    }
     427
     428    /**
     429     * Replaces a value in the array with the specified value at the
     430     * specified position.
     431     *
     432     * @param index the position in the array
     433     * @param value the JSON value
     434     * @return this array builder
     435     * @throws NullPointerException if the specified value is null
     436     * @throws IndexOutOfBoundsException if the index is out of range
     437     *   {@code (index < 0 || index >= array size)}
     438     *
     439     * @since 1.1
     440     */
     441    default JsonArrayBuilder set(int index, JsonValue value) {
     442        throw new UnsupportedOperationException();
     443    }
     444
     445    /**
     446     * Replaces a value in the array with the specified value as a
     447     * {@link JsonString} at the specified position.
     448     *
     449     * @param index the position in the array
     450     * @param value the string value
     451     * @return this array builder
     452     * @throws NullPointerException if the specified value is null
     453     * @throws IndexOutOfBoundsException if the index is out of range
     454     *   {@code (index < 0 || index >= array size)}
     455     *
     456     * @since 1.1
     457     */
     458    default JsonArrayBuilder set(int index, String value) {
     459        throw new UnsupportedOperationException();
     460    }
     461
     462    /**
     463     * Replaces a value in the array with the specified value as a
     464     * {@link JsonNumber} at the specified position.
     465     *
     466     * @param index the position in the array
     467     * @param value the number value
     468     * @return this array builder
     469     * @throws NullPointerException if the specified value is null
     470     * @throws IndexOutOfBoundsException if the index is out of range
     471     *   {@code (index < 0 || index >= array size)}
     472     *
     473     * @see JsonNumber
     474     *
     475     * @since 1.1
     476     */
     477    default JsonArrayBuilder set(int index, BigDecimal value) {
     478        throw new UnsupportedOperationException();
     479    }
     480
     481    /**
     482     * Replaces a value in the array with the specified value as a
     483     * {@link JsonNumber} at the specified position.
     484     *
     485     * @param index the position in the array
     486     * @param value the number value
     487     * @return this array builder
     488     * @throws NullPointerException if the specified value is null
     489     * @throws IndexOutOfBoundsException if the index is out of range
     490     *   {@code (index < 0 || index >= array size)}
     491     *
     492     * @see JsonNumber
     493     *
     494     * @since 1.1
     495     */
     496    default JsonArrayBuilder set(int index, BigInteger value) {
     497        throw new UnsupportedOperationException();
     498    }
     499
     500    /**
     501     * Replaces a value in the array with the specified value as a
     502     * {@link JsonNumber} at the specified position.
     503     *
     504     * @param index the position in the array
     505     * @param value the number value
     506     * @return this array builder
     507     * @throws IndexOutOfBoundsException if the index is out of range
     508     *   {@code (index < 0 || index >= array size)}
     509     *
     510     * @see JsonNumber
     511     *
     512     * @since 1.1
     513     */
     514    default JsonArrayBuilder set(int index, int value) {
     515        throw new UnsupportedOperationException();
     516    }
     517
     518    /**
     519     * Replaces a value in the array with the specified value as a
     520     * {@link JsonNumber} at the specified position.
     521     *
     522     * @param index the position in the array
     523     * @param value the number value
     524     * @return this array builder
     525     * @throws IndexOutOfBoundsException if the index is out of range
     526     *   {@code (index < 0 || index >= array size)}
     527     *
     528     * @see JsonNumber
     529     *
     530     * @since 1.1
     531     */
     532    default JsonArrayBuilder set(int index, long value) {
     533        throw new UnsupportedOperationException();
     534    }
     535
     536    /**
     537     * Replaces a value in the array with the specified value as a
     538     * {@link JsonNumber} at the specified position.
     539     *
     540     * @param index the position in the array
     541     * @param value the number value
     542     * @return this array builder
     543     * @throws NumberFormatException if the value is Not-a-Number (NaN) or
     544     *      infinity
     545     * @throws IndexOutOfBoundsException if the index is out of range
     546     *   {@code (index < 0 || index >= array size)}
     547     *
     548     * @see JsonNumber
     549     *
     550     * @since 1.1
     551     */
     552    default JsonArrayBuilder set(int index, double value) {
     553        throw new UnsupportedOperationException();
     554    }
     555
     556    /**
     557     * Replaces a value in the array with
     558     * a {@link JsonValue#TRUE}  or {@link JsonValue#FALSE} value
     559     * at the specified position.
     560     *
     561     * @param index the position in the array
     562     * @param value the boolean value
     563     * @return this array builder
     564     * @throws IndexOutOfBoundsException if the index is out of range
     565     *   {@code (index < 0 || index >= array size)}
     566     *
     567     * @since 1.1
     568     */
     569    default JsonArrayBuilder set(int index, boolean value) {
     570        throw new UnsupportedOperationException();
     571    }
     572
     573    /**
     574     * Replaces a value in the array with
     575     * a {@link JsonValue#NULL} value at the specified position.
     576     *
     577     * @param index the position in the array
     578     * @return this array builder
     579     * @throws IndexOutOfBoundsException if the index is out of range
     580     *   {@code (index < 0 || index >= array size)}
     581     *
     582     * @since 1.1
     583     */
     584    default JsonArrayBuilder setNull(int index) {
     585        return set(index, JsonValue.NULL);
     586    }
     587
     588    /**
     589     * Replaces a value in the array with the specified value as a
     590     * {@link JsonObject} from an object builder at the specified position.
     591     *
     592     * @param index the position in the array
     593     * @param builder the object builder
     594     * @return this array builder
     595     * @throws NullPointerException if the specified builder is null
     596     * @throws IndexOutOfBoundsException if the index is out of range
     597     *   {@code (index < 0 || index >= array size)}
     598     *
     599     * @since 1.1
     600     */
     601    default JsonArrayBuilder set(int index, JsonObjectBuilder builder) {
     602        throw new UnsupportedOperationException();
     603    }
     604
     605    /**
     606     * Replaces a value in the array with the specified value as a
     607     * {@link JsonArray} from an array builder at the specified position.
     608     *
     609     * @param index the position in the array
     610     * @param builder the array builder
     611     * @return this array builder
     612     * @throws NullPointerException if the specified builder is null
     613     * @throws IndexOutOfBoundsException if the index is out of range
     614     *   {@code (index < 0 || index >= array size)}
     615     *
     616     * @since 1.1
     617     */
     618    default JsonArrayBuilder set(int index, JsonArrayBuilder builder) {
     619        throw new UnsupportedOperationException();
     620    }
     621
     622    /**
     623     * Remove the value in the array at the specified position.
     624     * Shift any subsequent values to the left (subtracts one from their
     625     * indices.
     626     *
     627     * @param index the position in the array
     628     * @return this array builder
     629     * @throws IndexOutOfBoundsException if the index is out of range
     630     *   {@code (index < 0 || index >= array size)}
     631     *
     632     * @since 1.1
     633     */
     634    default JsonArrayBuilder remove(int index) {
     635        throw new UnsupportedOperationException();
     636    }
     637
     638    /**
    209639     * Returns the current array.
    210640     *

  • trunk/src/javax/json/JsonBuilderFactory.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4141package javax.json;
    4242
     43import java.util.Collection;
    4344import java.util.Map;
    4445
    … …  
    7172 * <p> All the methods in this class are safe for use by multiple concurrent
    7273 * threads.
    73  *
    74  * @author Jitendra Kotamraju
    7574 */
    7675public interface JsonBuilderFactory {
    … …  
    8584
    8685    /**
     86     * Creates a {@code JsonObjectBuilder} instance, initialized with an object.
     87     *
     88     * @param object the initial object in the builder
     89     * @return a JSON object builder
     90     * @throws NullPointerException if specified object is {@code null}
     91     *
     92     * @since 1.1
     93     */
     94    default JsonObjectBuilder createObjectBuilder(JsonObject object) {
     95        throw new UnsupportedOperationException();
     96    }
     97
     98    /**
     99     * Creates a {@code JsonObjectBuilder} instance, initialized with the specified object.
     100     *
     101     * @param object the initial object in the builder
     102     * @return a JSON object builder
     103     * @throws NullPointerException if specified object is {@code null}
     104     *
     105     * @since 1.1
     106     */
     107    default JsonObjectBuilder createObjectBuilder(Map<String, Object> object) {
     108        throw new UnsupportedOperationException();
     109    }
     110
     111    /**
    87112     * Creates a {@code JsonArrayBuilder} instance that is used to build
    88113     * {@link JsonArray}
    … …  
    91116     */
    92117    JsonArrayBuilder createArrayBuilder();
     118
     119    /**
     120     * Creates a {@code JsonArrayBuilder} instance, initialized with an array.
     121     *
     122     * @param array the initial array in the builder
     123     * @return a JSON array builder
     124     * @throws NullPointerException if specified array is {@code null}
     125     *
     126     * @since 1.1
     127     */
     128    default JsonArrayBuilder createArrayBuilder(JsonArray array) {
     129        throw new UnsupportedOperationException();
     130    }
     131
     132    /**
     133     * Creates a {@code JsonArrayBuilder} instance,
     134     * initialized with the content of specified collection.
     135     *
     136     * @param collection the initial data for the builder
     137     * @return a JSON array builder
     138     * @throws NullPointerException if specified collection is {@code null}
     139     *
     140     * @since 1.1
     141     */
     142    default JsonArrayBuilder createArrayBuilder(Collection<?> collection) {
     143        throw new UnsupportedOperationException();
     144    }
    93145
    94146    /**

  • trunk/src/javax/json/JsonException.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4444 * <code>JsonException</code> indicates that some exception happened during
    4545 * JSON processing.
    46  *
    47  * @author Jitendra Kotamraju
    4846 */
    4947public class JsonException extends RuntimeException {

  • trunk/src/javax/json/JsonNumber.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    5151 * value internally.
    5252 * The {@code BigDecimal} object can be constructed from the following types:
    53  * {@link BigDecimal#BigDecimal(int) <code>int</code>},
    54  * {@link BigDecimal#BigDecimal(long) <code>long</code>},
    55  * {@link BigDecimal#BigDecimal(BigInteger) <code>BigInteger</code>},
    56  * {@link BigDecimal#valueOf(double) <code>double</code>}, and
    57  * {@link BigDecimal#BigDecimal(String) <code>String</code>}.
     53 * <code>int</code> {@link BigDecimal#BigDecimal(int)},
     54 * <code>long</code> {@link BigDecimal#BigDecimal(long)},
     55 * <code>BigInteger</code> {@link BigDecimal#BigDecimal(BigInteger)},
     56 * <code>double</code> {@link BigDecimal#valueOf(double)}, and
     57 * <code>String</code> {@link BigDecimal#BigDecimal(String)}.
    5858 * Some of the method semantics in this class are defined using the
    5959 * {@code BigDecimal} semantics.
    60  *
    61  * @author Jitendra Kotamraju
    6260 */
    6361public interface JsonNumber extends JsonValue {
    … …  
    138136
    139137    /**
    140      * Returns this JSON number as a {@link BigDecimal} object. This is a
     138     * Returns this JSON number as a {@link BigInteger} object. This is a
    141139     * convenience method for {@code bigDecimalValue().toBigIntegerExact()}.
    142140     *
    … …  
    167165
    168166    /**
     167     * Returns this JSON number as a {@link Number} object.
     168     *
     169     * @return a {@link Number} representation of the JSON number
     170     *
     171     * @since 1.1
     172     */
     173    default Number numberValue() {
     174        throw new UnsupportedOperationException();
     175    }
     176
     177    /**
    169178     * Returns a JSON text representation of the JSON number. The
    170179     * representation is equivalent to {@link BigDecimal#toString()}.
    … …  
    181190     * objects are <i>equal</i>
    182191     *
    183      * @param obj the object to be compared for equality with 
     192     * @param obj the object to be compared for equality with
    184193     *      this {@code JsonNumber}
    185      * @return {@code true} if the specified object is equal to this 
     194     * @return {@code true} if the specified object is equal to this
    186195     *      {@code JsonNumber}
    187196     */

  • trunk/src/javax/json/JsonObject.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    125125 * name/value pairs are added to the corresponding builder or the order
    126126 * in which name/value pairs appear in the corresponding stream.
    127  *
    128  * @author Jitendra Kotamraju
    129127 */
    130128public interface JsonObject extends JsonStructure, Map<String, JsonValue> {
    … …  
    266264     *
    267265     * @param name name whose associated value is checked
    268      * @return return true if the associated value is {@code JsonValue.NUL},
     266     * @return return true if the associated value is {@code JsonValue.NULL},
    269267     * otherwise false
    270268     * @throws NullPointerException if the specified name doesn't have any

  • trunk/src/javax/json/JsonObjectBuilder.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    6565 * way to create multiple instances.
    6666 *
    67  * <a id="JsonObjectBuilderExample1"/>
    6867 * The example code below shows how to build a {@code JsonObject} model that
    6968 * represents the following JSON object:
    … …  
    207206     * @param value value in the name/value pair
    208207     * @return this object builder
    209      * @throws NumberFormatException if the value is Not-a-Number(NaN) or
     208     * @throws NumberFormatException if the value is Not-a-Number (NaN) or
    210209     * infinity
    211210     * @throws NullPointerException if the specified name is null
    … …  
    269268
    270269    /**
     270     * Adds all name/value pairs in the JSON object associated with the specified
     271     * object builder to the JSON object associated with this object builder.
     272     * The newly added name/value pair will replace any existing name/value pair with
     273     * the same name.
     274     *
     275     * @param builder the specified object builder
     276     * @return this object builder
     277     * @throws NullPointerException if the specified builder is null
     278     * @since 1.1
     279     */
     280    default JsonObjectBuilder addAll(JsonObjectBuilder builder) {
     281        throw new UnsupportedOperationException();
     282    }
     283
     284    /**
     285     * Remove the name/value pair from the JSON object associated with this
     286     * object builder if it is present.
     287     *
     288     * @param name the name in the name/value pair to be removed
     289     * @return this object builder
     290     * @throws NullPointerException if the specified name is null
     291     * @since 1.1
     292     */
     293    default JsonObjectBuilder remove(String name) {
     294        throw new UnsupportedOperationException();
     295    }
     296
     297    /**
    271298     * Returns the JSON object associated with this object builder.
    272299     * The iteration order for the {@code JsonObject} is based

  • trunk/src/javax/json/JsonReader.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    5151 *
    5252 * <p>
    53  * <a id="JsonReaderExample1"/>
    5453 * The following example demonstrates how to read an empty JSON array from
    5554 * a string:
    … …  
    7574 * </code>
    7675 * </pre>
    77  *
    78  * @author Jitendra Kotamraju
    7976 */
    8077public interface JsonReader extends  /*Auto*/Closeable {
    … …  
    9188     * @throws javax.json.stream.JsonParsingException if a JSON object or array
    9289     *     cannot be created due to incorrect representation
    93      * @throws IllegalStateException if read, readObject, readArray or
    94      *     close method is already called
     90     * @throws IllegalStateException if read, readObject, readArray,
     91     *     readValue or close method is already called
    9592     */
    9693    JsonStructure read();
    … …  
    107104     * @throws javax.json.stream.JsonParsingException if a JSON object cannot
    108105     *     be created due to incorrect representation
    109      * @throws IllegalStateException if read, readObject, readArray or
    110      *     close method is already called
     106     * @throws IllegalStateException if read, readObject, readArray,
     107     *     readValue or close method is already called
    111108     */
    112109    JsonObject readObject();
    … …  
    123120     * @throws javax.json.stream.JsonParsingException if a JSON array cannot
    124121     *     be created due to incorrect representation
    125      * @throws IllegalStateException if read, readObject, readArray or
    126      *     close method is already called
     122     * @throws IllegalStateException if read, readObject, readArray,
     123     *     readValue or close method is already called
    127124     */
    128125    JsonArray readArray();
     126
     127    /**
     128     * Returns a JSON value that is represented in
     129     * the input source. This method needs to be called
     130     * only once for a reader instance.
     131     *
     132     * @return a JSON value
     133     * @throws JsonException if a JSON value
     134     *     be created due to i/o error (IOException would be
     135     *     cause of JsonException)
     136     * @throws javax.json.stream.JsonParsingException if a JSON value
     137     *     cannot be created due to incorrect representation
     138     * @throws IllegalStateException if read, readObject, readArray,
     139     *     readValue or close method is already called
     140     *
     141     * @since 1.1
     142     */
     143    default JsonValue readValue() {
     144        throw new UnsupportedOperationException();
     145    }
    129146
    130147    /**

  • trunk/src/javax/json/JsonReaderFactory.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    6868 * <p> All the methods in this class are safe for use by multiple concurrent
    6969 * threads.
    70  *
    71  * @author Jitendra Kotamraju
    7270 */
    7371public interface JsonReaderFactory {
    … …  
    8583     * Creates a JSON reader from a byte stream. The character encoding of
    8684     * the stream is determined as described in
    87      * <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
     85     * <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
    8886     * The reader is configured with the factory configuration.
    8987     *

  • trunk/src/javax/json/JsonString.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4343/**
    4444 * An immutable JSON string value.
    45  *
    46  * @author Jitendra Kotamraju
    4745 */
    4846public interface JsonString extends JsonValue {

  • trunk/src/javax/json/JsonStructure.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4444 * Super type for the two structured types in JSON ({@link JsonObject object}s
    4545 * and {@link JsonArray array}s).
    46  *
    47  * @author Jitendra Kotamraju
    4846 */
    4947public interface JsonStructure extends JsonValue {
     48
     49    /**
     50     * Get the value referenced by the provided JSON Pointer in the JsonStructure.
     51     *
     52     * @param jsonPointer the JSON Pointer
     53     * @return the {@code JsonValue} at the referenced location
     54     * @throws JsonException if the JSON Pointer is malformed, or if it references
     55     *     a non-existing member or value.
     56     *
     57     * @since 1.1
     58     */
     59    default public JsonValue getValue(String jsonPointer) {
     60        return Json.createPointer(jsonPointer).getValue(this);
     61    }
    5062}

  • trunk/src/javax/json/JsonValue.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4444 * <code>JsonValue</code> represents an immutable JSON value.
    4545 *
    46  * 
     46 *
    4747 * <p>A JSON value is one of the following:
    4848 * an object ({@link JsonObject}), an array ({@link JsonArray}),
    4949 * a number ({@link JsonNumber}), a string ({@link JsonString}),
    50  * {@code true} ({@link JsonValue#TRUE JsonValue.TRUE}), {@code false} 
     50 * {@code true} ({@link JsonValue#TRUE JsonValue.TRUE}), {@code false}
    5151 * ({@link JsonValue#FALSE JsonValue.FALSE}),
    5252 * or {@code null} ({@link JsonValue#NULL JsonValue.NULL}).
    53  *
    54  * @author Jitendra Kotamraju
    5553 */
    5654public interface JsonValue {
     55
     56    /**
     57     * The empty JSON object.
     58     *
     59     * @since 1.1
     60     */
     61    static final JsonObject EMPTY_JSON_OBJECT = new EmptyObject();
     62
     63    /**
     64     * The empty JSON array.
     65     *
     66     * @since 1.1
     67     */
     68    static final JsonArray EMPTY_JSON_ARRAY = new EmptyArray();
    5769
    5870    /**
    … …  
    99111     * JSON null value.
    100112     */
    101     static final JsonValue NULL = new JsonValue() {
    102         @Override
    103         public ValueType getValueType() {
    104             return ValueType.NULL;
    105         }
    106 
    107         /**
    108          * Compares the specified object with this {@link JsonValue#NULL}
    109          * object for equality. Returns {@code true} if and only if the
    110          * specified object is also a {@code JsonValue}, and their
    111          * {@link #getValueType()} objects are <i>equal</i>.
    112          *
    113          * @param obj the object to be compared for equality with this
    114          *      {@code JsonValue}
    115          * @return {@code true} if the specified object is equal to this
    116          *      {@code JsonValue}
    117          */
    118         @Override
    119         public boolean equals(Object obj) {
    120             if (obj instanceof JsonValue) {
    121                 return getValueType().equals(((JsonValue)obj).getValueType());
    122             }
    123             return false;
    124         }
    125 
    126         /**
    127          * Returns the hash code value for this {@link JsonValue#NULL} object.
    128          * The hash code of the {@link JsonValue#NULL} object is defined to be
    129          * its {@link #getValueType()} object's hash code.
    130          *
    131          * @return the hash code value for this JsonString object
    132          */
    133         @Override
    134         public int hashCode() {
    135             return ValueType.NULL.hashCode();
    136         }
    137 
    138         /**
    139          * Returns a "null" string.
    140          *
    141          * @return "null"
    142          */
    143         @Override
    144         public String toString() {
    145             return "null";
    146         }
    147     };
     113    static final JsonValue NULL = new JsonValueImpl(ValueType.NULL);
    148114
    149115    /**
    150116     * JSON true value.
    151117     */
    152     static final JsonValue TRUE = new JsonValue() {
    153         @Override
    154         public ValueType getValueType() {
    155             return ValueType.TRUE;
    156         }
    157 
    158         /**
    159          * Compares the specified object with this {@link JsonValue#TRUE}
    160          * object for equality. Returns {@code true} if and only if the
    161          * specified object is also a JsonValue, and their
    162          * {@link #getValueType()} objects are <i>equal</i>.
    163          *
    164          * @param obj the object to be compared for equality with this JsonValue.
    165          * @return {@code true} if the specified object is equal to this JsonValue.
    166          */
    167         @Override
    168         public boolean equals(Object obj) {
    169             if (obj instanceof JsonValue) {
    170                 return getValueType().equals(((JsonValue)obj).getValueType());
    171             }
    172             return false;
    173         }
    174 
    175         /**
    176          * Returns the hash code value for this {@link JsonValue#TRUE} object.
    177          * The hash code of the {@link JsonValue#TRUE} object is defined to be
    178          * its {@link #getValueType()} object's hash code.
    179          *
    180          * @return the hash code value for this JsonString object
    181          */
    182         @Override
    183         public int hashCode() {
    184             return ValueType.TRUE.hashCode();
    185         }
    186 
    187         /**
    188          * Returns "true" string
    189          *
    190          * @return "true"
    191          */
    192         @Override
    193         public String toString() {
    194             return "true";
    195         }
    196     };
     118    static final JsonValue TRUE = new JsonValueImpl(ValueType.TRUE);
    197119
    198120    /**
    199      * JSON false value
     121     * JSON false value.
    200122     */
    201     static final JsonValue FALSE = new JsonValue() {
    202         @Override
    203         public ValueType getValueType() {
    204             return ValueType.FALSE;
    205         }
    206 
    207         /**
    208          * Compares the specified object with this {@link JsonValue#FALSE}
    209          * object for equality. Returns {@code true} if and only if the
    210          * specified object is also a JsonValue, and their
    211          * {@link #getValueType()} objects are <i>equal</i>.
    212          *
    213          * @param obj the object to be compared for equality with this JsonValue
    214          * @return {@code true} if the specified object is equal to this JsonValue
    215          */
    216         @Override
    217         public boolean equals(Object obj) {
    218             if (obj instanceof JsonValue) {
    219                 return getValueType().equals(((JsonValue)obj).getValueType());
    220             }
    221             return false;
    222         }
    223 
    224         /**
    225          * Returns the hash code value for this {@link JsonValue#FALSE} object.
    226          * The hash code of the {@link JsonValue#FALSE} object is defined to be
    227          * its {@link #getValueType()} object's hash code.
    228          *
    229          * @return the hash code value for this JsonString object
    230          */
    231         @Override
    232         public int hashCode() {
    233             return ValueType.FALSE.hashCode();
    234         }
    235 
    236         /**
    237          * Returns "false" string
    238          *
    239          * @return "false"
    240          */
    241         @Override
    242         public String toString() {
    243             return "false";
    244         }
    245     };
     123    static final JsonValue FALSE = new JsonValueImpl(ValueType.FALSE);
    246124
    247125    /**
    … …  
    251129     */
    252130    ValueType getValueType();
     131
     132    /**
     133     * Return the JsonValue as a JsonObject
     134     *
     135     * @return the JsonValue as a JsonObject
     136     * @throws ClassCastException if the JsonValue is not a JsonObject
     137     *
     138     * @since 1.1
     139     */
     140    default JsonObject asJsonObject() {
     141        return JsonObject.class.cast(this);
     142    }
     143
     144    /**
     145     * Return the JsonValue as a JsonArray
     146     *
     147     * @return the JsonValue as a JsonArray
     148     * @throws ClassCastException if the JsonValue is not a JsonArray
     149     *
     150     * @since 1.1
     151     */
     152    default JsonArray asJsonArray() {
     153        return JsonArray.class.cast(this);
     154    }
    253155
    254156    /**

  • trunk/src/javax/json/JsonWriter.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    5151 *
    5252 * <p>
    53  * <a id="JsonWriterExample1"/>
    5453 * The following example demonstrates how write an empty JSON object:
    5554 * <pre>
    … …  
    7473 * </code>
    7574 * </pre>
    76  *
    77  * @author Jitendra Kotamraju
    7875 */
    7976public interface JsonWriter extends  /*Auto*/Closeable {
    … …  
    126123     * cause of JsonException)
    127124     */
     125
     126    /**
     127     * Writes the specified {@link JsonValue} to the output source.
     128     * method needs to be called only once for a write instance.
     129     *
     130     * @param value a {@code JsonValue} to be written to the output
     131     *              source
     132     * @throws JsonException if the specified JSON object cannot be
     133     *     written due to i/o error (IOException would be cause of
     134     *     JsonException)
     135     * @throws IllegalStateException if writeArray, writeObject, write
     136     *     or close method is already called
     137     *
     138     * @since 1.1
     139     */
     140    default void write(JsonValue value) {
     141        throw new UnsupportedOperationException();
     142    }
     143
    128144    @Override
    129145    void close();

  • trunk/src/javax/json/JsonWriterFactory.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    6868 * <p> All the methods in this class are safe for use by multiple concurrent
    6969 * threads.
    70  *
    71  * @author Jitendra Kotamraju
    7270 */
    7371public interface JsonWriterFactory {

  • trunk/src/javax/json/package-info.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    5151 * ordered sequence of zero or more values from the model.
    5252 *
    53  * <p>The object model API uses builder patterns to create these object models.
    54  * The classes {@link javax.json.JsonObjectBuilder} and
    55  * {@link javax.json.JsonArrayBuilder} provide methods to create models
     53 * <p>The object model API uses builder patterns to create and modify
     54 * these object models. The classes {@link javax.json.JsonObjectBuilder} and
     55 * {@link javax.json.JsonArrayBuilder} provide methods to create and modify models
    5656 * of type {@code JsonObject} and {@code JsonArray} respectively.
    5757 *
    … …  
    5959 * the class {@link javax.json.JsonReader}. Similarly, these object models
    6060 * can be written to an output source using the class {@link javax.json.JsonWriter}.
    61  *
    62  * @since JSON Processing 1.0
    63  * @author Jitendra Kotamraju
     61 * <p>
     62 * This package includes several classes that implement other JSON related
     63 * standards: <a href="http://tools.ietf.org/html/rfc6901">JSON Pointer</a>,
     64 * <a Href="http://tools.ietf.org/html/rfc6902">JSON Patch</a>, and
     65 * <a Href="http://tools.ietf.org/html/rfc7396">JSON Merge Patch</a>.
     66 * They can be used to retrieve, transform or manipulate values in an
     67 * object model.
    6468 */
    6569package javax.json;

  • trunk/src/javax/json/spi/JsonProvider.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    5050import java.io.Reader;
    5151import java.io.Writer;
     52import java.util.Collection;
    5253import java.util.Iterator;
    5354import java.util.Map;
    5455import java.util.ServiceLoader;
     56import java.math.BigDecimal;
     57import java.math.BigInteger;
     58import java.util.Optional;
    5559
    5660/**
    … …  
    6165 *
    6266 * @see ServiceLoader
    63  * @author Jitendra Kotamraju
    6467 */
    6568public abstract class JsonProvider {
    … …  
    7679
    7780    /**
    78      *
    7981     * Creates a JSON provider object. The provider is loaded using the
    8082     * {@link ServiceLoader#load(Class)} method. If there are no available
    8183     * service providers, this method returns the default service provider.
     84     * Users are recommended to cache the result of this method.
    8285     *
    8386     * @see ServiceLoader
    … …  
    9093            return it.next();
    9194        }
    92 
    9395        try {
    9496            Class<?> clazz = Class.forName(DEFAULT_PROVIDER);
    95             return (JsonProvider)clazz.newInstance();
     97            return (JsonProvider) clazz.newInstance();
    9698        } catch (ClassNotFoundException x) {
    9799            throw new JsonException(
    … …  
    115117     * Creates a JSON parser from the specified byte stream.
    116118     * The character encoding of the stream is determined
    117      * as defined in <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627
     119     * as defined in <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159
    118120     * </a>.
    119121     *
    … …  
    193195     * Creates a JSON reader from a byte stream. The character encoding of
    194196     * the stream is determined as described in
    195      * <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
     197     * <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
    196198     *
    197199     * @param in a byte stream from which JSON is to be read
    … …  
    246248
    247249    /**
    248      * Creates a JSON object builder
     250     * Creates a JSON object builder.
    249251     *
    250252     * @return a JSON object builder
    … …  
    253255
    254256    /**
    255      * Creates a JSON array builder
     257     * Creates a JSON object builder, initialized with the specified object.
     258     *
     259     * @param object the initial JSON object in the builder
     260     * @return a JSON object builder
     261     *
     262     * @since 1.1
     263     */
     264    public JsonObjectBuilder createObjectBuilder(JsonObject object) {
     265        throw new UnsupportedOperationException();
     266    }
     267
     268    /**
     269     * Creates a JSON object builder, initialized with the data from specified {@code map}.
     270     * If the @{code map} contains {@link Optional}s then resulting JSON object builder
     271     * contains the key from the {@code map} only if the {@link Optional} is not empty.
     272     *
     273     * @param map the initial object in the builder
     274     * @return a JSON object builder
     275     * @exception IllegalArgumentException if the value from the {@code map} cannot be converted
     276     *            to the corresponding {@link JsonValue}
     277     *
     278     * @since 1.1
     279     */
     280    public JsonObjectBuilder createObjectBuilder(Map<String, Object> map) {
     281        throw new UnsupportedOperationException();
     282    }
     283
     284    /**
     285     * Creates a JSON array builder.
    256286     *
    257287     * @return a JSON array builder
    258288     */
    259289    public abstract JsonArrayBuilder createArrayBuilder();
     290
     291    /**
     292     * Creates a JSON array builder, initialized with the specified array.
     293     *
     294     * @param array the initial JSON array in the builder
     295     * @return a JSON array builder
     296     *
     297     * @since 1.1
     298     */
     299    public JsonArrayBuilder createArrayBuilder(JsonArray array) {
     300        throw new UnsupportedOperationException();
     301    }
     302
     303    /**
     304     * Creates JSON Pointer (<a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>)
     305     * from given {@code jsonPointer} string.
     306     * <ul>
     307     *     <li>An empty {@code jsonPointer} string defines a reference to the target itself.</li>
     308     *     <li>If the {@code jsonPointer} string is non-empty, it must be a sequence of '{@code /}' prefixed tokens.</li>
     309     * </ul>
     310     *
     311     * @param jsonPointer the JSON Pointer string
     312     * @throws NullPointerException if {@code jsonPointer} is {@code null}
     313     * @throws JsonException if {@code jsonPointer} is not a valid JSON Pointer
     314     * @return a JSON Pointer
     315     *
     316     * @since 1.1
     317     */
     318    public JsonPointer createPointer(String jsonPointer) {
     319        throw new UnsupportedOperationException();
     320    }
     321
     322    /**
     323     * Creates a JSON Patch builder (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>).
     324     *
     325     * @return a JSON Patch builder
     326     *
     327     * @since 1.1
     328     */
     329    public JsonPatchBuilder createPatchBuilder() {
     330        throw new UnsupportedOperationException();
     331    }
     332
     333    /**
     334     * Creates a JSON Patch builder
     335     * (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>),
     336     * initialized with the specified operations.
     337     *
     338     * @param array the initial patch operations
     339     * @return a JSON Patch builder
     340     *
     341     * @since 1.1
     342     */
     343    public JsonPatchBuilder createPatchBuilder(JsonArray array) {
     344        throw new UnsupportedOperationException();
     345    }
     346
     347    /**
     348     * Creates a JSON Patch (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>)
     349     * from the specified operations.
     350     *
     351     * @param array patch operations
     352     * @return a JSON Patch
     353     *
     354     * @since 1.1
     355     */
     356    public JsonPatch createPatch(JsonArray array) {
     357        throw new UnsupportedOperationException();
     358    }
     359
     360    /**
     361     * Generates a JSON Patch (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>)
     362     * from the source and target {@code JsonStructure}.
     363     * The generated JSON Patch need not be unique.
     364     *
     365     * @param source the source
     366     * @param target the target, must be the same type as the source
     367     * @return a JSON Patch which when applied to the source, yields the target
     368     *
     369     * @since 1.1
     370     */
     371    public JsonPatch createDiff(JsonStructure source, JsonStructure target) {
     372        throw new UnsupportedOperationException();
     373    }
     374
     375    /**
     376     * Creates JSON Merge Patch (<a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>)
     377     * from specified {@code JsonValue}.
     378     *
     379     * @param patch the patch
     380     * @return a JSON Merge Patch
     381     *
     382     * @since 1.1
     383     */
     384    public JsonMergePatch createMergePatch(JsonValue patch) {
     385        throw new UnsupportedOperationException();
     386    }
     387
     388    /**
     389     * Generates a JSON Merge Patch (<a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>)
     390     * from the source and target {@code JsonValue}s
     391     * which when applied to the {@code source}, yields the {@code target}.
     392     *
     393     * @param source the source
     394     * @param target the target
     395     * @return a JSON Merge Patch
     396     *
     397     * @since 1.1
     398     */
     399    public JsonMergePatch createMergeDiff(JsonValue source, JsonValue target) {
     400        throw new UnsupportedOperationException();
     401    }
     402
     403    /**
     404     * Creates a JSON array builder, initialized with the content of specified {@code collection}.
     405     * If the @{code collection} contains {@link Optional}s then resulting JSON array builder
     406     * contains the value from the {@code collection} only if the {@link Optional} is not empty.
     407     *
     408     * @param collection the initial data for the builder
     409     * @return a JSON array builder
     410     * @exception IllegalArgumentException if the value from the {@code collection} cannot be converted
     411     *            to the corresponding {@link JsonValue}
     412     *
     413     * @since 1.1
     414     */
     415    public JsonArrayBuilder createArrayBuilder(Collection<?> collection) {
     416        throw new UnsupportedOperationException();
     417    }
     418
    260419
    261420    /**
    … …  
    272431    public abstract JsonBuilderFactory createBuilderFactory(Map<String,?> config);
    273432
     433    /**
     434     * Creates a JsonString.
     435     *
     436     * @param value a JSON string
     437     * @return the JsonString for the string
     438     *
     439     * @since 1.1
     440     */
     441    public JsonString createValue(String value) {
     442        throw new UnsupportedOperationException();
     443    }
     444
     445    /**
     446     * Creates a JsonNumber.
     447     *
     448     * @param value a JSON number
     449     * @return the JsonNumber for the number
     450     *
     451     * @since 1.1
     452     */
     453    public JsonNumber createValue(int value) {
     454        throw new UnsupportedOperationException();
     455    }
     456
     457    /**
     458     * Creates a JsonNumber.
     459     *
     460     * @param value a JSON number
     461     * @return the JsonNumber for the number
     462     *
     463     * @since 1.1
     464     */
     465    public JsonNumber createValue(long value) {
     466        throw new UnsupportedOperationException();
     467    }
     468
     469    /**
     470     * Creates a JsonNumber.
     471     *
     472     * @param value a JSON number
     473     * @return the JsonNumber for the number
     474     *
     475     * @since 1.1
     476     */
     477    public JsonNumber createValue(double value) {
     478        throw new UnsupportedOperationException();
     479    }
     480
     481    /**
     482     * Creates a JsonNumber.
     483     *
     484     * @param value a JSON number
     485     * @return the JsonNumber for the number
     486     *
     487     * @since 1.1
     488     */
     489    public JsonNumber createValue(BigDecimal value) {
     490        throw new UnsupportedOperationException();
     491    }
     492
     493    /**
     494     * Creates a JsonNumber.
     495     *
     496     * @param value a JSON number
     497     * @return the JsonNumber for the number
     498     *
     499     * @since 1.1
     500     */
     501    public JsonNumber createValue(BigInteger value) {
     502        throw new UnsupportedOperationException();
     503    }
    274504}

  • trunk/src/javax/json/spi/package-info.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    5353 *
    5454 * @since JSON Processing 1.0
    55  * @author Jitendra Kotamraju
    5655 */
    5756package javax.json.spi;

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

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4646 * {@code JsonGenerationException} indicates an incorrect JSON is
    4747 * being generated.
    48  *
    49  * @author Jitendra Kotamraju
    5048 */
    5149public class JsonGenerationException extends JsonException {

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

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

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

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    6767 * <p> All the methods in this class are safe for use by multiple concurrent
    6868 * threads.
    69  *
    70  * @author Jitendra Kotamraju
    7169 */
    7270public interface JsonGeneratorFactory {
    … …  
    7775     *
    7876     * @param writer i/o writer to which JSON is written
     77     * @return the created JSON generator
    7978     */
    8079    JsonGenerator createGenerator(Writer writer);
    … …  
    8685     *
    8786     * @param out i/o stream to which JSON is written
     87     * @return the created JSON generator
    8888     */
    8989    JsonGenerator createGenerator(OutputStream out);
    … …  
    9696     * @param out i/o stream to which JSON is written
    9797     * @param charset a charset
     98     * @return the created JSON generator
    9899     */
    99100    JsonGenerator createGenerator(OutputStream out, Charset charset);

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

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    5252 * {@link javax.json.JsonArray JsonArray} input source, all the methods in
    5353 * this class return -1.
    54  *
    55  * @author Jitendra Kotamraju
    5654 * @see JsonParser
    5755 * @see JsonParsingException
    … …  
    6058
    6159    /**
    62      * Return the line number for the current JSON event in the input source.
     60     * Return the line number (starts with 1 for the first line) for the current JSON event in the input source.
    6361     *
    64      * @return the line number or -1 if none is available
     62     * @return the line number (starts with 1 for the first line) or -1 if none is available
    6563     */
    6664    long getLineNumber();
    6765
    6866    /**
    69      * Return the column number for the current JSON event in the input source.
     67     * Return the column number (starts with 1 for the first column) for the current JSON event in the input source.
    7068     *
    71      * @return the column number or -1 if none is available
     69     * @return the column number (starts with 1 for the first column) or -1 if none is available
    7270     */
    7371    long getColumnNumber();

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

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4444import java.io.Closeable;
    4545import java.math.BigDecimal;
     46import java.util.stream.Stream;
     47import java.util.Map;
     48
     49import javax.json.JsonValue;
     50import javax.json.JsonObject;
     51import javax.json.JsonArray;
    4652
    4753/**
    4854 * Provides forward, read-only access to JSON data in a streaming way. This
    49  * is the most efficient way for reading JSON data. The class
     55 * is the most efficient way for reading JSON data.
     56 * This is the only way to parse and process JSON data that are too big to be loaded in memory.
     57 * <p>The class
    5058 * {@link javax.json.Json} contains methods to create parsers from input
    5159 * sources ({@link java.io.InputStream} and {@link java.io.Reader}).
    … …  
    97105 *
    98106 * <p>
    99  * <a id="JsonParserExample2"/>
    100  * <p>
    101107 * <b>For example</b>, for the following JSON:
    102108 * <pre>
    … …  
    113119 * locations below (marked in bold):
    114120 *
    115  * <p>
    116121 * <pre>
    117122 * {<B>START_OBJECT</B>
    … …  
    124129 * </pre>
    125130 *
    126  * <p>
    127  * The methods {@code next()} and {@code hasNext()} enable iteration over
     131 * The methods {@link #next()} and {@link #hasNext()} enable iteration over
    128132 * parser events to process JSON data. {@code JsonParser} provides get methods
    129133 * to obtain the value at the current state of the parser. For example, the
    130134 * following code shows how to obtain the value "John" from the JSON above:
    131135 *
    132  * <p>
    133136 * <pre>
    134137 * <code>
    … …  
    140143 * </pre>
    141144 *
     145 * Starting in version 1.1, it is possible to build a partial JSON object
     146 * model from the stream, at the current parser position.
     147 * The methods {@link #getArray} and {@link #getObject} can be used to read in
     148 * a {@code JsonArray} or {@code JsonObject}.  For example, the following code
     149 * shows how to obtain the phoneNumber in a JsonArray, from the JSON above:
     150 *
     151 * <pre><code>
     152 * while (parser.hasNext() {
     153 *     Event event = parser.next();
     154 *     if (event == JsonParser.Event.KEY_NAME ) {
     155 *         String key = getString();
     156 *         event = parser.next();
     157 *         if (key.equals("phoneNumber") {
     158 *             JsonArray phones = parser.getArray();
     159 *         }
     160 *     }
     161 * }
     162 * </code></pre>
     163 *
     164 * The methods {@link #getArrayStream} and {@link #getObjectStream} can be used
     165 * to get a stream of the elements of a {@code JsonArray} or {@code JsonObject}.
     166 * For example, the following code shows another way to obtain John's phoneNumber
     167 * in a {@code JsonArray} :
     168 *
     169 * <pre>{@code
     170 * Event event = parser.next(); // START_OBJECT
     171 * JsonArray phones = (JsonArray)
     172 *     parser.getObjectStream().filter(e->e.getKey().equals("phoneNumber"))
     173 *                             .map(e->e.getValue())
     174 *                             .findFirst()
     175 *                             .get();
     176 * }</pre>
     177 *
     178 * The methods {@link #skipArray} and {@link #skipObject} can be used to
     179 * skip tokens and position the parser to {@code END_ARRAY} or
     180 * {@code END_OBJECT}.
     181 * <p>
     182 * {@code JsonParser} can be used to parse sequence of JSON values that are not
     183 * enclosed in a JSON array, e.g. { } { }. The following code demonstrates how
     184 * to parse such sequence.
     185 * <pre><code>
     186 * JsonParser parser = Json.createParser(...);
     187 * while (parser.hasNext) {
     188 *     parser.next(); // advance parser state
     189 *     JsonValue value = parser.getValue();
     190 * }
     191 * </code></pre>
     192 *
    142193 * @see javax.json.Json
    143194 * @see JsonParserFactory
    144  * @author Jitendra Kotamraju
    145195 */
    146196public interface JsonParser extends /*Auto*/Closeable {
    … …  
    223273     * @throws java.util.NoSuchElementException if there are no more parsing
    224274     * states.
     275     * @return the event for the next parsing state
    225276     */
    226277    Event next();
    … …  
    319370
    320371    /**
    321      * getJsonValue(JsonObject.class) is valid in the START_OBJECT state and
    322      * moves the cursor to END_OBJECT.
    323      *
    324      * getJsonValue(JsonArray.class) is valid in the START_ARRAY state
    325      * and moves the cursor to END_ARRAY.
    326      *
    327      * getJsonValue(JsonString.class) is valid in the VALUE_STRING state.
    328      *
    329      * getJsonValue(JsonNumber.class) is valid in the VALUE_NUMBER state.
    330      *
    331      * @param clazz
    332      * @return
    333      *
    334     public <T extends JsonValue> T getJsonValue(Class<T> clazz);
    335      */
     372     * Returns a {@code JsonObject} and advances the parser to the
     373     * corresponding {@code END_OBJECT}.
     374     *
     375     * @return the {@code JsonObject} at the current parser position
     376     *
     377     * @throws IllegalStateException when the parser state is not
     378     *     {@code START_OBJECT}
     379     *
     380     * @since 1.1
     381     */
     382    default public JsonObject getObject() {
     383        throw new UnsupportedOperationException();
     384    }
     385
     386    /**
     387     * Returns a {@code JsonValue} at the current parser position.
     388     * If the parser state is {@code START_ARRAY}, the behavior is
     389     * the same as {@link #getArray}. If the parser state is
     390     * {@code START_OBJECT}, the behavior is the same as
     391     * {@link #getObject}. For all other cases, if applicable, the JSON value is
     392     * read and returned.
     393     *
     394     * @return the {@code JsonValue} at the current parser position.
     395     * @throws IllegalStateException when the parser state is
     396     *     {@code END_OBJECT} or {@code END_ARRAY}
     397     *
     398     * @since 1.1
     399     */
     400    default public JsonValue getValue() {
     401        throw new UnsupportedOperationException();
     402    }
     403
     404    /**
     405     * Returns a {@code JsonArray} and advance the parser to the
     406     * the corresponding {@code END_ARRAY}.
     407     *
     408     * @return the {@code JsonArray} at the current parser position
     409     *
     410     * @throws IllegalStateException when the parser state is not
     411     *     {@code START_ARRAY}
     412     *
     413     * @since 1.1
     414     */
     415    default public JsonArray getArray() {
     416        throw new UnsupportedOperationException();
     417    }
     418
     419    /**
     420     * Returns a stream of the {@code JsonArray} elements.
     421     * The parser state must be {@code START_ARRAY}.
     422     * The elements are read lazily, on an as-needed basis, as
     423     * required by the stream operations.
     424     * If the stream operations do not consume
     425     * all of the array elements, {@link skipArray} can be used to
     426     * skip the unprocessed array elements.
     427     *
     428     * @return a stream of elements of the {@code JsonArray}
     429     *
     430     * @throws IllegalStateException when the parser state is not
     431     *     {@code START_ARRAY}
     432     *
     433     * @since 1.1
     434     */
     435    default public Stream<JsonValue> getArrayStream() {
     436        throw new UnsupportedOperationException();
     437    }
     438
     439    /**
     440     * Returns a stream of the {@code JsonObject}'s
     441     * name/value pairs. The parser state must be {@code START_OBJECT}.
     442     * The name/value pairs are read lazily, on an as-needed basis, as
     443     * required by the stream operations.
     444     * If the stream operations do not consume
     445     * all of the object's name/value pairs, {@link skipObject} can be
     446     * used to skip the unprocessed elements.
     447     *
     448     * @return a stream of name/value pairs of the {@code JsonObject}
     449     *
     450     * @throws IllegalStateException when the parser state is not
     451     *     {@code START_OBJECT}
     452     *
     453     * @since 1.1
     454     */
     455    default public Stream<Map.Entry<String,JsonValue>> getObjectStream() {
     456        throw new UnsupportedOperationException();
     457    }
     458
     459    /**
     460     * Returns a stream of {@code JsonValue} from a sequence of
     461     * JSON values. The values are read lazily, on an as-needed basis,
     462     * as needed by the stream operations.
     463     *
     464     * @return a Stream of {@code JsonValue}
     465     *
     466     * @throws IllegalStateException if the parser is in an array or object.
     467     *
     468     * @since 1.1
     469     */
     470    default public Stream<JsonValue> getValueStream() {
     471        throw new UnsupportedOperationException();
     472    }
     473
     474    /**
     475     * Advance the parser to {@code END_ARRAY}.
     476     * If the parser is in array context, i.e. it has previously
     477     * encountered a {@code START_ARRAY} without encountering the
     478     * corresponding {@code END_ARRAY}, the parser is advanced to
     479     * the corresponding {@code END_ARRAY}.
     480     * If the parser is not in any array context, nothing happens.
     481     *
     482     * @since 1.1
     483     */
     484    default public void skipArray() {
     485        throw new UnsupportedOperationException();
     486    }
     487
     488    /**
     489     * Advance the parser to {@code END_OBJECT}.
     490     * If the parser is in object context, i.e. it has previously
     491     * encountered a {@code START_OBJECT} without encountering the
     492     * corresponding {@code END_OBJECT}, the parser is advanced to
     493     * the corresponding {@code END_OBJECT}.
     494     * If the parser is not in any object context, nothing happens.
     495     *
     496     * @since 1.1
     497     */
     498    default public void skipObject() {
     499        throw new UnsupportedOperationException();
     500    }
    336501
    337502    /**
    … …  
    344509    @Override
    345510    void close();
    346 
    347511}

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

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    6969 * <p> All the methods in this class are safe for use by multiple concurrent
    7070 * threads.
    71  *
    72  * @author Jitendra Kotamraju
    7371 */
    7472public interface JsonParserFactory {
    … …  
    7876     *
    7977     * @param reader a i/o reader from which JSON is to be read
     78     * @return the created JSON parser
    8079     */
    8180    JsonParser createParser(Reader reader);
    … …  
    8483     * Creates a JSON parser from the specified byte stream.
    8584     * The character encoding of the stream is determined
    86      * as specified in <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
     85     * as specified in <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
    8786     *
    8887     * @param in i/o stream from which JSON is to be read
     88     * @return the created JSON parser
    8989     * @throws javax.json.JsonException if encoding cannot be determined
    9090     *         or i/o error (IOException would be cause of JsonException)
    … …  
    9999     * @param in i/o stream from which JSON is to be read
    100100     * @param charset a charset
     101     * @return the created JSON parser
    101102     */
    102103    JsonParser createParser(InputStream in, Charset charset);
    … …  
    106107     *
    107108     * @param obj a JSON object
     109     * @return the created JSON parser
    108110     */
    109111    JsonParser createParser(JsonObject obj);
    … …  
    113115     *
    114116     * @param array a JSON array
     117     * @return the created JSON parser
    115118     */
    116119    JsonParser createParser(JsonArray array);

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

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    4646 * {@code JsonParsingException} is used when an incorrect JSON is
    4747 * being parsed.
    48  *
    49  * @author Jitendra Kotamraju
    5048 */
    5149public class JsonParsingException extends JsonException {

  • trunk/src/javax/json/stream/package-info.java

    r6756 r13231  
    22 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    33 *
    4  * Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
     4 * Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
    55 *
    66 * The contents of this file are subject to the terms of either the GNU
    … …  
    99 * may not use this file except in compliance with the License.  You can
    1010 * obtain a copy of the License at
    11  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
    12  * or packager/legal/LICENSE.txt.  See the License for the specific
     11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
     12 * or LICENSE.txt.  See the License for the specific
    1313 * language governing permissions and limitations under the License.
    1414 *
    1515 * When distributing the software, include this License Header Notice in each
    16  * file and include the License file at packager/legal/LICENSE.txt.
     16 * file and include the License file at LICENSE.txt.
    1717 *
    1818 * GPL Classpath Exception:
    … …  
    6868 *
    6969 * @since JSON Processing 1.0
    70  * @author Jitendra Kotamraju
    7170 */
    7271package javax.json.stream;
Note: See TracChangeset for help on using the changeset viewer.