Skip to content
Commits on Source (11)
Expand all Show whitespace changes
Inline Side-by-side
.gitignore 0 → 100644
View file @ b2351df6
#Maven noise
target/
#OSX noise
.DS_Store
#IntelliJ Idea noise
.idea
*.iws
*.ipr
*.iml
#Eclipse noise
.settings/
.classpath
.project
#NetBeans noise
nbproject/
#Java noise
*.class
api/doc
*err_pid*.log
CONTRIBUTING.md 0 → 100644
View file @ b2351df6
---
---
# Source Code Submissions
We welcome your contributions and look forward to collaborating with you. We can only accept source code repository
submissions from users who have signed and returned the Oracle
Contributor Agreement. You will find details and the agreement to sign at this OTN web page:
[Oracle Contributor Agreement](http://www.oracle.com/technetwork/community/oca-486395.html).
# Other Contributions
For all project Submissions other than source code repository contributions, the following also applies: Oracle does
not claim ownership of Your Submissions. However, in order to fulfill
the purposes of this project, You must give Oracle and all Users
the right to post, access, discuss, use, publish, disseminate, and refine
Your Submissions.
In legalese: *You hereby grant to Oracle and all
Users a royalty-free, perpetual, irrevocable, worldwide, non-exclusive,
and fully sub-licensable right and license, under Your intellectual
property rights, to reproduce, modify, adapt, publish, translate, create
derivative works from, distribute, perform, display, and use Your
Submissions (in whole or part) and to incorporate or implement them in
other works in any form, media, or technology now known or later
developed, all subject to the obligation to retain any copyright notices
included in Your Submissions. All Users, Oracle, and their
sublicensees are responsible for any modifications they make to the
Submissions of others.*
Copyright © 2017 Oracle and/or its affiliates. All rights reserved.
LICENSE.txt 0 → 100644
View file @ b2351df6
This diff is collapsed.
README.md 0 → 100644
View file @ b2351df6
# JSON Processing (JSON-P)
This projects contains API and Reference Implementation (RI) of JSR-374.
The Java API for JSON Processing provides portable APIs to parse, generate, transform, and query JSON documents.
## Build
Use the following command:
```bash
mvn -U -C clean install -Dnon.final=true
```
## Licensing
### JSON-P API
[Java API for JSON Processing 1.1 specification license](https://jcp.org/aboutJava/communityprocess/licenses/jsr374/JSR_374-Spec-Java_API_for_JSON_Proc-1.1-11.25.14.pdf)
### JSON-P RI
Commercial use:
The RI will be available for commercial use under the [CDDL 1.1](https://oss.oracle.com/licenses/CDDL+GPL-1.1) open source license, the [GPLv2 with Classpath Exception](https://oss.oracle.com/licenses/CDDL+GPL-1.1) open source license, or this [license](https://jcp.org/aboutJava/communityprocess/licenses/jsr374/OCSL-JSR_374-Java_API_for_JSON_Processing-1.1-AttachD-11.25.14.pdf).
Non-Commercial use:
The RI will be available for non-Commercial use under the [CDDL 1.1](https://oss.oracle.com/licenses/CDDL+GPL-1.1) open source license or the [GPLv2 with Classpath Exception](https://oss.oracle.com/licenses/CDDL+GPL-1.1) open source license.
## Links
- JSON-P official web site: https://javaee.github.io/jsonp
- JSR-374 page on JCP site: https://jcp.org/en/jsr/detail?id=374
\ No newline at end of file
api/pom.xml
View file @ b2351df6
......@@ -3,19 +3,19 @@
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
The contents of this file are subject to the terms of either the GNU
General Public License Version 2 only ("GPL") or the Common Development
and Distribution License("CDDL") (collectively, the "License"). You
may not use this file except in compliance with the License. You can
obtain a copy of the License at
https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
or packager/legal/LICENSE.txt. See the License for the specific
https://oss.oracle.com/licenses/CDDL+GPL-1.1
or LICENSE.txt. See the License for the specific
language governing permissions and limitations under the License.
When distributing the software, include this License Header Notice in each
file and include the License file at packager/legal/LICENSE.txt.
file and include the License file at LICENSE.txt.
GPL Classpath Exception:
Oracle designates this particular file as subject to the "Classpath"
......@@ -47,17 +47,22 @@
<parent>
<groupId>org.glassfish</groupId>
<artifactId>json</artifactId>
<version>1.0.2</version>
<version>1.1.2</version>
<relativePath>../pom.xml</relativePath>
</parent>
<groupId>javax.json</groupId>
<artifactId>javax.json-api</artifactId>
<packaging>bundle</packaging>
<version>1.0</version>
<name>JSR 353 (JSON Processing) API</name>
<description>API module of JSR 353:Java API for Processing JSON</description>
<url>http://json-processing-spec.java.net</url>
<version>1.1.2</version>
<name>JSR 374 (JSON Processing) API</name>
<description>API module of JSR 374:Java API for Processing JSON</description>
<url>https://javaee.github.io/jsonp</url>
<properties>
<packages.export>javax.json.*</packages.export>
</properties>
<build>
<plugins>
<plugin>
......@@ -68,6 +73,7 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<docfilessubdirs>true</docfilessubdirs>
<groups>
<group>
<title>JSON Processing Packages</title>
......@@ -75,16 +81,16 @@
</group>
</groups>
<bottom>
<![CDATA[Copyright &#169; 2012-2013,
<![CDATA[Copyright &#169; 2012-2017,
<a href="http://www.oracle.com">Oracle</a>
and/or its affiliates. All Rights Reserved.
Use is subject to
<a href="{@docRoot}/doc-files/speclicense.html" target="_top">license terms</a>.
<br>Comments to : users@json-processing-spec.java.net
<br>Comments to : jsonp-spec@javaee.groups.io
]]>
</bottom>
<links>
<link>http://docs.oracle.com/javase/6/docs/api/</link>
<link>http://docs.oracle.com/javase/8/docs/api/</link>
</links>
</configuration>
......@@ -102,10 +108,11 @@
<artifactId>spec-version-maven-plugin</artifactId>
<configuration>
<spec>
<nonFinal>false</nonFinal>
<nonFinal>${non.final}</nonFinal>
<jarType>api</jarType>
<specVersion>${spec_version}</specVersion>
<specImplVersion>${spec_impl_version}</specImplVersion>
<specImplVersion>${new_spec_impl_version}</specImplVersion>
<newSpecVersion>${new_spec_version}</newSpecVersion>
<apiPackage>${api_package}</apiPackage>
</spec>
</configuration>
......@@ -136,6 +143,7 @@
<Implementation-Version>${spec.implementation.version}</Implementation-Version>
<Specification-Version>${spec.specification.version}</Specification-Version>
<Export-Package>${packages.export}</Export-Package>
<Bundle-Description>Java API for JSON Processing (JSON-P) ${spec_version}</Bundle-Description>
</instructions>
</configuration>
</plugin>
......
api/src/main/java/javax/json/EmptyArray.java 0 → 100644
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.json;
import java.io.Serializable;
import java.util.AbstractList;
import java.util.Collections;
import java.util.List;
import java.util.RandomAccess;
/**
* Private implementation of immutable {@link JsonArray}.
*
* @author Lukas Jungmann
*/
final class EmptyArray extends AbstractList<JsonValue> implements JsonArray, Serializable, RandomAccess {
private static final long serialVersionUID = 7295439472061642859L;
@Override
public JsonValue get(int index) {
throw new IndexOutOfBoundsException("Index: " + index);
}
@Override
public int size() {
return 0;
}
@Override
public JsonObject getJsonObject(int index) {
return (JsonObject) get(index);
}
@Override
public JsonArray getJsonArray(int index) {
return (JsonArray) get(index);
}
@Override
public JsonNumber getJsonNumber(int index) {
return (JsonNumber) get(index);
}
@Override
public JsonString getJsonString(int index) {
return (JsonString) get(index);
}
@Override
public <T extends JsonValue> List<T> getValuesAs(Class<T> clazz) {
return Collections.emptyList();
}
@Override
public String getString(int index) {
return getJsonString(index).getString();
}
@Override
public String getString(int index, String defaultValue) {
return defaultValue;
}
@Override
public int getInt(int index) {
return getJsonNumber(index).intValue();
}
@Override
public int getInt(int index, int defaultValue) {
return defaultValue;
}
@Override
public boolean getBoolean(int index) {
return get(index) == JsonValue.TRUE;
}
@Override
public boolean getBoolean(int index, boolean defaultValue) {
return defaultValue;
}
@Override
public boolean isNull(int index) {
return get(index) == JsonValue.NULL;
}
@Override
public ValueType getValueType() {
return ValueType.ARRAY;
}
// Preserves singleton property
private Object readResolve() {
return JsonValue.EMPTY_JSON_ARRAY;
}
}
api/src/main/java/javax/json/EmptyObject.java 0 → 100644
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.json;
import java.io.Serializable;
import java.util.AbstractMap;
import java.util.Collections;
import java.util.Set;
/**
* Private implementation of immutable {@link JsonObject}.
*
* @author Lukas Jungmann
*/
final class EmptyObject extends AbstractMap<String, JsonValue> implements JsonObject, Serializable {
private static final long serialVersionUID = -1461653546889072583L;
@Override
public Set<Entry<String, JsonValue>> entrySet() {
return Collections.<Entry<String, JsonValue>>emptySet();
}
@Override
public JsonArray getJsonArray(String name) {
return (JsonArray) get(name);
}
@Override
public JsonObject getJsonObject(String name) {
return (JsonObject) get(name);
}
@Override
public JsonNumber getJsonNumber(String name) {
return (JsonNumber) get(name);
}
@Override
public JsonString getJsonString(String name) {
return (JsonString) get(name);
}
@Override
public String getString(String name) {
return getJsonString(name).getString();
}
@Override
public String getString(String name, String defaultValue) {
return defaultValue;
}
@Override
public int getInt(String name) {
return getJsonNumber(name).intValue();
}
@Override
public int getInt(String name, int defaultValue) {
return defaultValue;
}
@Override
public boolean getBoolean(String name) {
throw new NullPointerException();
}
@Override
public boolean getBoolean(String name, boolean defaultValue) {
return defaultValue;
}
@Override
public boolean isNull(String name) {
throw new NullPointerException();
}
@Override
public ValueType getValueType() {
return ValueType.OBJECT;
}
// Preserves singleton property
private Object readResolve() {
return JsonValue.EMPTY_JSON_OBJECT;
}
}
api/src/main/java/javax/json/Json.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -40,13 +40,20 @@
package javax.json;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Reader;
import java.io.Writer;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Collection;
import java.util.Map;
import java.util.Optional;
import javax.json.spi.JsonProvider;
import javax.json.stream.JsonGenerator;
import javax.json.stream.JsonGeneratorFactory;
import javax.json.stream.JsonParser;
import javax.json.stream.JsonParserFactory;
import java.io.*;
import java.util.Map;
/**
* Factory class for creating JSON processing objects.
......@@ -72,10 +79,8 @@ import java.util.Map;
* <p>
* All the methods in this class are safe for use by multiple concurrent
* threads.
*
* @author Jitendra Kotamraju
*/
public class Json {
public final class Json {
private Json() {
}
......@@ -93,7 +98,7 @@ public class Json {
/**
* Creates a JSON parser from a byte stream.
* The character encoding of the stream is determined as specified in
* <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
* <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
*
* @param in i/o stream from which JSON is to be read
* @throws JsonException if encoding cannot be determined
......@@ -211,7 +216,7 @@ public class Json {
/**
* Creates a JSON reader from a byte stream. The character encoding of
* the stream is determined as described in
* <a href="http://tools.ietf.org/rfc/rfc4627.txt">RFC 4627</a>.
* <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
*
* @param in a byte stream from which JSON is to be read
* @return a JSON reader
......@@ -257,6 +262,34 @@ public class Json {
return JsonProvider.provider().createArrayBuilder();
}
/**
* Creates a JSON array builder, initialized with the specified array
*
* @param array the initial array in the builder
* @return a JSON array builder
*
* @since 1.1
*/
public static JsonArrayBuilder createArrayBuilder(JsonArray array) {
return JsonProvider.provider().createArrayBuilder(array);
}
/**
* Creates a JSON array builder, initialized with the content of specified {@code collection}.
* If the @{code collection} contains {@link Optional}s then resulting JSON array builder
* contains the value from the {@code collection} only if the {@link Optional} is not empty.
*
* @param collection the initial data for the builder
* @return a JSON array builder
* @exception IllegalArgumentException if the value from the {@code collection} cannot be converted
* to the corresponding {@link JsonValue}
*
* @since 1.1
*/
public static JsonArrayBuilder createArrayBuilder(Collection<?> collection) {
return JsonProvider.provider().createArrayBuilder(collection);
}
/**
* Creates a JSON object builder
*
......@@ -266,6 +299,134 @@ public class Json {
return JsonProvider.provider().createObjectBuilder();
}
/**
* Creates a JSON object builder, initialized with the specified object.
*
* @param object the initial object in the builder
* @return a JSON object builder
*
* @since 1.1
*/
public static JsonObjectBuilder createObjectBuilder(JsonObject object) {
return JsonProvider.provider().createObjectBuilder(object);
}
/**
* Creates a JSON object builder, initialized with the data from specified {@code map}.
* If the @{code map} contains {@link Optional}s then resulting JSON object builder
* contains the key from the {@code map} only if the {@link Optional} is not empty.
*
* @param map the initial object in the builder
* @return a JSON object builder
* @exception IllegalArgumentException if the value from the {@code map} cannot be converted
* to the corresponding {@link JsonValue}
*
* @since 1.1
*/
public static JsonObjectBuilder createObjectBuilder(Map<String, Object> map) {
return JsonProvider.provider().createObjectBuilder(map);
}
/**
* Creates JSON Pointer (<a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>)
* from given {@code jsonPointer} string.
* <ul>
* <li>An empty {@code jsonPointer} string defines a reference to the target itself.</li>
* <li>If the {@code jsonPointer} string is non-empty, it must be a sequence of '{@code /}' prefixed tokens.</li>
* </ul>
*
* @param jsonPointer the valid escaped JSON Pointer string
* @throws NullPointerException if {@code jsonPointer} is {@code null}
* @throws JsonException if {@code jsonPointer} is not a valid JSON Pointer
* @return a JSON Pointer
*
* @since 1.1
*/
public static JsonPointer createPointer(String jsonPointer) {
return JsonProvider.provider().createPointer(jsonPointer);
}
/**
* Creates a JSON Patch builder (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>).
*
* @return a JSON Patch builder
*
* @since 1.1
*/
public static JsonPatchBuilder createPatchBuilder() {
return JsonProvider.provider().createPatchBuilder();
}
/**
* Creates a JSON Patch builder
* (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>),
* initialized with the specified operations.
*
* @param array the initial patch operations
* @return a JSON Patch builder
*
* @since 1.1
*/
public static JsonPatchBuilder createPatchBuilder(JsonArray array) {
return JsonProvider.provider().createPatchBuilder(array);
}
/**
* Creates a JSON Patch (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>)
* from the specified operations.
*
* @param array patch operations
* @return a JSON Patch
*
* @since 1.1
*/
public static JsonPatch createPatch(JsonArray array) {
return JsonProvider.provider().createPatch(array);
}
/**
* Generates a JSON Patch (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>)
* from the source and target {@code JsonStructure}.
* The generated JSON Patch need not be unique.
*
* @param source the source
* @param target the target, must be the same type as the source
* @return a JSON Patch which when applied to the source, yields the target
*
* @since 1.1
*/
public static JsonPatch createDiff(JsonStructure source, JsonStructure target) {
return JsonProvider.provider().createDiff(source, target);
}
/**
* Creates JSON Merge Patch (<a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>)
* from specified {@code JsonValue}.
*
* @param patch the patch
* @return a JSON Merge Patch
*
* @since 1.1
*/
public static JsonMergePatch createMergePatch(JsonValue patch) {
return JsonProvider.provider().createMergePatch(patch);
}
/**
* Generates a JSON Merge Patch (<a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>)
* from the source and target {@code JsonValue}s
* which when applied to the {@code source}, yields the {@code target}.
*
* @param source the source
* @param target the target
* @return a JSON Merge Patch
*
* @since 1.1
*/
public static JsonMergePatch createMergeDiff(JsonValue source, JsonValue target) {
return JsonProvider.provider().createMergeDiff(source, target);
}
/**
* Creates a builder factory for creating {@link JsonArrayBuilder}
* and {@link JsonObjectBuilder} objects.
......@@ -282,4 +443,102 @@ public class Json {
return JsonProvider.provider().createBuilderFactory(config);
}
/**
* Creates a JsonString.
*
* @param value a JSON string
* @return the JsonString for the string
*
* @since 1.1
*/
public static JsonString createValue(String value) {
return JsonProvider.provider().createValue(value);
}
/**
* Creates a JsonNumber.
*
* @param value a JSON number
* @return the JsonNumber for the number
*
* @since 1.1
*/
public static JsonNumber createValue(int value) {
return JsonProvider.provider().createValue(value);
}
/**
* Creates a JsonNumber.
*
* @param value a JSON number
* @return the JsonNumber for the number
*
* @since 1.1
*/
public static JsonNumber createValue(long value) {
return JsonProvider.provider().createValue(value);
}
/**
* Creates a JsonNumber.
*
* @param value a JSON number
* @return the JsonNumber for the number
*
* @since 1.1
*/
public static JsonNumber createValue(double value) {
return JsonProvider.provider().createValue(value);
}
/**
* Creates a JsonNumber.
*
* @param value a JSON number
* @return the JsonNumber for the number
*
* @since 1.1
*/
public static JsonNumber createValue(BigDecimal value) {
return JsonProvider.provider().createValue(value);
}
/**
* Creates a JsonNumber.
*
* @param value a JSON number
* @return the JsonNumber for the number
*
* @since 1.1
*/
public static JsonNumber createValue(BigInteger value) {
return JsonProvider.provider().createValue(value);
}
/**
* Encodes (escapes) a passed string as defined by <a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>.
* This method doesn't validate the passed JSON-pointer string.
*
* @param pointer the JSON-pointer string to encode
* @return encoded JSON-pointer string
*
* @since 1.1
*/
public static String encodePointer(String pointer) {
return pointer.replace("~", "~0").replace("/", "~1");
}
/**
* Decodes a passed JSON-pointer string as defined by <a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>.
* This method doesn't validate the passed JSON-pointer string.
*
* @param escaped the JSON-pointer string to decode
* @return decoded JSON-pointer string
*
* @since 1.1
*/
public static String decodePointer(String escaped) {
return escaped.replace("~1", "/").replace("~0", "~");
}
}
api/src/main/java/javax/json/JsonArray.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -41,6 +41,9 @@
package javax.json;
import java.util.List;
import java.util.function.Function;
import java.util.stream.Collectors;
import java.util.stream.Stream;
/**
* {@code JsonArray} represents an immutable JSON array
......@@ -110,8 +113,6 @@ import java.util.List;
* access to the values in the JSON array. Any attempt to modify the list,
* whether directly or using its collection views, results in an
* {@code UnsupportedOperationException}.
*
* @author Jitendra Kotamraju
*/
public interface JsonArray extends JsonStructure, List<JsonValue> {
......@@ -164,18 +165,45 @@ public interface JsonArray extends JsonStructure, List<JsonValue> {
JsonString getJsonString(int index);
/**
* Returns a list a view of the specified type for the array. This method
* Returns a list view of the specified type for the array. This method
* does not verify if there is a value of wrong type in the array. Providing
* this typesafe view dynamically may cause a program fail with a
* {@code ClassCastException}, if there is a value of wrong type in this
* array. Unfortunately, the exception can occur at any time after this
* method returns.
*
* @param <T> The type of the List for the array
* @param clazz a JsonValue type
* @return a list view of the specified type
*/
<T extends JsonValue> List<T> getValuesAs(Class<T> clazz);
/**
* Returns a list view for the array. The value and the type of the elements
* in the list is specified by the {@code func} argument.
* <p>This method can be used to obtain a list of the unwrapped types, such as
* <pre>{@code
* List<String> strings = ary1.getValuesAs(JsonString::getString);
* List<Integer> ints = ary2.getValuesAs(JsonNumber::intValue);
* } </pre>
* or a list of simple projections, such as
* <pre> {@code
* List<Integer> stringsizes = ary1.getValueAs((JsonString v)->v.getString().length();
* } </pre>
* @param <K> The element type (must be a subtype of JsonValue) of this JsonArray.
* @param <T> The element type of the returned List
* @param func The function that maps the elements of this JsonArray to the target elements.
* @return A List of the specified values and type.
* @throws ClassCastException if the {@code JsonArray} contains a value of wrong type
*
* @since 1.1
*/
default <T, K extends JsonValue> List<T> getValuesAs(Function<K, T> func) {
@SuppressWarnings("unchecked")
Stream<K> stream = (Stream<K>) stream();
return stream.map(func).collect(Collectors.toList());
}
/**
* A convenience method for
* {@code getJsonString(index).getString()}.
......@@ -194,7 +222,9 @@ public interface JsonArray extends JsonStructure, List<JsonValue> {
* its {@link javax.json.JsonString#getString()} is returned. Otherwise,
* the specified default value is returned.
*
* @param index index of the JsonString value
* @param index index of the {@code JsonString} value
* @param defaultValue the String to return if the {@code JsonValue} at the
* specified position is not a {@code JsonString}
* @return the String value at the specified position in this array,
* or the specified default value
*/
......@@ -219,6 +249,8 @@ public interface JsonArray extends JsonStructure, List<JsonValue> {
* this method returns the specified default value.
*
* @param index index of the {@code JsonNumber} value
* @param defaultValue the int value to return if the {@code JsonValue} at
* the specified position is not a {@code JsonNumber}
* @return the int value at the specified position in this array,
* or the specified default value
*/
......@@ -246,6 +278,8 @@ public interface JsonArray extends JsonStructure, List<JsonValue> {
* Otherwise this method returns the specified default value.
*
* @param index index of the JSON boolean value
* @param defaultValue the boolean value to return if the {@code JsonValue}
* at the specified position is neither TRUE nor FALSE
* @return the boolean value at the specified position,
* or the specified default value
*/
......@@ -257,9 +291,8 @@ public interface JsonArray extends JsonStructure, List<JsonValue> {
*
* @param index index of the JSON null value
* @return return true if the value at the specified location is
* {@code JsonValue.NUL}, otherwise false
* {@code JsonValue.NULL}, otherwise false
* @throws IndexOutOfBoundsException if the index is out of range
*/
boolean isNull(int index);
}
api/src/main/java/javax/json/JsonArrayBuilder.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -44,10 +44,13 @@ import java.math.BigDecimal;
import java.math.BigInteger;
/**
* A builder for creating {@link JsonArray} models from scratch. This
* interface initializes an empty JSON array model and provides methods to add
* values to the array model and to return the resulting array. The methods
* in this class can be chained to add multiple values to the array.
* A builder for creating {@link JsonArray} models from scratch, and for
* modifying a existing {@code JsonArray}.
* <p>A {@code JsonArrayBuilder} can start with an empty or a non-empty
* JSON array model. This interface provides methods to add, insert, remove
* and replace values in the JSON array model.</p>
* <p>Methods in this class can be chained to perform multiple values to
* the array.</p>
*
* <p>The class {@link javax.json.Json} contains methods to create the builder
* object. The example code below shows how to build an empty {@code JsonArray}
......@@ -63,7 +66,6 @@ import java.math.BigInteger;
* multiple builder instances with the same configuration. This the preferred
* way to create multiple instances.
*
* <a id="JsonArrayBuilderExample1"/>
* The example code below shows how to build a {@code JsonArray} object
* that represents the following JSON array:
*
......@@ -205,6 +207,434 @@ public interface JsonArrayBuilder {
*/
JsonArrayBuilder add(JsonArrayBuilder builder);
/**
* Adds all elements of the array in the specified array builder to the array.
*
* @param builder the array builder
* @return this array builder
* @throws NullPointerException if the specified builder is null
*
@since 1.1
*/
default JsonArrayBuilder addAll(JsonArrayBuilder builder) {
throw new UnsupportedOperationException();
}
/**
* Inserts a value to the array at the specified position. Shifts the value
* currently at that position (if any) and any subsequent values to the right
* (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param value the JSON value
* @return this array builder
* @throws NullPointerException if the specified value is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, JsonValue value) {
throw new UnsupportedOperationException();
}
/**
* Adds a value to the array as a {@link JsonString} at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param value the string value
* @return this array builder
* @throws NullPointerException if the specified value is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, String value) {
throw new UnsupportedOperationException();
}
/**
* Adds a value to the array as a {@link JsonNumber} at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws NullPointerException if the specified value is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, BigDecimal value) {
throw new UnsupportedOperationException();
}
/**
* Adds a value to the array as a {@link JsonNumber} at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws NullPointerException if the specified value is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, BigInteger value) {
throw new UnsupportedOperationException();
}
/**
* Adds a value to the array as a {@link JsonNumber} at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, int value) {
throw new UnsupportedOperationException();
}
/**
* Adds a value to the array as a {@link JsonNumber} at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, long value) {
throw new UnsupportedOperationException();
}
/**
* Adds a value to the array as a {@link JsonNumber} at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws NumberFormatException if the value is Not-a-Number (NaN) or
* infinity
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, double value) {
throw new UnsupportedOperationException();
}
/**
* Adds a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value to the
* array at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param value the boolean value
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, boolean value) {
throw new UnsupportedOperationException();
}
/**
* Adds a {@link JsonValue#NULL} value to the array at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @since 1.1
*/
default JsonArrayBuilder addNull(int index) {
return add(index, JsonValue.NULL);
}
/**
* Adds a {@link JsonObject} from an object builder to the array at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param builder the object builder
* @return this array builder
* @throws NullPointerException if the specified builder is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, JsonObjectBuilder builder) {
throw new UnsupportedOperationException();
}
/**
* Adds a {@link JsonArray} from an array builder to the array at the specified position.
* Shifts the value currently at that position (if any) and any subsequent values
* to the right (adds one to their indices). Index starts with 0.
*
* @param index the position in the array
* @param builder the array builder
* @return this array builder
* @throws NullPointerException if the specified builder is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index > array size)}
*
* @since 1.1
*/
default JsonArrayBuilder add(int index, JsonArrayBuilder builder) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with the specified value at the
* specified position.
*
* @param index the position in the array
* @param value the JSON value
* @return this array builder
* @throws NullPointerException if the specified value is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, JsonValue value) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with the specified value as a
* {@link JsonString} at the specified position.
*
* @param index the position in the array
* @param value the string value
* @return this array builder
* @throws NullPointerException if the specified value is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, String value) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with the specified value as a
* {@link JsonNumber} at the specified position.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws NullPointerException if the specified value is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, BigDecimal value) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with the specified value as a
* {@link JsonNumber} at the specified position.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws NullPointerException if the specified value is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, BigInteger value) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with the specified value as a
* {@link JsonNumber} at the specified position.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, int value) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with the specified value as a
* {@link JsonNumber} at the specified position.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, long value) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with the specified value as a
* {@link JsonNumber} at the specified position.
*
* @param index the position in the array
* @param value the number value
* @return this array builder
* @throws NumberFormatException if the value is Not-a-Number (NaN) or
* infinity
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @see JsonNumber
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, double value) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with
* a {@link JsonValue#TRUE} or {@link JsonValue#FALSE} value
* at the specified position.
*
* @param index the position in the array
* @param value the boolean value
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, boolean value) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with
* a {@link JsonValue#NULL} value at the specified position.
*
* @param index the position in the array
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @since 1.1
*/
default JsonArrayBuilder setNull(int index) {
return set(index, JsonValue.NULL);
}
/**
* Replaces a value in the array with the specified value as a
* {@link JsonObject} from an object builder at the specified position.
*
* @param index the position in the array
* @param builder the object builder
* @return this array builder
* @throws NullPointerException if the specified builder is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, JsonObjectBuilder builder) {
throw new UnsupportedOperationException();
}
/**
* Replaces a value in the array with the specified value as a
* {@link JsonArray} from an array builder at the specified position.
*
* @param index the position in the array
* @param builder the array builder
* @return this array builder
* @throws NullPointerException if the specified builder is null
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @since 1.1
*/
default JsonArrayBuilder set(int index, JsonArrayBuilder builder) {
throw new UnsupportedOperationException();
}
/**
* Remove the value in the array at the specified position.
* Shift any subsequent values to the left (subtracts one from their
* indices.
*
* @param index the position in the array
* @return this array builder
* @throws IndexOutOfBoundsException if the index is out of range
* {@code (index < 0 || index >= array size)}
*
* @since 1.1
*/
default JsonArrayBuilder remove(int index) {
throw new UnsupportedOperationException();
}
/**
* Returns the current array.
*
......
api/src/main/java/javax/json/JsonBuilderFactory.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -40,6 +40,7 @@
package javax.json;
import java.util.Collection;
import java.util.Map;
/**
......@@ -70,8 +71,6 @@ import java.util.Map;
*
* <p> All the methods in this class are safe for use by multiple concurrent
* threads.
*
* @author Jitendra Kotamraju
*/
public interface JsonBuilderFactory {
......@@ -83,6 +82,32 @@ public interface JsonBuilderFactory {
*/
JsonObjectBuilder createObjectBuilder();
/**
* Creates a {@code JsonObjectBuilder} instance, initialized with an object.
*
* @param object the initial object in the builder
* @return a JSON object builder
* @throws NullPointerException if specified object is {@code null}
*
* @since 1.1
*/
default JsonObjectBuilder createObjectBuilder(JsonObject object) {
throw new UnsupportedOperationException();
}
/**
* Creates a {@code JsonObjectBuilder} instance, initialized with the specified object.
*
* @param object the initial object in the builder
* @return a JSON object builder
* @throws NullPointerException if specified object is {@code null}
*
* @since 1.1
*/
default JsonObjectBuilder createObjectBuilder(Map<String, Object> object) {
throw new UnsupportedOperationException();
}
/**
* Creates a {@code JsonArrayBuilder} instance that is used to build
* {@link JsonArray}
......@@ -91,6 +116,33 @@ public interface JsonBuilderFactory {
*/
JsonArrayBuilder createArrayBuilder();
/**
* Creates a {@code JsonArrayBuilder} instance, initialized with an array.
*
* @param array the initial array in the builder
* @return a JSON array builder
* @throws NullPointerException if specified array is {@code null}
*
* @since 1.1
*/
default JsonArrayBuilder createArrayBuilder(JsonArray array) {
throw new UnsupportedOperationException();
}
/**
* Creates a {@code JsonArrayBuilder} instance,
* initialized with the content of specified collection.
*
* @param collection the initial data for the builder
* @return a JSON array builder
* @throws NullPointerException if specified collection is {@code null}
*
* @since 1.1
*/
default JsonArrayBuilder createArrayBuilder(Collection<?> collection) {
throw new UnsupportedOperationException();
}
/**
* Returns read-only map of supported provider specific configuration
* properties that are used to configure the created JSON builders.
......
api/src/main/java/javax/json/JsonException.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -43,8 +43,6 @@ package javax.json;
/**
* <code>JsonException</code> indicates that some exception happened during
* JSON processing.
*
* @author Jitendra Kotamraju
*/
public class JsonException extends RuntimeException {
......
api/src/main/java/javax/json/JsonMergePatch.java 0 → 100644
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2015-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.json;
/**
* <p>This interface represents an implementation of a JSON Merge Patch
* as defined by <a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>.
* </p>
* <p>A {@code JsonMergePatch} can be instantiated with {@link Json#createMergePatch(JsonValue)}
* by specifying the patch operations in a JSON Merge Patch or using {@link Json#createMergeDiff(JsonValue, JsonValue)}
* to create a JSON Merge Patch based on the difference between two {@code JsonValue}s.
* </p>
* The following illustrates both approaches.
* <p>1. Construct a JsonMergePatch with an existing JSON Merge Patch.
* <pre>{@code
* JsonValue contacts = ... ; // The target to be patched
* JsonValue patch = ... ; // JSON Merge Patch
* JsonMergePatch mergePatch = Json.createMergePatch(patch);
* JsonValue result = mergePatch.apply(contacts);
* } </pre>
* 2. Construct a JsonMergePatch from a difference between two {@code JsonValue}s.
* <pre>{@code
* JsonValue source = ... ; // The source object
* JsonValue target = ... ; // The modified object
* JsonMergePatch mergePatch = Json.createMergeDiff(source, target); // The diff between source and target in a Json Merge Patch format
* } </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>
*
* @since 1.1
*/
public interface JsonMergePatch {
/**
* Applies the JSON Merge Patch to the specified {@code target}.
* The target is not modified by the patch.
*
* @param target the target to apply the merge patch
* @return the transformed target after the patch
*/
JsonValue apply(JsonValue target);
/**
* Returns the {@code JsonMergePatch} as {@code JsonValue}.
*
* @return this {@code JsonMergePatch} as {@code JsonValue}
*/
JsonValue toJsonValue();
}
api/src/main/java/javax/json/JsonNumber.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -50,15 +50,13 @@ import java.math.BigInteger;
* Implementations may use a {@link BigDecimal} object to store the numeric
* value internally.
* The {@code BigDecimal} object can be constructed from the following types:
* {@link BigDecimal#BigDecimal(int) <code>int</code>},
* {@link BigDecimal#BigDecimal(long) <code>long</code>},
* {@link BigDecimal#BigDecimal(BigInteger) <code>BigInteger</code>},
* {@link BigDecimal#valueOf(double) <code>double</code>}, and
* {@link BigDecimal#BigDecimal(String) <code>String</code>}.
* <code>int</code> {@link BigDecimal#BigDecimal(int)},
* <code>long</code> {@link BigDecimal#BigDecimal(long)},
* <code>BigInteger</code> {@link BigDecimal#BigDecimal(BigInteger)},
* <code>double</code> {@link BigDecimal#valueOf(double)}, and
* <code>String</code> {@link BigDecimal#BigDecimal(String)}.
* Some of the method semantics in this class are defined using the
* {@code BigDecimal} semantics.
*
* @author Jitendra Kotamraju
*/
public interface JsonNumber extends JsonValue {
......@@ -137,7 +135,7 @@ public interface JsonNumber extends JsonValue {
BigInteger bigIntegerValue();
/**
* Returns this JSON number as a {@link BigDecimal} object. This is a
* Returns this JSON number as a {@link BigInteger} object. This is a
* convenience method for {@code bigDecimalValue().toBigIntegerExact()}.
*
* @return a {@link BigInteger} representation of the JSON number
......@@ -165,6 +163,17 @@ public interface JsonNumber extends JsonValue {
*/
BigDecimal bigDecimalValue();
/**
* Returns this JSON number as a {@link Number} object.
*
* @return a {@link Number} representation of the JSON number
*
* @since 1.1
*/
default Number numberValue() {
throw new UnsupportedOperationException();
}
/**
* Returns a JSON text representation of the JSON number. The
* representation is equivalent to {@link BigDecimal#toString()}.
......
api/src/main/java/javax/json/JsonObject.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2011-2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -124,8 +124,6 @@ import java.util.Map;
* <p>The map object's iteration ordering is based on the order in which
* name/value pairs are added to the corresponding builder or the order
* in which name/value pairs appear in the corresponding stream.
*
* @author Jitendra Kotamraju
*/
public interface JsonObject extends JsonStructure, Map<String, JsonValue> {
......@@ -265,7 +263,7 @@ public interface JsonObject extends JsonStructure, Map<String, JsonValue> {
* {@code JsonValue.NULL}.
*
* @param name name whose associated value is checked
* @return return true if the associated value is {@code JsonValue.NUL},
* @return return true if the associated value is {@code JsonValue.NULL},
* otherwise false
* @throws NullPointerException if the specified name doesn't have any
* mapping
......
api/src/main/java/javax/json/JsonObjectBuilder.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -64,7 +64,6 @@ import java.math.BigInteger;
* multiple builder instances with the same configuration. This the preferred
* way to create multiple instances.
*
* <a id="JsonObjectBuilderExample1"/>
* The example code below shows how to build a {@code JsonObject} model that
* represents the following JSON object:
*
......@@ -267,6 +266,34 @@ public interface JsonObjectBuilder {
*/
JsonObjectBuilder add(String name, JsonArrayBuilder builder);
/**
* Adds all name/value pairs in the JSON object associated with the specified
* object builder to the JSON object associated with this object builder.
* The newly added name/value pair will replace any existing name/value pair with
* the same name.
*
* @param builder the specified object builder
* @return this object builder
* @throws NullPointerException if the specified builder is null
* @since 1.1
*/
default JsonObjectBuilder addAll(JsonObjectBuilder builder) {
throw new UnsupportedOperationException();
}
/**
* Remove the name/value pair from the JSON object associated with this
* object builder if it is present.
*
* @param name the name in the name/value pair to be removed
* @return this object builder
* @throws NullPointerException if the specified name is null
* @since 1.1
*/
default JsonObjectBuilder remove(String name) {
throw new UnsupportedOperationException();
}
/**
* Returns the JSON object associated with this object builder.
* The iteration order for the {@code JsonObject} is based
......
api/src/main/java/javax/json/JsonPatch.java 0 → 100644
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2015-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.json;
/**
* <p>This interface represents an immutable implementation of a JSON Patch
* as defined by <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>.
* </p>
* <p>A {@code JsonPatch} can be instantiated with {@link Json#createPatch(JsonArray)}
* by specifying the patch operations in a JSON Patch. Alternately, it
* can also be constructed with a {@link JsonPatchBuilder}.
* </p>
* The following illustrates both approaches.
* <p>1. Construct a JsonPatch with a JSON Patch.
* <pre>{@code
* JsonArray contacts = ... // The target to be patched
* JsonArray patch = ... ; // JSON Patch
* JsonPatch jsonpatch = Json.createPatch(patch);
* JsonArray result = jsonpatch.apply(contacts);
* } </pre>
* 2. Construct a JsonPatch with JsonPatchBuilder.
* <pre>{@code
* JsonPatchBuilder builder = Json.createPatchBuilder();
* JsonArray result = builder.add("/John/phones/office", "1234-567")
* .remove("/Amy/age")
* .build()
* .apply(contacts);
* } </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>
*
* @since 1.1
*/
public interface JsonPatch {
/**
* This enum represents the list of valid JSON Patch operations
* as defined by <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>.
*
* @see <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>
*/
enum Operation {
/**
* "add" operation.
*/
ADD("add"),
/**
* "remove" operation.
*/
REMOVE("remove"),
/**
* "remove" operation.
*/
REPLACE("replace"),
/**
* "move" operation.
*/
MOVE("move"),
/**
* "copy" operation.
*/
COPY("copy"),
/**
* "test" operation.
*/
TEST("test");
private final String operationName;
private Operation(String operationName) {
this.operationName = operationName;
}
/**
* Returns enum constant name as lower case string.
*
* @return lower case name of the enum constant
*/
public String operationName() {
return operationName;
}
/**
* Returns the enum constant with the specified name.
*
* @param operationName {@code operationName} to convert to the enum constant.
* @return the enum constant for given {@code operationName}
* @throws JsonException if given {@code operationName} is not recognized
*/
public static Operation fromOperationName(String operationName) {
for (Operation op : values()) {
if (op.operationName().equalsIgnoreCase(operationName)) {
return op;
}
}
throw new JsonException("Illegal value for the operationName of the JSON patch operation: " + operationName);
}
}
/**
* Applies the patch operations to the specified {@code target}.
* The target is not modified by the patch.
*
* @param <T> the target type, must be a subtype of {@link JsonStructure}
* @param target the target to apply the patch operations
* @return the transformed target after the patch
* @throws JsonException if the supplied JSON Patch is malformed or if
* it contains references to non-existing members
*/
<T extends JsonStructure> T apply(T target);
/**
* Returns the {@code JsonPatch} as {@code JsonArray}.
*
* @return this {@code JsonPatch} as {@code JsonArray}
*/
JsonArray toJsonArray();
}
api/src/main/java/javax/json/JsonPatchBuilder.java 0 → 100644
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2015-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.json;
/**
* A builder for constructing a JSON Patch as defined by
* <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a> by adding
* JSON Patch operations incrementally.
* <p>
* The following illustrates the approach.
* <pre>
* JsonPatchBuilder builder = Json.createPatchBuilder();
* JsonPatch patch = builder.add("/John/phones/office", "1234-567")
* .remove("/Amy/age")
* .build();
* </pre>
* The result is equivalent to the following JSON Patch.
* <pre>
* [
* {"op" = "add", "path" = "/John/phones/office", "value" = "1234-567"},
* {"op" = "remove", "path" = "/Amy/age"}
* ] </pre>
*
* @see <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>
*
* @since 1.1
*/
public interface JsonPatchBuilder {
/**
* Adds an "add" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder add(String path, JsonValue value);
/**
* Adds an "add" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder add(String path, String value);
/**
* Adds an "add" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder add(String path, int value);
/**
* Adds an "add" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder add(String path, boolean value);
/**
* Adds a "remove" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer.
* @return this JsonPatchBuilder
*/
JsonPatchBuilder remove(String path);
/**
* Adds a "replace" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder replace(String path, JsonValue value);
/**
* Adds a "replace" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder replace(String path, String value);
/**
* Adds a "replace" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder replace(String path, int value);
/**
* Adds a "replace" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder replace(String path, boolean value);
/**
* Adds a "move" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param from the "from" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder move(String path, String from);
/**
* Adds a "copy" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param from the "from" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder copy(String path, String from);
/**
* Adds a "test" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder test(String path, JsonValue value);
/**
* Adds a "test" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder test(String path, String value);
/**
* Adds a "test" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder test(String path, int value);
/**
* Adds a "test" JSON Patch operation.
*
* @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string.
* @param value the "value" member of the operation
* @return this JsonPatchBuilder
*/
JsonPatchBuilder test(String path, boolean value);
/**
* Returns the JSON Patch.
*
* @return a JSON Patch
*/
JsonPatch build();
}
api/src/main/java/javax/json/JsonPointer.java 0 → 100644
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2015-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.json;
/**
* <p>This interface represents an immutable implementation of a JSON Pointer
* as defined by <a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>.
* </p>
* <p> A JSON Pointer, when applied to a target {@link JsonValue},
* defines a reference location in the target.</p>
* <p> An empty JSON Pointer string defines a reference to the target itself.</p>
* <p> If the JSON Pointer string is non-empty, it must be a sequence
* of '/' prefixed tokens, and the target must either be a {@link JsonArray}
* or {@link JsonObject}. If the target is a {@code JsonArray}, the pointer
* defines a reference to an array element, and the last token specifies the index.
* If the target is a {@link JsonObject}, the pointer defines a reference to a
* name/value pair, and the last token specifies the name.
* </p>
* <p> The method {@link #getValue getValue()} returns the referenced value.
* Methods {@link #add add()}, {@link #replace replace()},
* and {@link #remove remove()} execute operations specified in
* <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>. </p>
*
* @see <a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>
* @see <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>
*
* @since 1.1
*/
public interface JsonPointer {
/**
* Adds or replaces a value at the referenced location in the specified
* {@code target} with the specified {@code value}.
* <ol>
* <li>If the reference is the target (empty JSON Pointer string),
* the specified {@code value}, which must be the same type as
* specified {@code target}, is returned.</li>
* <li>If the reference is an array element, the specified {@code value} is inserted
* into the array, at the referenced index. The value currently at that location, and
* any subsequent values, are shifted to the right (adds one to the indices).
* Index starts with 0. If the reference is specified with a "-", or if the
* index is equal to the size of the array, the value is appended to the array.</li>
* <li>If the reference is a name/value pair of a {@code JsonObject}, and the
* referenced value exists, the value is replaced by the specified {@code value}.
* If the value does not exist, a new name/value pair is added to the object.</li>
* </ol>
*
* @param <T> the target type, must be a subtype of {@link JsonValue}
* @param target the target referenced by this {@code JsonPointer}
* @param value the value to be added
* @return the transformed {@code target} after the value is added.
* @throws NullPointerException if {@code target} is {@code null}
* @throws JsonException if the reference is an array element and
* the index is out of range ({@code index < 0 || index > array size}),
* or if the pointer contains references to non-existing objects or arrays.
*/
<T extends JsonStructure> T add(T target, JsonValue value);
/**
* Removes the value at the reference location in the specified {@code target}.
*
* @param <T> the target type, must be a subtype of {@link JsonValue}
* @param target the target referenced by this {@code JsonPointer}
* @return the transformed {@code target} after the value is removed.
* @throws NullPointerException if {@code target} is {@code null}
* @throws JsonException if the referenced value does not exist,
* or if the reference is the target.
*/
<T extends JsonStructure> T remove(T target);
/**
* Replaces the value at the referenced location in the specified
* {@code target} with the specified {@code value}.
*
* @param <T> the target type, must be a subtype of {@link JsonValue}
* @param target the target referenced by this {@code JsonPointer}
* @param value the value to be stored at the referenced location
* @return the transformed {@code target} after the value is replaced.
* @throws NullPointerException if {@code target} is {@code null}
* @throws JsonException if the referenced value does not exist,
* or if the reference is the target.
*/
<T extends JsonStructure> T replace(T target, JsonValue value);
/**
* Returns {@code true} if there is a value at the referenced location in the specified {@code target}.
*
* @param target the target referenced by this {@code JsonPointer}
* @return {@code true} if this pointer points to a value in a specified {@code target}.
*/
boolean containsValue(JsonStructure target);
/**
* Returns the value at the referenced location in the specified {@code target}.
*
* @param target the target referenced by this {@code JsonPointer}
* @return the referenced value in the target.
* @throws NullPointerException if {@code target} is null
* @throws JsonException if the referenced value does not exist
*/
JsonValue getValue(JsonStructure target);
}
api/src/main/java/javax/json/JsonReader.java
View file @ b2351df6
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2012-2013 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
......@@ -50,7 +50,6 @@ import java.io.Closeable;
* input sources ({@link java.io.InputStream} and {@link java.io.Reader}).
*
* <p>
* <a id="JsonReaderExample1"/>
* The following example demonstrates how to read an empty JSON array from
* a string:
* <pre>
......@@ -74,8 +73,6 @@ import java.io.Closeable;
* JsonReader reader2 = factory.createReader(...);
* </code>
* </pre>
*
* @author Jitendra Kotamraju
*/
public interface JsonReader extends /*Auto*/Closeable {
......@@ -90,8 +87,8 @@ public interface JsonReader extends /*Auto*/Closeable {
* cause of JsonException)
* @throws javax.json.stream.JsonParsingException if a JSON object or array
* cannot be created due to incorrect representation
* @throws IllegalStateException if read, readObject, readArray or
* close method is already called
* @throws IllegalStateException if read, readObject, readArray,
* readValue or close method is already called
*/
JsonStructure read();
......@@ -106,8 +103,8 @@ public interface JsonReader extends /*Auto*/Closeable {
* cause of JsonException)
* @throws javax.json.stream.JsonParsingException if a JSON object cannot
* be created due to incorrect representation
* @throws IllegalStateException if read, readObject, readArray or
* close method is already called
* @throws IllegalStateException if read, readObject, readArray,
* readValue or close method is already called
*/
JsonObject readObject();
......@@ -122,11 +119,31 @@ public interface JsonReader extends /*Auto*/Closeable {
* cause of JsonException)
* @throws javax.json.stream.JsonParsingException if a JSON array cannot
* be created due to incorrect representation
* @throws IllegalStateException if read, readObject, readArray or
* close method is already called
* @throws IllegalStateException if read, readObject, readArray,
* readValue or close method is already called
*/
JsonArray readArray();
/**
* Returns a JSON value that is represented in
* the input source. This method needs to be called
* only once for a reader instance.
*
* @return a JSON value
* @throws JsonException if a JSON value
* be created due to i/o error (IOException would be
* cause of JsonException)
* @throws javax.json.stream.JsonParsingException if a JSON value
* cannot be created due to incorrect representation
* @throws IllegalStateException if read, readObject, readArray,
* readValue or close method is already called
*
* @since 1.1
*/
default JsonValue readValue() {
throw new UnsupportedOperationException();
}
/**
* Closes this reader and frees any resources associated with the
* reader. This method closes the underlying input source.
......