diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index a1677a18..ef1b23d0 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -4,16 +4,20 @@ on: [push, pull_request]
jobs:
build:
+ name: "Build on JDK ${{ matrix.java }}"
+ strategy:
+ matrix:
+ java: [ 11, 17 ]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- - name: Set up JDK 11
+ - name: "Set up JDK ${{ matrix.java }}"
uses: actions/setup-java@v3
with:
distribution: 'temurin'
- java-version: '11'
+ java-version: ${{ matrix.java }}
cache: 'maven'
- name: Build with Maven
# This also runs javadoc:jar to detect any issues with the Javadoc generated during release
- run: mvn --batch-mode --update-snapshots verify javadoc:jar
+ run: mvn --batch-mode --update-snapshots --no-transfer-progress verify javadoc:jar
diff --git a/.github/workflows/check-api-compatibility.yml b/.github/workflows/check-api-compatibility.yml
index aa70782b..a4465764 100644
--- a/.github/workflows/check-api-compatibility.yml
+++ b/.github/workflows/check-api-compatibility.yml
@@ -24,9 +24,9 @@ jobs:
run: |
cd gson-old-japicmp
# Set dummy version
- mvn --batch-mode org.codehaus.mojo:versions-maven-plugin:2.11.0:set -DnewVersion=JAPICMP-OLD
+ mvn --batch-mode --no-transfer-progress org.codehaus.mojo:versions-maven-plugin:2.11.0:set -DnewVersion=JAPICMP-OLD
# Install artifacts with dummy version in local repository; used later by Maven plugin for comparison
- mvn --batch-mode install -DskipTests
+ mvn --batch-mode --no-transfer-progress install -DskipTests
- name: Checkout new version
uses: actions/checkout@v3
@@ -34,7 +34,7 @@ jobs:
- name: Check API compatibility
id: check-compatibility
run: |
- mvn --batch-mode --fail-at-end package japicmp:cmp -DskipTests
+ mvn --batch-mode --fail-at-end --no-transfer-progress package japicmp:cmp -DskipTests
- name: Upload API differences artifacts
uses: actions/upload-artifact@v3
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index 10df305f..01d95bdf 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -48,7 +48,7 @@ jobs:
# Can replace this with github/codeql-action/autobuild action to run complete build
- name: Compile sources
run: |
- mvn compile --batch-mode
+ mvn compile --batch-mode --no-transfer-progress
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b0790fcd..7810fa88 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,17 +1,38 @@
Change Log
==========
+## Version 2.10
+
+* Support for serializing and deserializing Java records, on Java ≥ 16. (https://github.com/google/gson/pull/2201)
+* Add `JsonArray.asList` and `JsonObject.asMap` view methods (https://github.com/google/gson/pull/2225)
+* Fix `TypeAdapterRuntimeTypeWrapper` not detecting reflective `TreeTypeAdapter` and `FutureTypeAdapter` (https://github.com/google/gson/pull/1787)
+* Improve `JsonReader.skipValue()` (https://github.com/google/gson/pull/2062)
+* Perform numeric conversion for primitive numeric type adapters (https://github.com/google/gson/pull/2158)
+* Add `Gson.fromJson(..., TypeToken)` overloads (https://github.com/google/gson/pull/1700)
+* Fix changes to `GsonBuilder` affecting existing `Gson` instances (https://github.com/google/gson/pull/1815)
+* Make `JsonElement` conversion methods more consistent and fix javadoc (https://github.com/google/gson/pull/2178)
+* Throw `UnsupportedOperationException` when `JsonWriter.jsonValue` is not supported (https://github.com/google/gson/pull/1651)
+* Disallow `JsonObject` `Entry.setValue(null)` (https://github.com/google/gson/pull/2167)
+* Fix `TypeAdapter.toJson` throwing AssertionError for custom IOException (https://github.com/google/gson/pull/2172)
+* Convert null to JsonNull for `JsonArray.set` (https://github.com/google/gson/pull/2170)
+* Fixed nullSafe usage. (https://github.com/google/gson/pull/1555)
+* Validate `TypeToken.getParameterized` arguments (https://github.com/google/gson/pull/2166)
+* Fix #1702: Gson.toJson creates CharSequence which does not implement toString (https://github.com/google/gson/pull/1703)
+* Prefer existing adapter for concurrent `Gson.getAdapter` calls (https://github.com/google/gson/pull/2153)
+* Improve `ArrayTypeAdapter` for `Object[]` (https://github.com/google/gson/pull/1716)
+* Improve `AppendableWriter` performance (https://github.com/google/gson/pull/1706)
+
## Version 2.9.1
* Make `Object` and `JsonElement` deserialization iterative rather than
- recursive (#1912)
-* Added parsing support for enum that has overridden toString() method (#1950)
-* Removed support for building Gson with Gradle (#2081)
-* Removed obsolete `codegen` hierarchy (#2099)
-* Add support for reflection access filter (#1905)
-* Improve `TypeToken` creation validation (#2072)
-* Add explicit support for `float` in `JsonWriter` (#2130, #2132)
-* Fail when parsing invalid local date (#2134)
+ recursive (https://github.com/google/gson/pull/1912)
+* Added parsing support for enum that has overridden toString() method (https://github.com/google/gson/pull/1950)
+* Removed support for building Gson with Gradle (https://github.com/google/gson/pull/2081)
+* Removed obsolete `codegen` hierarchy (https://github.com/google/gson/pull/2099)
+* Add support for reflection access filter (https://github.com/google/gson/pull/1905)
+* Improve `TypeToken` creation validation (https://github.com/google/gson/pull/2072)
+* Add explicit support for `float` in `JsonWriter` (https://github.com/google/gson/pull/2130, https://github.com/google/gson/pull/2132)
+* Fail when parsing invalid local date (https://github.com/google/gson/pull/2134)
Also many small improvements to javadoc.
@@ -19,52 +40,52 @@ Also many small improvements to javadoc.
**The minimum supported Java version changes from 6 to 7.**
-* Change target Java version to 7 (#2043)
-* Put `module-info.class` into Multi-Release JAR folder (#2013)
-* Improve error message when abstract class cannot be constructed (#1814)
-* Support EnumMap deserialization (#2071)
-* Add LazilyParsedNumber default adapter (#2060)
-* Fix JsonReader.hasNext() returning true at end of document (#2061)
+* Change target Java version to 7 (https://github.com/google/gson/pull/2043)
+* Put `module-info.class` into Multi-Release JAR folder (https://github.com/google/gson/pull/2013)
+* Improve error message when abstract class cannot be constructed (https://github.com/google/gson/pull/1814)
+* Support EnumMap deserialization (https://github.com/google/gson/pull/2071)
+* Add LazilyParsedNumber default adapter (https://github.com/google/gson/pull/2060)
+* Fix JsonReader.hasNext() returning true at end of document (https://github.com/google/gson/pull/2061)
* Remove Gradle build support. Build script was outdated and not actively
- maintained anymore (#2063)
-* Add `GsonBuilder.disableJdkUnsafe()` (#1904)
-* Add `UPPER_CASE_WITH_UNDERSCORES` in FieldNamingPolicy (#2024)
-* Fix failing to serialize Collection or Map with inaccessible constructor (#1902)
-* Improve TreeTypeAdapter thread-safety (#1976)
-* Fix `Gson.newJsonWriter` ignoring lenient and HTML-safe setting (#1989)
-* Delete unused LinkedHashTreeMap (#1992)
-* Make default adapters stricter; improve exception messages (#2000)
-* Fix `FieldNamingPolicy.upperCaseFirstLetter` uppercasing non-letter (#2004)
+ maintained anymore (https://github.com/google/gson/pull/2063)
+* Add `GsonBuilder.disableJdkUnsafe()` (https://github.com/google/gson/pull/1904)
+* Add `UPPER_CASE_WITH_UNDERSCORES` in FieldNamingPolicy (https://github.com/google/gson/pull/2024)
+* Fix failing to serialize Collection or Map with inaccessible constructor (https://github.com/google/gson/pull/1902)
+* Improve TreeTypeAdapter thread-safety (https://github.com/google/gson/pull/1976)
+* Fix `Gson.newJsonWriter` ignoring lenient and HTML-safe setting (https://github.com/google/gson/pull/1989)
+* Delete unused LinkedHashTreeMap (https://github.com/google/gson/pull/1992)
+* Make default adapters stricter; improve exception messages (https://github.com/google/gson/pull/2000)
+* Fix `FieldNamingPolicy.upperCaseFirstLetter` uppercasing non-letter (https://github.com/google/gson/pull/2004)
## Version 2.8.9
-* Make OSGi bundle's dependency on `sun.misc` optional (#1993).
-* Deprecate `Gson.excluder()` exposing internal `Excluder` class (#1986).
-* Prevent Java deserialization of internal classes (#1991).
-* Improve number strategy implementation (#1987).
-* Fix LongSerializationPolicy null handling being inconsistent with Gson (#1990).
-* Support arbitrary Number implementation for Object and Number deserialization (#1290).
-* Bump proguard-maven-plugin from 2.4.0 to 2.5.1 (#1980).
-* Don't exclude static local classes (#1969).
-* Fix `RuntimeTypeAdapterFactory` depending on internal `Streams` class (#1959).
-* Improve Maven build (#1964).
-* Make dependency on `java.sql` optional (#1707).
+* Make OSGi bundle's dependency on `sun.misc` optional (https://github.com/google/gson/pull/1993).
+* Deprecate `Gson.excluder()` exposing internal `Excluder` class (https://github.com/google/gson/pull/1986).
+* Prevent Java deserialization of internal classes (https://github.com/google/gson/pull/1991).
+* Improve number strategy implementation (https://github.com/google/gson/pull/1987).
+* Fix LongSerializationPolicy null handling being inconsistent with Gson (https://github.com/google/gson/pull/1990).
+* Support arbitrary Number implementation for Object and Number deserialization (https://github.com/google/gson/pull/1290).
+* Bump proguard-maven-plugin from 2.4.0 to 2.5.1 (https://github.com/google/gson/pull/1980).
+* Don't exclude static local classes (https://github.com/google/gson/pull/1969).
+* Fix `RuntimeTypeAdapterFactory` depending on internal `Streams` class (https://github.com/google/gson/pull/1959).
+* Improve Maven build (https://github.com/google/gson/pull/1964).
+* Make dependency on `java.sql` optional (https://github.com/google/gson/pull/1707).
## Version 2.8.8
-* Fixed issue with recursive types (#1390).
-* Better behaviour with Java 9+ and `Unsafe` if there is a security manager (#1712).
-* `EnumTypeAdapter` now works better when ProGuard has obfuscated enum fields (#1495).
+* Fixed issue with recursive types (https://github.com/google/gson/issues/1390).
+* Better behaviour with Java 9+ and `Unsafe` if there is a security manager (https://github.com/google/gson/pull/1712).
+* `EnumTypeAdapter` now works better when ProGuard has obfuscated enum fields (https://github.com/google/gson/pull/1495).
## Version 2.8.7
* Fixed `ISO8601UtilsTest` failing on systems with UTC+X.
* Improved javadoc for `JsonStreamParser`.
-* Updated proguard.cfg (#1693).
-* Fixed `IllegalStateException` in `JsonTreeWriter` (#1592).
-* Added `JsonArray.isEmpty()` (#1640).
-* Added new test cases (#1638).
-* Fixed OSGi metadata generation to work on JavaSE < 9 (#1603).
+* Updated proguard.cfg (https://github.com/google/gson/pull/1693).
+* Fixed `IllegalStateException` in `JsonTreeWriter` (https://github.com/google/gson/issues/1592).
+* Added `JsonArray.isEmpty()` (https://github.com/google/gson/pull/1640).
+* Added new test cases (https://github.com/google/gson/pull/1638).
+* Fixed OSGi metadata generation to work on JavaSE < 9 (https://github.com/google/gson/pull/1603).
## Version 2.8.6
_2019-10-04_ [GitHub Diff](https://github.com/google/gson/compare/gson-parent-2.8.5...gson-parent-2.8.6)
diff --git a/README.md b/README.md
index 995d446a..54598ec9 100644
--- a/README.md
+++ b/README.md
@@ -45,7 +45,7 @@ There are a few open-source projects that can convert Java objects to JSON. Howe
Gradle:
```gradle
dependencies {
- implementation 'com.google.code.gson:gson:2.9.1'
+ implementation 'com.google.code.gson:gson:2.10'
}
```
@@ -54,7 +54,7 @@ Maven:
com.google.code.gsongson
- 2.9.1
+ 2.10
```
diff --git a/ReleaseProcess.md b/ReleaseProcess.md
index 6e2b923d..eaa0e7c5 100644
--- a/ReleaseProcess.md
+++ b/ReleaseProcess.md
@@ -6,7 +6,6 @@ The following is a step-by-step procedure for releasing a new version of Google-
1. Ensure all changelists are code-reviewed and have +1
1. `cd gson` to the parent directory; ensure there are no open files and all changes are committed.
1. Run `mvn release:clean`
-1. Do a dry run: `mvn release:prepare -DdryRun=true`
1. Start the release: `mvn release:prepare`
- Answer questions: usually the defaults are fine. Try to follow [Semantic Versioning](https://semver.org/) when choosing the release version number.
- This will do a full build, change version from `-SNAPSHOT` to the released version, commit and create the tags. It will then change the version to `-SNAPSHOT` for the next release.
@@ -18,9 +17,13 @@ The following is a step-by-step procedure for releasing a new version of Google-
1. Update version references in (version might be referenced multiple times):
- [`README.md`](README.md)
- [`UserGuide.md`](UserGuide.md)
+
+ Note: When using the Maven Release Plugin as described above, these version references should have been replaced automatically, but verify this manually nonetheless to be on the safe side.
1. Optional: Create a post on the [Gson Discussion Forum](https://groups.google.com/group/google-gson).
1. Optional: Update the release version in [Wikipedia](https://en.wikipedia.org/wiki/Gson) and update the current "stable" release.
+Important: When aborting a release / rolling back release preparations, make sure to also revert all changes to files which were done during the release (e.g. automatic replacement of version references).
+
## Configuring a machine for deployment to Sonatype Repository
This section was borrowed heavily from [Doclava release process](https://code.google.com/archive/p/doclava/wikis/ProcessRelease.wiki).
diff --git a/UserGuide.md b/UserGuide.md
index 12b53351..b82bd725 100644
--- a/UserGuide.md
+++ b/UserGuide.md
@@ -76,7 +76,7 @@ The Gson instance does not maintain any state while invoking JSON operations. So
```gradle
dependencies {
- implementation 'com.google.code.gson:gson:2.9.1'
+ implementation 'com.google.code.gson:gson:2.10'
}
```
@@ -90,7 +90,7 @@ To use Gson with Maven2/3, you can use the Gson version available in Maven Centr
com.google.code.gsongson
- 2.9.1
+ 2.10compile
@@ -225,7 +225,9 @@ Collection ints = Arrays.asList(1,2,3,4,5);
String json = gson.toJson(ints); // ==> json is [1,2,3,4,5]
// Deserialization
-Type collectionType = new TypeToken>(){}.getType();
+TypeToken> collectionType = new TypeToken>(){};
+// Note: For older Gson versions it is necessary to use `collectionType.getType()` as argument below,
+// this is however not type-safe and care must be taken to specify the correct type for the local variable
Collection ints2 = gson.fromJson(json, collectionType);
// ==> ints2 is same as ints
```
@@ -263,10 +265,12 @@ For deserialization Gson uses the `read` method of the `TypeAdapter` registered
```java
Gson gson = new Gson();
-Type mapType = new TypeToken>(){}.getType();
+TypeToken> mapType = new TypeToken>(){};
String json = "{\"key\": \"value\"}";
// Deserialization
+// Note: For older Gson versions it is necessary to use `mapType.getType()` as argument below,
+// this is however not type-safe and care must be taken to specify the correct type for the local variable
Map stringMap = gson.fromJson(json, mapType);
// ==> stringMap is {key=value}
```
diff --git a/extras/pom.xml b/extras/pom.xml
index 152f0644..e19851cb 100644
--- a/extras/pom.xml
+++ b/extras/pom.xml
@@ -3,7 +3,7 @@
io.gitlab.jfronnygson-parent
- 2.9.2-SNAPSHOT
+ 2.11-SNAPSHOTgson-extras
diff --git a/extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java b/extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java
index 502ad4ec..87b522f0 100644
--- a/extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java
+++ b/extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java
@@ -91,7 +91,7 @@ import java.util.Map;
* Both the type field name ({@code "type"}) and the type labels ({@code
* "Rectangle"}) are configurable.
*
- *
Registering Types
+ *
Registering Types
* Create a {@code RuntimeTypeAdapterFactory} by passing the base type and type field
* name to the {@link #of} factory method. If you don't supply an explicit type
* field name, {@code "type"} will be used.
* In order to serialize and deserialize a polymorphic object,
* you must specify the base type explicitly.
*
{@code
@@ -158,7 +158,7 @@ public final class RuntimeTypeAdapterFactory implements TypeAdapterFactory {
public static RuntimeTypeAdapterFactory of(Class baseType, String typeFieldName, boolean maintainType) {
return new RuntimeTypeAdapterFactory<>(baseType, typeFieldName, maintainType);
}
-
+
/**
* Creates a new runtime type adapter using for {@code baseType} using {@code
* typeFieldName} as the type field name. Type field names are case sensitive.
@@ -244,7 +244,7 @@ public final class RuntimeTypeAdapterFactory implements TypeAdapterFactory {
} else {
labelJsonElement = jsonElement.getAsJsonObject().remove(typeFieldName);
}
-
+
if (labelJsonElement == null) {
throw new JsonParseException("cannot deserialize " + baseType
+ " because it does not define a field named " + typeFieldName);
@@ -282,7 +282,7 @@ public final class RuntimeTypeAdapterFactory implements TypeAdapterFactory {
+ " because it already defines a field named " + typeFieldName);
}
clone.add(typeFieldName, new JsonPrimitive(label));
-
+
for (Map.Entry e : jsonObject.entrySet()) {
clone.add(e.getKey(), e.getValue());
}
diff --git a/gson/pom.xml b/gson/pom.xml
index 2dd465aa..d8c0bb7a 100644
--- a/gson/pom.xml
+++ b/gson/pom.xml
@@ -4,7 +4,7 @@
io.gitlab.jfronnygson-parent
- 2.9.2-SNAPSHOT
+ 2.11-SNAPSHOTgson
@@ -17,6 +17,10 @@
+
+ **/Java17*
+
+
junit
@@ -60,7 +64,23 @@
+
+ default-testCompile
+ test-compile
+
+ testCompile
+
+
+
+ ${excludeTestCompilation}
+
+
+
+
+ 8
+ 8
+ biz.aQute.bnd
@@ -119,4 +139,16 @@
+
+
+ JDK17
+
+ [17,)
+
+
+ 17
+
+
+
+
diff --git a/gson/src/main/java/com/google/gson/FieldNamingPolicy.java b/gson/src/main/java/com/google/gson/FieldNamingPolicy.java
index a4fa7c27..cd42f42c 100644
--- a/gson/src/main/java/com/google/gson/FieldNamingPolicy.java
+++ b/gson/src/main/java/com/google/gson/FieldNamingPolicy.java
@@ -86,6 +86,8 @@ public enum FieldNamingPolicy implements FieldNamingStrategy {
*
aStringField ---> A_STRING_FIELD
*
aURL ---> A_U_R_L
*
+ *
+ * @since 2.9.0
*/
UPPER_CASE_WITH_UNDERSCORES() {
@Override public String translateName(Field f) {
@@ -125,7 +127,8 @@ public enum FieldNamingPolicy implements FieldNamingStrategy {
* Using dashes in JavaScript is not recommended since dash is also used for a minus sign in
* expressions. This requires that a field named with dashes is always accessed as a quoted
* property like {@code myobject['my-field']}. Accessing it as an object field
- * {@code myobject.my-field} will result in an unintended javascript expression.
+ * {@code myobject.my-field} will result in an unintended JavaScript expression.
+ *
* @since 1.4
*/
LOWER_CASE_WITH_DASHES() {
@@ -148,8 +151,9 @@ public enum FieldNamingPolicy implements FieldNamingStrategy {
* Using dots in JavaScript is not recommended since dot is also used for a member sign in
* expressions. This requires that a field named with dots is always accessed as a quoted
* property like {@code myobject['my.field']}. Accessing it as an object field
- * {@code myobject.my.field} will result in an unintended javascript expression.
- * @since 2.8
+ * {@code myobject.my.field} will result in an unintended JavaScript expression.
+ *
+ * @since 2.8.4
*/
LOWER_CASE_WITH_DOTS() {
@Override public String translateName(Field f) {
diff --git a/gson/src/main/java/com/google/gson/Gson.java b/gson/src/main/java/com/google/gson/Gson.java
index ad427d2e..b9638d27 100644
--- a/gson/src/main/java/com/google/gson/Gson.java
+++ b/gson/src/main/java/com/google/gson/Gson.java
@@ -27,6 +27,7 @@ import com.google.gson.internal.bind.MapTypeAdapterFactory;
import com.google.gson.internal.bind.NumberTypeAdapter;
import com.google.gson.internal.bind.ObjectTypeAdapter;
import com.google.gson.internal.bind.ReflectiveTypeAdapterFactory;
+import com.google.gson.internal.bind.SerializationDelegatingTypeAdapter;
import com.google.gson.internal.bind.TypeAdapters;
import com.google.gson.internal.sql.SqlTypesSupport;
import com.google.gson.reflect.TypeToken;
@@ -71,26 +72,32 @@ import java.util.concurrent.atomic.AtomicLongArray;
*
* Gson gson = new Gson(); // Or use new GsonBuilder().create();
* MyType target = new MyType();
- * String json = gson.toJson(target); // serializes target to Json
+ * String json = gson.toJson(target); // serializes target to JSON
* MyType target2 = gson.fromJson(json, MyType.class); // deserializes json into target2
*
*
- *
If the object that your are serializing/deserializing is a {@code ParameterizedType}
- * (i.e. contains at least one type parameter and may be an array) then you must use the
- * {@link #toJson(Object, Type)} or {@link #fromJson(String, Type)} method. Here is an
- * example for serializing and deserializing a {@code ParameterizedType}:
- *
+ *
If the type of the object that you are converting is a {@code ParameterizedType}
+ * (i.e. has at least one type argument, for example {@code List}) then for
+ * deserialization you must use a {@code fromJson} method with {@link Type} or {@link TypeToken}
+ * parameter to specify the parameterized type. For serialization specifying a {@code Type}
+ * or {@code TypeToken} is optional, otherwise Gson will use the runtime type of the object.
+ * {@link TypeToken} is a class provided by Gson which helps creating parameterized types.
+ * Here is an example showing how this can be done:
*
- * Type listType = new TypeToken<List<String>>() {}.getType();
- * List<String> target = new LinkedList<String>();
- * target.add("blah");
+ * TypeToken<List<MyType>> listType = new TypeToken<List<MyType>>() {};
+ * List<MyType> target = new LinkedList<MyType>();
+ * target.add(new MyType(1, "abc"));
*
* Gson gson = new Gson();
- * String json = gson.toJson(target, listType);
- * List<String> target2 = gson.fromJson(json, listType);
+ * // For serialization you normally do not have to specify the type, Gson will use
+ * // the runtime type of the objects, however you can also specify it explicitly
+ * String json = gson.toJson(target, listType.getType());
+ *
+ * // But for deserialization you have to specify the type
+ * List<MyType> target2 = gson.fromJson(json, listType);
*
See the Gson User Guide
* for a more complete set of examples.
*
*
Lenient JSON handling
@@ -120,7 +127,7 @@ import java.util.concurrent.atomic.AtomicLongArray;
* to make sure there is no trailing data
*
*
- * @see com.google.gson.reflect.TypeToken
+ * @see TypeToken
*
* @author Inderjeet Singh
* @author Joel Leitch
@@ -192,9 +199,9 @@ public final class Gson {
* through {@link GsonBuilder#excludeFieldsWithoutExposeAnnotation()}.
*
By default, Gson ignores the {@link com.google.gson.annotations.Since} annotation. You
* can enable Gson to use this annotation through {@link GsonBuilder#setVersion(double)}.
- *
The default field naming policy for the output Json is same as in Java. So, a Java class
+ *
The default field naming policy for the output JSON is same as in Java. So, a Java class
* field versionNumber will be output as "versionNumber" in
- * Json. The same rules are applied for mapping incoming Json to the Java classes. You can
+ * JSON. The same rules are applied for mapping incoming JSON to the Java classes. You can
* change this policy through {@link GsonBuilder#setFieldNamingPolicy(FieldNamingPolicy)}.
*
By default, Gson excludes transient or static fields from
* consideration for serialization and deserialization. You can change this behavior through
@@ -321,6 +328,7 @@ public final class Gson {
* instance.
*
* @return a GsonBuilder instance.
+ * @since 2.8.3
*/
public GsonBuilder newBuilder() {
return new GsonBuilder(this);
@@ -374,7 +382,7 @@ public final class Gson {
}
double doubleValue = value.doubleValue();
checkValidFloatingPoint(doubleValue);
- out.value(value);
+ out.value(doubleValue);
}
};
}
@@ -398,7 +406,10 @@ public final class Gson {
}
float floatValue = value.floatValue();
checkValidFloatingPoint(floatValue);
- out.value(value);
+ // For backward compatibility don't call `JsonWriter.value(float)` because that method has
+ // been newly added and not all custom JsonWriter implementations might override it yet
+ Number floatNumber = value instanceof Float ? value : floatValue;
+ out.value(floatNumber);
}
};
}
@@ -619,13 +630,15 @@ public final class Gson {
* {@link JsonElement}s. This method should be used when the specified object is not a generic
* type. This method uses {@link Class#getClass()} to get the type for the specified object, but
* the {@code getClass()} loses the generic type information because of the Type Erasure feature
- * of Java. Note that this method works fine if the any of the object fields are of generic type,
+ * of Java. Note that this method works fine if any of the object fields are of generic type,
* just the object itself should not be of a generic type. If the object is of generic type, use
* {@link #toJsonTree(Object, Type)} instead.
*
- * @param src the object for which Json representation is to be created setting for Gson
- * @return Json representation of {@code src}.
+ * @param src the object for which JSON representation is to be created
+ * @return JSON representation of {@code src}.
* @since 1.4
+ *
+ * @see #toJsonTree(Object, Type)
*/
public JsonElement toJsonTree(Object src) {
if (src == null) {
@@ -649,6 +662,8 @@ public final class Gson {
*
* @return Json representation of {@code src}
* @since 1.4
+ *
+ * @see #toJsonTree(Object)
*/
public JsonElement toJsonTree(Object src, Type typeOfSrc) {
JsonTreeWriter writer = new JsonTreeWriter();
@@ -657,17 +672,20 @@ public final class Gson {
}
/**
- * This method serializes the specified object into its equivalent Json representation.
+ * This method serializes the specified object into its equivalent JSON representation.
* This method should be used when the specified object is not a generic type. This method uses
* {@link Class#getClass()} to get the type for the specified object, but the
* {@code getClass()} loses the generic type information because of the Type Erasure feature
- * of Java. Note that this method works fine if the any of the object fields are of generic type,
+ * of Java. Note that this method works fine if any of the object fields are of generic type,
* just the object itself should not be of a generic type. If the object is of generic type, use
* {@link #toJson(Object, Type)} instead. If you want to write out the object to a
* {@link Writer}, use {@link #toJson(Object, Appendable)} instead.
*
- * @param src the object for which Json representation is to be created setting for Gson
+ * @param src the object for which JSON representation is to be created
* @return Json representation of {@code src}.
+ *
+ * @see #toJson(Object, Appendable)
+ * @see #toJson(Object, Type)
*/
public String toJson(Object src) {
if (src == null) {
@@ -678,7 +696,7 @@ public final class Gson {
/**
* This method serializes the specified object, including those of generic types, into its
- * equivalent Json representation. This method must be used if the specified object is a generic
+ * equivalent JSON representation. This method must be used if the specified object is a generic
* type. For non-generic objects, use {@link #toJson(Object)} instead. If you want to write out
* the object to a {@link Appendable}, use {@link #toJson(Object, Type, Appendable)} instead.
*
@@ -689,7 +707,10 @@ public final class Gson {
*
* Type typeOfSrc = new TypeToken<Collection<Foo>>(){}.getType();
*
- * @return Json representation of {@code src}
+ * @return JSON representation of {@code src}
+ *
+ * @see #toJson(Object, Type, Appendable)
+ * @see #toJson(Object)
*/
public String toJson(Object src, Type typeOfSrc) {
StringWriter writer = new StringWriter();
@@ -698,18 +719,22 @@ public final class Gson {
}
/**
- * This method serializes the specified object into its equivalent Json representation.
+ * This method serializes the specified object into its equivalent JSON representation and
+ * writes it to the writer.
* This method should be used when the specified object is not a generic type. This method uses
* {@link Class#getClass()} to get the type for the specified object, but the
* {@code getClass()} loses the generic type information because of the Type Erasure feature
- * of Java. Note that this method works fine if the any of the object fields are of generic type,
+ * of Java. Note that this method works fine if any of the object fields are of generic type,
* just the object itself should not be of a generic type. If the object is of generic type, use
* {@link #toJson(Object, Type, Appendable)} instead.
*
- * @param src the object for which Json representation is to be created setting for Gson
- * @param writer Writer to which the Json representation needs to be written
+ * @param src the object for which JSON representation is to be created
+ * @param writer Writer to which the JSON representation needs to be written
* @throws JsonIOException if there was a problem writing to the writer
* @since 1.2
+ *
+ * @see #toJson(Object)
+ * @see #toJson(Object, Type, Appendable)
*/
public void toJson(Object src, Appendable writer) throws JsonIOException {
if (src != null) {
@@ -721,8 +746,9 @@ public final class Gson {
/**
* This method serializes the specified object, including those of generic types, into its
- * equivalent Json representation. This method must be used if the specified object is a generic
- * type. For non-generic objects, use {@link #toJson(Object, Appendable)} instead.
+ * equivalent JSON representation and writes it to the writer.
+ * This method must be used if the specified object is a generic type. For non-generic objects,
+ * use {@link #toJson(Object, Appendable)} instead.
*
* @param src the object for which JSON representation is to be created
* @param typeOfSrc The specific genericized type of src. You can obtain
@@ -731,9 +757,12 @@ public final class Gson {
*
* Type typeOfSrc = new TypeToken<Collection<Foo>>(){}.getType();
*
- * @param writer Writer to which the Json representation of src needs to be written.
+ * @param writer Writer to which the JSON representation of src needs to be written.
* @throws JsonIOException if there was a problem writing to the writer
* @since 1.2
+ *
+ * @see #toJson(Object, Type)
+ * @see #toJson(Object, Appendable)
*/
public void toJson(Object src, Type typeOfSrc, Appendable writer) throws JsonIOException {
try {
@@ -802,7 +831,7 @@ public final class Gson {
* Writes out the equivalent JSON for a tree of {@link JsonElement}s.
*
* @param jsonElement root of a tree of {@link JsonElement}s
- * @param writer Writer to which the Json representation needs to be written
+ * @param writer Writer to which the JSON representation needs to be written
* @throws JsonIOException if there was a problem writing to the writer
* @since 1.4
*/
@@ -840,6 +869,7 @@ public final class Gson {
jsonWriter.setLenient(lenient);
jsonWriter.setOmitQuotes(omitQuotes);
jsonWriter.setSerializeNulls(serializeNulls);
+ jsonWriter.setSerializeSpecialFloatingPointValues(serializeSpecialFloatingPointValues);
return jsonWriter;
}
@@ -854,6 +884,7 @@ public final class Gson {
public JsonReader newJsonReader(Reader reader) {
JsonReader jsonReader = new JsonReader(reader);
jsonReader.setLenient(lenient);
+ jsonReader.setSerializeSpecialFloatingPointValues(serializeSpecialFloatingPointValues);
return jsonReader;
}
@@ -896,17 +927,17 @@ public final class Gson {
}
/**
- * This method deserializes the specified Json into an object of the specified class. It is not
+ * This method deserializes the specified JSON into an object of the specified class. It is not
* suitable to use if the specified class is a generic type since it will not have the generic
* type information because of the Type Erasure feature of Java. Therefore, this method should not
* be used if the desired type is a generic type. Note that this method works fine if the any of
* the fields of the specified object are generics, just the object itself should not be a
* generic type. For the cases when the object is of generic type, invoke
- * {@link #fromJson(String, Type)}. If you have the Json in a {@link Reader} instead of
+ * {@link #fromJson(String, TypeToken)}. If you have the JSON in a {@link Reader} instead of
* a String, use {@link #fromJson(Reader, Class)} instead.
*
- *
An exception is thrown if the JSON string has multiple top-level JSON elements,
- * or if there is trailing data.
+ *
An exception is thrown if the JSON string has multiple top-level JSON elements, or if there
+ * is trailing data. Use {@link #fromJson(JsonReader, Type)} if this behavior is not desired.
*
* @param the type of the desired object
* @param json the string from which the object is to be deserialized
@@ -915,98 +946,167 @@ public final class Gson {
* or if {@code json} is empty.
* @throws JsonSyntaxException if json is not a valid representation for an object of type
* classOfT
+ *
+ * @see #fromJson(Reader, Class)
+ * @see #fromJson(String, TypeToken)
*/
public T fromJson(String json, Class classOfT) throws JsonSyntaxException {
- Object object = fromJson(json, (Type) classOfT);
+ T object = fromJson(json, TypeToken.get(classOfT));
return Primitives.wrap(classOfT).cast(object);
}
/**
- * This method deserializes the specified Json into an object of the specified type. This method
+ * This method deserializes the specified JSON into an object of the specified type. This method
* is useful if the specified object is a generic type. For non-generic objects, use
- * {@link #fromJson(String, Class)} instead. If you have the Json in a {@link Reader} instead of
+ * {@link #fromJson(String, Class)} instead. If you have the JSON in a {@link Reader} instead of
* a String, use {@link #fromJson(Reader, Type)} instead.
*
+ *
Since {@code Type} is not parameterized by T, this method is not type-safe and
+ * should be used carefully. If you are creating the {@code Type} from a {@link TypeToken},
+ * prefer using {@link #fromJson(String, TypeToken)} instead since its return type is based
+ * on the {@code TypeToken} and is therefore more type-safe.
+ *
*
An exception is thrown if the JSON string has multiple top-level JSON elements,
- * or if there is trailing data.
+ * or if there is trailing data. Use {@link #fromJson(JsonReader, Type)} if this behavior is
+ * not desired.
*
* @param the type of the desired object
* @param json the string from which the object is to be deserialized
- * @param typeOfT The specific genericized type of src. You can obtain this type by using the
- * {@link com.google.gson.reflect.TypeToken} class. For example, to get the type for
+ * @param typeOfT The specific genericized type of src
+ * @return an object of type T from the string. Returns {@code null} if {@code json} is {@code null}
+ * or if {@code json} is empty.
+ * @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
+ *
+ * @see #fromJson(Reader, Type)
+ * @see #fromJson(String, Class)
+ * @see #fromJson(String, TypeToken)
+ */
+ @SuppressWarnings("unchecked")
+ public T fromJson(String json, Type typeOfT) throws JsonSyntaxException {
+ return (T) fromJson(json, TypeToken.get(typeOfT));
+ }
+
+ /**
+ * This method deserializes the specified JSON into an object of the specified type. This method
+ * is useful if the specified object is a generic type. For non-generic objects, use
+ * {@link #fromJson(String, Class)} instead. If you have the JSON in a {@link Reader} instead of
+ * a String, use {@link #fromJson(Reader, TypeToken)} instead.
+ *
+ *
An exception is thrown if the JSON string has multiple top-level JSON elements, or if there
+ * is trailing data. Use {@link #fromJson(JsonReader, TypeToken)} if this behavior is not desired.
+ *
+ * @param the type of the desired object
+ * @param json the string from which the object is to be deserialized
+ * @param typeOfT The specific genericized type of src. You should create an anonymous subclass of
+ * {@code TypeToken} with the specific generic type arguments. For example, to get the type for
* {@code Collection}, you should use:
*
- * Type typeOfT = new TypeToken<Collection<Foo>>(){}.getType();
+ * new TypeToken<Collection<Foo>>(){}
*
* @return an object of type T from the string. Returns {@code null} if {@code json} is {@code null}
* or if {@code json} is empty.
- * @throws JsonParseException if json is not a valid representation for an object of type typeOfT
- * @throws JsonSyntaxException if json is not a valid representation for an object of type
+ * @throws JsonSyntaxException if json is not a valid representation for an object of the type typeOfT
+ *
+ * @see #fromJson(Reader, TypeToken)
+ * @see #fromJson(String, Class)
+ * @since 2.10
*/
- public T fromJson(String json, Type typeOfT) throws JsonSyntaxException {
+ public T fromJson(String json, TypeToken typeOfT) throws JsonSyntaxException {
if (json == null) {
return null;
}
StringReader reader = new StringReader(json);
- @SuppressWarnings("unchecked")
- T target = (T) fromJson(reader, typeOfT);
- return target;
+ return fromJson(reader, typeOfT);
}
/**
- * This method deserializes the Json read from the specified reader into an object of the
+ * This method deserializes the JSON read from the specified reader into an object of the
* specified class. It is not suitable to use if the specified class is a generic type since it
* will not have the generic type information because of the Type Erasure feature of Java.
* Therefore, this method should not be used if the desired type is a generic type. Note that
- * this method works fine if the any of the fields of the specified object are generics, just the
+ * this method works fine if any of the fields of the specified object are generics, just the
* object itself should not be a generic type. For the cases when the object is of generic type,
- * invoke {@link #fromJson(Reader, Type)}. If you have the Json in a String form instead of a
+ * invoke {@link #fromJson(Reader, TypeToken)}. If you have the JSON in a String form instead of a
* {@link Reader}, use {@link #fromJson(String, Class)} instead.
*
- *
An exception is thrown if the JSON data has multiple top-level JSON elements,
- * or if there is trailing data.
+ *
An exception is thrown if the JSON data has multiple top-level JSON elements, or if there
+ * is trailing data. Use {@link #fromJson(JsonReader, Type)} if this behavior is not desired.
*
* @param the type of the desired object
- * @param json the reader producing the Json from which the object is to be deserialized.
+ * @param json the reader producing the JSON from which the object is to be deserialized.
* @param classOfT the class of T
- * @return an object of type T from the string. Returns {@code null} if {@code json} is at EOF.
+ * @return an object of type T from the Reader. Returns {@code null} if {@code json} is at EOF.
* @throws JsonIOException if there was a problem reading from the Reader
- * @throws JsonSyntaxException if json is not a valid representation for an object of type
+ * @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
* @since 1.2
+ *
+ * @see #fromJson(String, Class)
+ * @see #fromJson(Reader, TypeToken)
*/
public T fromJson(Reader json, Class classOfT) throws JsonSyntaxException, JsonIOException {
- JsonReader jsonReader = newJsonReader(json);
- Object object = fromJson(jsonReader, classOfT);
- assertFullConsumption(object, jsonReader);
+ T object = fromJson(json, TypeToken.get(classOfT));
return Primitives.wrap(classOfT).cast(object);
}
/**
- * This method deserializes the Json read from the specified reader into an object of the
+ * This method deserializes the JSON read from the specified reader into an object of the
* specified type. This method is useful if the specified object is a generic type. For
- * non-generic objects, use {@link #fromJson(Reader, Class)} instead. If you have the Json in a
+ * non-generic objects, use {@link #fromJson(Reader, Class)} instead. If you have the JSON in a
* String form instead of a {@link Reader}, use {@link #fromJson(String, Type)} instead.
*
- *
An exception is thrown if the JSON data has multiple top-level JSON elements,
- * or if there is trailing data.
+ *
Since {@code Type} is not parameterized by T, this method is not type-safe and
+ * should be used carefully. If you are creating the {@code Type} from a {@link TypeToken},
+ * prefer using {@link #fromJson(Reader, TypeToken)} instead since its return type is based
+ * on the {@code TypeToken} and is therefore more type-safe.
+ *
+ *
An exception is thrown if the JSON data has multiple top-level JSON elements, or if there
+ * is trailing data. Use {@link #fromJson(JsonReader, Type)} if this behavior is not desired.
*
* @param the type of the desired object
- * @param json the reader producing Json from which the object is to be deserialized
- * @param typeOfT The specific genericized type of src. You can obtain this type by using the
- * {@link com.google.gson.reflect.TypeToken} class. For example, to get the type for
+ * @param json the reader producing JSON from which the object is to be deserialized
+ * @param typeOfT The specific genericized type of src
+ * @return an object of type T from the Reader. Returns {@code null} if {@code json} is at EOF.
+ * @throws JsonIOException if there was a problem reading from the Reader
+ * @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
+ * @since 1.2
+ *
+ * @see #fromJson(String, Type)
+ * @see #fromJson(Reader, Class)
+ * @see #fromJson(Reader, TypeToken)
+ */
+ @SuppressWarnings("unchecked")
+ public T fromJson(Reader json, Type typeOfT) throws JsonIOException, JsonSyntaxException {
+ return (T) fromJson(json, TypeToken.get(typeOfT));
+ }
+
+ /**
+ * This method deserializes the JSON read from the specified reader into an object of the
+ * specified type. This method is useful if the specified object is a generic type. For
+ * non-generic objects, use {@link #fromJson(Reader, Class)} instead. If you have the JSON in a
+ * String form instead of a {@link Reader}, use {@link #fromJson(String, TypeToken)} instead.
+ *
+ *
An exception is thrown if the JSON data has multiple top-level JSON elements, or if there
+ * is trailing data. Use {@link #fromJson(JsonReader, TypeToken)} if this behavior is not desired.
+ *
+ * @param the type of the desired object
+ * @param json the reader producing JSON from which the object is to be deserialized
+ * @param typeOfT The specific genericized type of src. You should create an anonymous subclass of
+ * {@code TypeToken} with the specific generic type arguments. For example, to get the type for
* {@code Collection}, you should use:
*
- * Type typeOfT = new TypeToken<Collection<Foo>>(){}.getType();
+ * new TypeToken<Collection<Foo>>(){}
*
- * @return an object of type T from the json. Returns {@code null} if {@code json} is at EOF.
+ * @return an object of type T from the Reader. Returns {@code null} if {@code json} is at EOF.
* @throws JsonIOException if there was a problem reading from the Reader
- * @throws JsonSyntaxException if json is not a valid representation for an object of type
- * @since 1.2
+ * @throws JsonSyntaxException if json is not a valid representation for an object of type of typeOfT
+ *
+ * @see #fromJson(String, TypeToken)
+ * @see #fromJson(Reader, Class)
+ * @since 2.10
*/
- public T fromJson(Reader json, Type typeOfT) throws JsonIOException, JsonSyntaxException {
+ public T fromJson(Reader json, TypeToken typeOfT) throws JsonIOException, JsonSyntaxException {
JsonReader jsonReader = newJsonReader(json);
- @SuppressWarnings("unchecked")
- T object = (T) fromJson(jsonReader, typeOfT);
+ T object = fromJson(jsonReader, typeOfT);
assertFullConsumption(object, jsonReader);
return object;
}
@@ -1023,10 +1123,18 @@ public final class Gson {
}
}
+ // fromJson(JsonReader, Class) is unfortunately missing and cannot be added now without breaking
+ // source compatibility in certain cases, see https://github.com/google/gson/pull/1700#discussion_r973764414
+
/**
- * Reads the next JSON value from {@code reader} and convert it to an object
+ * Reads the next JSON value from {@code reader} and converts it to an object
* of type {@code typeOfT}. Returns {@code null}, if the {@code reader} is at EOF.
- * Since Type is not parameterized by T, this method is type unsafe and should be used carefully.
+ *
+ *
Since {@code Type} is not parameterized by T, this method is not type-safe and
+ * should be used carefully. If you are creating the {@code Type} from a {@link TypeToken},
+ * prefer using {@link #fromJson(JsonReader, TypeToken)} instead since its return type is based
+ * on the {@code TypeToken} and is therefore more type-safe. If the provided type is a
+ * {@code Class} the {@code TypeToken} can be created with {@link TypeToken#get(Class)}.
*
*
Unlike the other {@code fromJson} methods, no exception is thrown if the JSON data has
* multiple top-level JSON elements, or if there is trailing data.
@@ -1035,19 +1143,59 @@ public final class Gson {
* regardless of the lenient mode setting of the provided reader. The lenient mode setting
* of the reader is restored once this method returns.
*
- * @throws JsonIOException if there was a problem writing to the Reader
- * @throws JsonSyntaxException if json is not a valid representation for an object of type
+ * @param the type of the desired object
+ * @param reader the reader whose next JSON value should be deserialized
+ * @param typeOfT The specific genericized type of src
+ * @return an object of type T from the JsonReader. Returns {@code null} if {@code reader} is at EOF.
+ * @throws JsonIOException if there was a problem reading from the JsonReader
+ * @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
+ *
+ * @see #fromJson(Reader, Type)
+ * @see #fromJson(JsonReader, TypeToken)
*/
+ @SuppressWarnings("unchecked")
public T fromJson(JsonReader reader, Type typeOfT) throws JsonIOException, JsonSyntaxException {
+ return (T) fromJson(reader, TypeToken.get(typeOfT));
+ }
+
+ /**
+ * Reads the next JSON value from {@code reader} and converts it to an object
+ * of type {@code typeOfT}. Returns {@code null}, if the {@code reader} is at EOF.
+ * This method is useful if the specified object is a generic type. For non-generic objects,
+ * {@link #fromJson(JsonReader, Type)} can be called, or {@link TypeToken#get(Class)} can
+ * be used to create the type token.
+ *
+ *
Unlike the other {@code fromJson} methods, no exception is thrown if the JSON data has
+ * multiple top-level JSON elements, or if there is trailing data.
+ *
+ *
The JSON data is parsed in {@linkplain JsonReader#setLenient(boolean) lenient mode},
+ * regardless of the lenient mode setting of the provided reader. The lenient mode setting
+ * of the reader is restored once this method returns.
+ *
+ * @param the type of the desired object
+ * @param reader the reader whose next JSON value should be deserialized
+ * @param typeOfT The specific genericized type of src. You should create an anonymous subclass of
+ * {@code TypeToken} with the specific generic type arguments. For example, to get the type for
+ * {@code Collection}, you should use:
+ *
+ * new TypeToken<Collection<Foo>>(){}
+ *
+ * @return an object of type T from the JsonReader. Returns {@code null} if {@code reader} is at EOF.
+ * @throws JsonIOException if there was a problem reading from the JsonReader
+ * @throws JsonSyntaxException if json is not a valid representation for an object of the type typeOfT
+ *
+ * @see #fromJson(Reader, TypeToken)
+ * @see #fromJson(JsonReader, Type)
+ * @since 2.10
+ */
+ public T fromJson(JsonReader reader, TypeToken typeOfT) throws JsonIOException, JsonSyntaxException {
boolean isEmpty = true;
boolean oldLenient = reader.isLenient();
reader.setLenient(lenient);
try {
reader.peek();
isEmpty = false;
- @SuppressWarnings("unchecked")
- TypeToken typeToken = (TypeToken) TypeToken.get(typeOfT);
- TypeAdapter typeAdapter = getAdapter(typeToken);
+ TypeAdapter typeAdapter = getAdapter(typeOfT);
T object = typeAdapter.read(reader);
return object;
} catch (EOFException e) {
@@ -1074,55 +1222,89 @@ public final class Gson {
}
/**
- * This method deserializes the Json read from the specified parse tree into an object of the
+ * This method deserializes the JSON read from the specified parse tree into an object of the
* specified type. It is not suitable to use if the specified class is a generic type since it
* will not have the generic type information because of the Type Erasure feature of Java.
* Therefore, this method should not be used if the desired type is a generic type. Note that
- * this method works fine if the any of the fields of the specified object are generics, just the
+ * this method works fine if any of the fields of the specified object are generics, just the
* object itself should not be a generic type. For the cases when the object is of generic type,
- * invoke {@link #fromJson(JsonElement, Type)}.
+ * invoke {@link #fromJson(JsonElement, TypeToken)}.
+ *
* @param the type of the desired object
* @param json the root of the parse tree of {@link JsonElement}s from which the object is to
* be deserialized
* @param classOfT The class of T
- * @return an object of type T from the json. Returns {@code null} if {@code json} is {@code null}
+ * @return an object of type T from the JSON. Returns {@code null} if {@code json} is {@code null}
* or if {@code json} is empty.
- * @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
+ * @throws JsonSyntaxException if json is not a valid representation for an object of type classOfT
* @since 1.3
+ *
+ * @see #fromJson(Reader, Class)
+ * @see #fromJson(JsonElement, TypeToken)
*/
public T fromJson(JsonElement json, Class classOfT) throws JsonSyntaxException {
- Object object = fromJson(json, (Type) classOfT);
+ T object = fromJson(json, TypeToken.get(classOfT));
return Primitives.wrap(classOfT).cast(object);
}
/**
- * This method deserializes the Json read from the specified parse tree into an object of the
+ * This method deserializes the JSON read from the specified parse tree into an object of the
+ * specified type. This method is useful if the specified object is a generic type. For
+ * non-generic objects, use {@link #fromJson(JsonElement, Class)} instead.
+ *
+ *
Since {@code Type} is not parameterized by T, this method is not type-safe and
+ * should be used carefully. If you are creating the {@code Type} from a {@link TypeToken},
+ * prefer using {@link #fromJson(JsonElement, TypeToken)} instead since its return type is based
+ * on the {@code TypeToken} and is therefore more type-safe.
+ *
+ * @param the type of the desired object
+ * @param json the root of the parse tree of {@link JsonElement}s from which the object is to
+ * be deserialized
+ * @param typeOfT The specific genericized type of src
+ * @return an object of type T from the JSON. Returns {@code null} if {@code json} is {@code null}
+ * or if {@code json} is empty.
+ * @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
+ * @since 1.3
+ *
+ * @see #fromJson(Reader, Type)
+ * @see #fromJson(JsonElement, Class)
+ * @see #fromJson(JsonElement, TypeToken)
+ */
+ @SuppressWarnings("unchecked")
+ public T fromJson(JsonElement json, Type typeOfT) throws JsonSyntaxException {
+ return (T) fromJson(json, TypeToken.get(typeOfT));
+ }
+
+ /**
+ * This method deserializes the JSON read from the specified parse tree into an object of the
* specified type. This method is useful if the specified object is a generic type. For
* non-generic objects, use {@link #fromJson(JsonElement, Class)} instead.
*
* @param the type of the desired object
* @param json the root of the parse tree of {@link JsonElement}s from which the object is to
* be deserialized
- * @param typeOfT The specific genericized type of src. You can obtain this type by using the
- * {@link com.google.gson.reflect.TypeToken} class. For example, to get the type for
+ * @param typeOfT The specific genericized type of src. You should create an anonymous subclass of
+ * {@code TypeToken} with the specific generic type arguments. For example, to get the type for
* {@code Collection}, you should use:
*
- * Type typeOfT = new TypeToken<Collection<Foo>>(){}.getType();
+ * new TypeToken<Collection<Foo>>(){}
*
- * @return an object of type T from the json. Returns {@code null} if {@code json} is {@code null}
+ * @return an object of type T from the JSON. Returns {@code null} if {@code json} is {@code null}
* or if {@code json} is empty.
* @throws JsonSyntaxException if json is not a valid representation for an object of type typeOfT
- * @since 1.3
+ *
+ * @see #fromJson(Reader, TypeToken)
+ * @see #fromJson(JsonElement, Class)
+ * @since 2.10
*/
- @SuppressWarnings("unchecked")
- public T fromJson(JsonElement json, Type typeOfT) throws JsonSyntaxException {
+ public T fromJson(JsonElement json, TypeToken typeOfT) throws JsonSyntaxException {
if (json == null) {
return null;
}
- return (T) fromJson(new JsonTreeReader(json), typeOfT);
+ return fromJson(new JsonTreeReader(json), typeOfT);
}
- static class FutureTypeAdapter extends TypeAdapter {
+ static class FutureTypeAdapter extends SerializationDelegatingTypeAdapter {
private TypeAdapter delegate;
public void setDelegate(TypeAdapter typeAdapter) {
@@ -1132,18 +1314,23 @@ public final class Gson {
delegate = typeAdapter;
}
- @Override public T read(JsonReader in) throws IOException {
+ private TypeAdapter delegate() {
if (delegate == null) {
- throw new IllegalStateException();
+ throw new IllegalStateException("Delegate has not been set yet");
}
- return delegate.read(in);
+ return delegate;
+ }
+
+ @Override public TypeAdapter getSerializationDelegate() {
+ return delegate();
+ }
+
+ @Override public T read(JsonReader in) throws IOException {
+ return delegate().read(in);
}
@Override public void write(JsonWriter out, T value) throws IOException {
- if (delegate == null) {
- throw new IllegalStateException();
- }
- delegate.write(out, value);
+ delegate().write(out, value);
}
}
diff --git a/gson/src/main/java/com/google/gson/GsonBuilder.java b/gson/src/main/java/com/google/gson/GsonBuilder.java
index 60276abd..03ae514f 100644
--- a/gson/src/main/java/com/google/gson/GsonBuilder.java
+++ b/gson/src/main/java/com/google/gson/GsonBuilder.java
@@ -18,6 +18,8 @@ package com.google.gson;
import static com.google.gson.internal.DefaultConfig.*;
+import com.google.gson.annotations.Since;
+import com.google.gson.annotations.Until;
import com.google.gson.internal.$Gson$Preconditions;
import com.google.gson.internal.Excluder;
import com.google.gson.internal.bind.DefaultDateTypeAdapter;
@@ -137,14 +139,25 @@ public final class GsonBuilder {
}
/**
- * Configures Gson to enable versioning support.
+ * Configures Gson to enable versioning support. Versioning support works based on the
+ * annotation types {@link Since} and {@link Until}. It allows including or excluding fields
+ * and classes based on the specified version. See the documentation of these annotation
+ * types for more information.
*
- * @param ignoreVersionsAfter any field or type marked with a version higher than this value
- * are ignored during serialization or deserialization.
+ *
By default versioning support is disabled and usage of {@code @Since} and {@code @Until}
+ * has no effect.
+ *
+ * @param version the version number to use.
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
+ * @throws IllegalArgumentException if the version number is NaN or negative
+ * @see Since
+ * @see Until
*/
- public GsonBuilder setVersion(double ignoreVersionsAfter) {
- excluder = excluder.withVersion(ignoreVersionsAfter);
+ public GsonBuilder setVersion(double version) {
+ if (Double.isNaN(version) || version < 0.0) {
+ throw new IllegalArgumentException("Invalid version: " + version);
+ }
+ excluder = excluder.withVersion(version);
return this;
}
@@ -215,8 +228,9 @@ public final class GsonBuilder {
* on the key; however, when this is called then one of the following cases
* apply:
*
- *
Maps as JSON objects
- * For this case, assume that a type adapter is registered to serialize and
+ *
Maps as JSON objects
+ *
+ *
For this case, assume that a type adapter is registered to serialize and
* deserialize some {@code Point} class, which contains an x and y coordinate,
* to/from the JSON Primitive string value {@code "(x,y)"}. The Java map would
* then be serialized as a {@link JsonObject}.
@@ -240,11 +254,12 @@ public final class GsonBuilder {
* }
* }
*
- *
Maps as JSON arrays
- * For this case, assume that a type adapter was NOT registered for some
+ *
Maps as JSON arrays
+ *
+ *
For this case, assume that a type adapter was NOT registered for some
* {@code Point} class, but rather the default Gson serialization is applied.
* In this case, some {@code new Point(2,3)} would serialize as {@code
- * {"x":2,"y":5}}.
+ * {"x":2,"y":3}}.
*
*
Given the assumption above, a {@code Map} will be
* serialize as an array of arrays (can be viewed as an entry set of pairs).
@@ -357,6 +372,10 @@ public final class GsonBuilder {
* Configures Gson to apply a specific naming strategy to an object's fields during
* serialization and deserialization.
*
+ *
The created Gson instance might only use the field naming strategy once for a
+ * field and cache the result. It is not guaranteed that the strategy will be used
+ * again every time the value of a field is serialized or deserialized.
+ *
* @param fieldNamingStrategy the naming strategy to apply to the fields
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
* @since 1.3
@@ -372,6 +391,7 @@ public final class GsonBuilder {
* @param objectToNumberStrategy the actual object-to-number strategy
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
* @see ToNumberPolicy#DOUBLE The default object-to-number strategy
+ * @since 2.8.9
*/
public GsonBuilder setObjectToNumberStrategy(ToNumberStrategy objectToNumberStrategy) {
this.objectToNumberStrategy = Objects.requireNonNull(objectToNumberStrategy);
@@ -384,6 +404,7 @@ public final class GsonBuilder {
* @param numberToNumberStrategy the actual number-to-number strategy
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
* @see ToNumberPolicy#LAZILY_PARSED_NUMBER The default number-to-number strategy
+ * @since 2.8.9
*/
public GsonBuilder setNumberToNumberStrategy(ToNumberStrategy numberToNumberStrategy) {
this.numberToNumberStrategy = Objects.requireNonNull(numberToNumberStrategy);
@@ -408,6 +429,10 @@ public final class GsonBuilder {
* JSON null is written to output, and when deserialized the JSON value is skipped and
* {@code null} is returned.
*
+ *
The created Gson instance might only use an exclusion strategy once for a field or
+ * class and cache the result. It is not guaranteed that the strategy will be used again
+ * every time the value of a field or a class is serialized or deserialized.
+ *
* @param strategies the set of strategy object to apply during object (de)serialization.
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
* @since 1.4
@@ -622,6 +647,10 @@ public final class GsonBuilder {
* is designed to handle a large number of factories, so you should consider registering
* them to be at par with registering an individual type adapter.
*
+ *
The created Gson instance might only use the factory once to create an adapter for
+ * a specific type and cache the result. It is not guaranteed that the factory will be used
+ * again every time the type is serialized or deserialized.
+ *
* @since 2.1
*/
public GsonBuilder registerTypeAdapterFactory(TypeAdapterFactory factory) {
@@ -699,6 +728,7 @@ public final class GsonBuilder {
* disabling usage of {@code Unsafe}.
*
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
+ * @since 2.9.0
*/
public GsonBuilder disableJdkUnsafe() {
this.useJdkUnsafe = false;
@@ -717,8 +747,13 @@ public final class GsonBuilder {
* all classes for which no {@link TypeAdapter} has been registered, and for which no
* built-in Gson {@code TypeAdapter} exists.
*
+ *
The created Gson instance might only use an access filter once for a class or its
+ * members and cache the result. It is not guaranteed that the filter will be used again
+ * every time a class or its members are accessed during serialization or deserialization.
+ *
* @param filter filter to add
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
+ * @since 2.9.1
*/
public GsonBuilder addReflectionAccessFilter(ReflectionAccessFilter filter) {
Objects.requireNonNull(filter);
diff --git a/gson/src/main/java/com/google/gson/JsonArray.java b/gson/src/main/java/com/google/gson/JsonArray.java
index d861cfb3..370b323f 100644
--- a/gson/src/main/java/com/google/gson/JsonArray.java
+++ b/gson/src/main/java/com/google/gson/JsonArray.java
@@ -16,6 +16,7 @@
package com.google.gson;
+import com.google.gson.internal.NonNullElementWrapperList;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.ArrayList;
@@ -28,11 +29,14 @@ import java.util.List;
* elements are added is preserved. This class does not support {@code null} values. If {@code null}
* is provided as element argument to any of the methods, it is converted to a {@link JsonNull}.
*
+ *
{@code JsonArray} only implements the {@link Iterable} interface but not the {@link List}
+ * interface. A {@code List} view of it can be obtained with {@link #asList()}.
+ *
* @author Inderjeet Singh
* @author Joel Leitch
*/
public final class JsonArray extends JsonElement implements Iterable {
- private final List elements;
+ private final ArrayList elements;
/**
* Creates an empty JsonArray.
@@ -48,6 +52,7 @@ public final class JsonArray extends JsonElement implements IterableThe {@code List} does not permit {@code null} elements. Unlike {@code JsonArray}'s
+ * {@code null} handling, a {@link NullPointerException} is thrown when trying to add {@code null}.
+ * Use {@link JsonNull} for JSON null values.
+ *
+ * @return mutable {@code List} view
+ * @since 2.10
+ */
+ public List asList() {
+ return new NonNullElementWrapperList<>(elements);
+ }
+
/**
* Returns whether the other object is equal to this. This method only considers
* the other object to be equal if it is an instance of {@code JsonArray} and has
diff --git a/gson/src/main/java/com/google/gson/JsonObject.java b/gson/src/main/java/com/google/gson/JsonObject.java
index 4b600510..60dac41c 100644
--- a/gson/src/main/java/com/google/gson/JsonObject.java
+++ b/gson/src/main/java/com/google/gson/JsonObject.java
@@ -27,6 +27,9 @@ import java.util.Set;
* This class does not support {@code null} values. If {@code null} is provided as value argument
* to any of the methods, it is converted to a {@link JsonNull}.
*
+ *
{@code JsonObject} does not implement the {@link Map} interface, but a {@code Map} view
+ * of it can be obtained with {@link #asMap()}.
+ *
* @author Inderjeet Singh
* @author Joel Leitch
*/
@@ -146,6 +149,7 @@ public final class JsonObject extends JsonElement {
* Returns the number of key/value pairs in the object.
*
* @return the number of key/value pairs in the object.
+ * @since 2.7
*/
public int size() {
return members.size();
@@ -207,6 +211,22 @@ public final class JsonObject extends JsonElement {
return (JsonObject) members.get(memberName);
}
+ /**
+ * Returns a mutable {@link Map} view of this {@code JsonObject}. Changes to the {@code Map}
+ * are visible in this {@code JsonObject} and the other way around.
+ *
+ *
The {@code Map} does not permit {@code null} keys or values. Unlike {@code JsonObject}'s
+ * {@code null} handling, a {@link NullPointerException} is thrown when trying to add {@code null}.
+ * Use {@link JsonNull} for JSON null values.
+ *
+ * @return mutable {@code Map} view
+ * @since 2.10
+ */
+ public Map asMap() {
+ // It is safe to expose the underlying map because it disallows null keys and values
+ return members;
+ }
+
/**
* Returns whether the other object is equal to this. This method only considers
* the other object to be equal if it is an instance of {@code JsonObject} and has
diff --git a/gson/src/main/java/com/google/gson/JsonParser.java b/gson/src/main/java/com/google/gson/JsonParser.java
index d3508c10..5b800420 100644
--- a/gson/src/main/java/com/google/gson/JsonParser.java
+++ b/gson/src/main/java/com/google/gson/JsonParser.java
@@ -45,6 +45,7 @@ public final class JsonParser {
* @param json JSON text
* @return a parse tree of {@link JsonElement}s corresponding to the specified JSON
* @throws JsonParseException if the specified text is not valid JSON
+ * @since 2.8.6
*/
public static JsonElement parseString(String json) throws JsonSyntaxException {
return parseReader(new StringReader(json));
@@ -61,6 +62,7 @@ public final class JsonParser {
* @return a parse tree of {@link JsonElement}s corresponding to the specified JSON
* @throws JsonParseException if there is an IOException or if the specified
* text is not valid JSON
+ * @since 2.8.6
*/
public static JsonElement parseReader(Reader reader) throws JsonIOException, JsonSyntaxException {
try {
@@ -90,6 +92,7 @@ public final class JsonParser {
*
* @throws JsonParseException if there is an IOException or if the specified
* text is not valid JSON
+ * @since 2.8.6
*/
public static JsonElement parseReader(JsonReader reader)
throws JsonIOException, JsonSyntaxException {
diff --git a/gson/src/main/java/com/google/gson/ReflectionAccessFilter.java b/gson/src/main/java/com/google/gson/ReflectionAccessFilter.java
index b787ae89..254d2e5d 100644
--- a/gson/src/main/java/com/google/gson/ReflectionAccessFilter.java
+++ b/gson/src/main/java/com/google/gson/ReflectionAccessFilter.java
@@ -1,8 +1,7 @@
package com.google.gson;
-import java.lang.reflect.AccessibleObject;
-
import com.google.gson.internal.ReflectionAccessFilterHelper;
+import java.lang.reflect.AccessibleObject;
/**
* Filter for determining whether reflection based serialization and
@@ -28,10 +27,13 @@ import com.google.gson.internal.ReflectionAccessFilterHelper;
* fields and classes.
*
* @see GsonBuilder#addReflectionAccessFilter(ReflectionAccessFilter)
+ * @since 2.9.1
*/
public interface ReflectionAccessFilter {
/**
* Result of a filter check.
+ *
+ * @since 2.9.1
*/
enum FilterResult {
/**
diff --git a/gson/src/main/java/com/google/gson/ToNumberPolicy.java b/gson/src/main/java/com/google/gson/ToNumberPolicy.java
index bd70213b..86892984 100644
--- a/gson/src/main/java/com/google/gson/ToNumberPolicy.java
+++ b/gson/src/main/java/com/google/gson/ToNumberPolicy.java
@@ -16,12 +16,11 @@
package com.google.gson;
-import java.io.IOException;
-import java.math.BigDecimal;
-
import com.google.gson.internal.LazilyParsedNumber;
import com.google.gson.stream.JsonReader;
import com.google.gson.stream.MalformedJsonException;
+import java.io.IOException;
+import java.math.BigDecimal;
/**
* An enumeration that defines two standard number reading strategies and a couple of
@@ -29,6 +28,7 @@ import com.google.gson.stream.MalformedJsonException;
* {@link Object} and {@link Number}.
*
* @see ToNumberStrategy
+ * @since 2.8.9
*/
public enum ToNumberPolicy implements ToNumberStrategy {
diff --git a/gson/src/main/java/com/google/gson/ToNumberStrategy.java b/gson/src/main/java/com/google/gson/ToNumberStrategy.java
index 3cd84fa5..ae742219 100644
--- a/gson/src/main/java/com/google/gson/ToNumberStrategy.java
+++ b/gson/src/main/java/com/google/gson/ToNumberStrategy.java
@@ -16,9 +16,8 @@
package com.google.gson;
-import java.io.IOException;
-
import com.google.gson.stream.JsonReader;
+import java.io.IOException;
/**
* A strategy that is used to control how numbers should be deserialized for {@link Object} and {@link Number}
@@ -56,6 +55,7 @@ import com.google.gson.stream.JsonReader;
* @see ToNumberPolicy
* @see GsonBuilder#setObjectToNumberStrategy(ToNumberStrategy)
* @see GsonBuilder#setNumberToNumberStrategy(ToNumberStrategy)
+ * @since 2.8.9
*/
public interface ToNumberStrategy {
diff --git a/gson/src/main/java/com/google/gson/TypeAdapter.java b/gson/src/main/java/com/google/gson/TypeAdapter.java
index 37f22b8e..98e1668a 100644
--- a/gson/src/main/java/com/google/gson/TypeAdapter.java
+++ b/gson/src/main/java/com/google/gson/TypeAdapter.java
@@ -30,7 +30,7 @@ import java.io.Writer;
/**
* Converts Java objects to and from JSON.
*
- *
Defining a type's JSON form
+ *
Defining a type's JSON form
* By default Gson converts application classes to JSON using its built-in type
* adapters. If Gson's default JSON conversion isn't appropriate for a type,
* extend this class to customize the conversion. Here's an example of a type
@@ -96,7 +96,7 @@ import java.io.Writer;
*/
// non-Javadoc:
//
-//
JSON Conversion
+//
JSON Conversion
//
A type adapter registered with Gson is automatically invoked while serializing
// or deserializing JSON. However, you can also use type adapters directly to serialize
// and deserialize JSON. Here is an example for deserialization:
{@code
@@ -118,6 +118,9 @@ import java.io.Writer;
//
public abstract class TypeAdapter {
+ public TypeAdapter() {
+ }
+
/**
* Writes one JSON value (an array, object, string, number, boolean or null)
* for {@code value}.
diff --git a/gson/src/main/java/com/google/gson/TypeAdapterFactory.java b/gson/src/main/java/com/google/gson/TypeAdapterFactory.java
index c12429e9..75fdddbf 100644
--- a/gson/src/main/java/com/google/gson/TypeAdapterFactory.java
+++ b/gson/src/main/java/com/google/gson/TypeAdapterFactory.java
@@ -22,6 +22,7 @@ import com.google.gson.reflect.TypeToken;
* Creates type adapters for set of related types. Type adapter factories are
* most useful when several types share similar structure in their JSON form.
*
+ *
Examples
*
Example: Converting enums to lowercase
* In this example, we implement a factory that creates type adapters for all
* enums. The type adapters will write enums in lowercase, despite the fact
@@ -90,7 +91,7 @@ import com.google.gson.reflect.TypeToken;
* If multiple factories support the same type, the factory registered earlier
* takes precedence.
*
- *
Example: composing other type adapters
+ *
Example: Composing other type adapters
* In this example we implement a factory for Guava's {@code Multiset}
* collection type. The factory can be used to create type adapters for
* multisets of any element type: the type adapter for {@code
diff --git a/gson/src/main/java/com/google/gson/annotations/JsonAdapter.java b/gson/src/main/java/com/google/gson/annotations/JsonAdapter.java
index a01d77a6..d1685759 100644
--- a/gson/src/main/java/com/google/gson/annotations/JsonAdapter.java
+++ b/gson/src/main/java/com/google/gson/annotations/JsonAdapter.java
@@ -16,6 +16,7 @@
package com.google.gson.annotations;
+import com.google.gson.Gson;
import com.google.gson.JsonDeserializer;
import com.google.gson.JsonSerializer;
import com.google.gson.TypeAdapter;
@@ -60,7 +61,7 @@ import java.lang.annotation.Target;
*
*
* Since User class specified UserJsonAdapter.class in @JsonAdapter annotation, it
- * will automatically be invoked to serialize/deserialize User instances.
+ * will automatically be invoked to serialize/deserialize User instances.
*
*
Here is an example of how to apply this annotation to a field.
*
The class referenced by this annotation must be either a {@link
* TypeAdapter} or a {@link TypeAdapterFactory}, or must implement one
- * or both of {@link JsonDeserializer} or {@link JsonSerializer}.
- * Using {@link TypeAdapterFactory} makes it possible to delegate
- * to the enclosing {@code Gson} instance.
+ * or both of {@link JsonDeserializer} or {@link JsonSerializer}.
+ * Using {@link TypeAdapterFactory} makes it possible to delegate
+ * to the enclosing {@link Gson} instance.
+ *
+ *
{@code Gson} instances might cache the adapter they create for
+ * a {@code @JsonAdapter} annotation. It is not guaranteed that a new
+ * adapter is created every time the annotated class or field is serialized
+ * or deserialized.
*
* @since 2.3
*
diff --git a/gson/src/main/java/com/google/gson/annotations/Since.java b/gson/src/main/java/com/google/gson/annotations/Since.java
index e23b6ec9..a7e51fc1 100644
--- a/gson/src/main/java/com/google/gson/annotations/Since.java
+++ b/gson/src/main/java/com/google/gson/annotations/Since.java
@@ -16,6 +16,7 @@
package com.google.gson.annotations;
+import com.google.gson.GsonBuilder;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
@@ -24,12 +25,11 @@ import java.lang.annotation.Target;
/**
* An annotation that indicates the version number since a member or a type has been present.
- * This annotation is useful to manage versioning of your Json classes for a web-service.
+ * This annotation is useful to manage versioning of your JSON classes for a web-service.
*
*
* This annotation has no effect unless you build {@link com.google.gson.Gson} with a
- * {@link com.google.gson.GsonBuilder} and invoke
- * {@link com.google.gson.GsonBuilder#setVersion(double)} method.
+ * {@code GsonBuilder} and invoke the {@link GsonBuilder#setVersion(double)} method.
*
*
Here is an example of how this annotation is meant to be used:
*
@@ -50,14 +50,16 @@ import java.lang.annotation.Target;
*
* @author Inderjeet Singh
* @author Joel Leitch
+ * @see GsonBuilder#setVersion(double)
+ * @see Until
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.TYPE})
public @interface Since {
/**
- * the value indicating a version number since this member
- * or type has been present.
+ * The value indicating a version number since this member or type has been present.
+ * The number is inclusive; annotated elements will be included if {@code gsonVersion >= value}.
*/
double value();
}
diff --git a/gson/src/main/java/com/google/gson/annotations/Until.java b/gson/src/main/java/com/google/gson/annotations/Until.java
index 7c61d104..a5fcabd4 100644
--- a/gson/src/main/java/com/google/gson/annotations/Until.java
+++ b/gson/src/main/java/com/google/gson/annotations/Until.java
@@ -16,6 +16,7 @@
package com.google.gson.annotations;
+import com.google.gson.GsonBuilder;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
@@ -24,14 +25,13 @@ import java.lang.annotation.Target;
/**
* An annotation that indicates the version number until a member or a type should be present.
- * Basically, if Gson is created with a version number that exceeds the value stored in the
- * {@code Until} annotation then the field will be ignored from the JSON output. This annotation
- * is useful to manage versioning of your JSON classes for a web-service.
+ * Basically, if Gson is created with a version number that is equal to or exceeds the value
+ * stored in the {@code Until} annotation then the field will be ignored from the JSON output.
+ * This annotation is useful to manage versioning of your JSON classes for a web-service.
*
*
* This annotation has no effect unless you build {@link com.google.gson.Gson} with a
- * {@link com.google.gson.GsonBuilder} and invoke
- * {@link com.google.gson.GsonBuilder#setVersion(double)} method.
+ * {@code GsonBuilder} and invoke the {@link GsonBuilder#setVersion(double)} method.
*
*
Here is an example of how this annotation is meant to be used:
*
@@ -47,12 +47,14 @@ import java.lang.annotation.Target;
* methods will use all the fields for serialization and deserialization. However, if you created
* Gson with {@code Gson gson = new GsonBuilder().setVersion(1.2).create()} then the
* {@code toJson()} and {@code fromJson()} methods of Gson will exclude the {@code emailAddress}
- * and {@code password} fields from the example above, because the version number passed to the
+ * and {@code password} fields from the example above, because the version number passed to the
* GsonBuilder, {@code 1.2}, exceeds the version number set on the {@code Until} annotation,
* {@code 1.1}, for those fields.
*
* @author Inderjeet Singh
* @author Joel Leitch
+ * @see GsonBuilder#setVersion(double)
+ * @see Since
* @since 1.3
*/
@Documented
@@ -61,8 +63,8 @@ import java.lang.annotation.Target;
public @interface Until {
/**
- * the value indicating a version number until this member
- * or type should be ignored.
+ * The value indicating a version number until this member or type should be be included.
+ * The number is exclusive; annotated elements will be included if {@code gsonVersion < value}.
*/
double value();
}
diff --git a/gson/src/main/java/com/google/gson/internal/ConstructorConstructor.java b/gson/src/main/java/com/google/gson/internal/ConstructorConstructor.java
index 68b2bd64..115a2a09 100644
--- a/gson/src/main/java/com/google/gson/internal/ConstructorConstructor.java
+++ b/gson/src/main/java/com/google/gson/internal/ConstructorConstructor.java
@@ -61,6 +61,25 @@ public final class ConstructorConstructor {
this.reflectionFilters = reflectionFilters;
}
+ /**
+ * Check if the class can be instantiated by Unsafe allocator. If the instance has interface or abstract modifiers
+ * return an exception message.
+ * @param c instance of the class to be checked
+ * @return if instantiable {@code null}, else a non-{@code null} exception message
+ */
+ static String checkInstantiable(Class c) {
+ int modifiers = c.getModifiers();
+ if (Modifier.isInterface(modifiers)) {
+ return "Interfaces can't be instantiated! Register an InstanceCreator "
+ + "or a TypeAdapter for this type. Interface name: " + c.getName();
+ }
+ if (Modifier.isAbstract(modifiers)) {
+ return "Abstract classes can't be instantiated! Register an InstanceCreator "
+ + "or a TypeAdapter for this type. Class name: " + c.getName();
+ }
+ return null;
+ }
+
public ObjectConstructor get(TypeToken typeToken) {
final Type type = typeToken.getType();
final Class rawType = typeToken.getRawType();
@@ -110,7 +129,7 @@ public final class ConstructorConstructor {
// Check whether type is instantiable; otherwise ReflectionAccessFilter recommendation
// of adjusting filter suggested below is irrelevant since it would not solve the problem
- final String exceptionMessage = UnsafeAllocator.checkInstantiable(rawType);
+ final String exceptionMessage = checkInstantiable(rawType);
if (exceptionMessage != null) {
return new ObjectConstructor() {
@Override public T construct() {
@@ -242,14 +261,17 @@ public final class ConstructorConstructor {
@SuppressWarnings("unchecked") // T is the same raw type as is requested
T newInstance = (T) constructor.newInstance();
return newInstance;
- } catch (InstantiationException e) {
- // TODO: JsonParseException ?
- throw new RuntimeException("Failed to invoke " + constructor + " with no args", e);
+ }
+ // Note: InstantiationException should be impossible because check at start of method made sure
+ // that class is not abstract
+ catch (InstantiationException e) {
+ throw new RuntimeException("Failed to invoke constructor '" + ReflectionHelper.constructorToString(constructor) + "'"
+ + " with no args", e);
} catch (InvocationTargetException e) {
- // TODO: don't wrap if cause is unchecked!
+ // TODO: don't wrap if cause is unchecked?
// TODO: JsonParseException ?
- throw new RuntimeException("Failed to invoke " + constructor + " with no args",
- e.getTargetException());
+ throw new RuntimeException("Failed to invoke constructor '" + ReflectionHelper.constructorToString(constructor) + "'"
+ + " with no args", e.getCause());
} catch (IllegalAccessException e) {
throw ReflectionHelper.createExceptionForUnexpectedIllegalAccess(e);
}
@@ -342,11 +364,10 @@ public final class ConstructorConstructor {
private ObjectConstructor newUnsafeAllocator(final Class rawType) {
if (useJdkUnsafe) {
return new ObjectConstructor() {
- private final UnsafeAllocator unsafeAllocator = UnsafeAllocator.create();
@Override public T construct() {
try {
@SuppressWarnings("unchecked")
- T newInstance = (T) unsafeAllocator.newInstance(rawType);
+ T newInstance = (T) UnsafeAllocator.INSTANCE.newInstance(rawType);
return newInstance;
} catch (Exception e) {
throw new RuntimeException(("Unable to create instance of " + rawType + ". "
diff --git a/gson/src/main/java/com/google/gson/internal/Excluder.java b/gson/src/main/java/com/google/gson/internal/Excluder.java
index 8d8a25f4..03bd45cb 100644
--- a/gson/src/main/java/com/google/gson/internal/Excluder.java
+++ b/gson/src/main/java/com/google/gson/internal/Excluder.java
@@ -240,9 +240,7 @@ public final class Excluder implements TypeAdapterFactory, Cloneable {
private boolean isValidSince(Since annotation) {
if (annotation != null) {
double annotationVersion = annotation.value();
- if (annotationVersion > version) {
- return false;
- }
+ return version >= annotationVersion;
}
return true;
}
@@ -250,9 +248,7 @@ public final class Excluder implements TypeAdapterFactory, Cloneable {
private boolean isValidUntil(Until annotation) {
if (annotation != null) {
double annotationVersion = annotation.value();
- if (annotationVersion <= version) {
- return false;
- }
+ return version < annotationVersion;
}
return true;
}
diff --git a/gson/src/main/java/com/google/gson/internal/NonNullElementWrapperList.java b/gson/src/main/java/com/google/gson/internal/NonNullElementWrapperList.java
new file mode 100644
index 00000000..b3017430
--- /dev/null
+++ b/gson/src/main/java/com/google/gson/internal/NonNullElementWrapperList.java
@@ -0,0 +1,98 @@
+package com.google.gson.internal;
+
+import java.util.AbstractList;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Objects;
+import java.util.RandomAccess;
+
+/**
+ * {@link List} which wraps another {@code List} but prevents insertion of
+ * {@code null} elements. Methods which only perform checks with the element
+ * argument (e.g. {@link #contains(Object)}) do not throw exceptions for
+ * {@code null} arguments.
+ */
+public class NonNullElementWrapperList extends AbstractList implements RandomAccess {
+ // Explicitly specify ArrayList as type to guarantee that delegate implements RandomAccess
+ private final ArrayList delegate;
+
+ public NonNullElementWrapperList(ArrayList delegate) {
+ this.delegate = Objects.requireNonNull(delegate);
+ }
+
+ @Override public E get(int index) {
+ return delegate.get(index);
+ }
+
+ @Override public int size() {
+ return delegate.size();
+ }
+
+ private E nonNull(E element) {
+ if (element == null) {
+ throw new NullPointerException("Element must be non-null");
+ }
+ return element;
+ }
+
+ @Override public E set(int index, E element) {
+ return delegate.set(index, nonNull(element));
+ }
+
+ @Override public void add(int index, E element) {
+ delegate.add(index, nonNull(element));
+ }
+
+ @Override public E remove(int index) {
+ return delegate.remove(index);
+ }
+
+ /* The following methods are overridden because their default implementation is inefficient */
+
+ @Override public void clear() {
+ delegate.clear();
+ }
+
+ @Override public boolean remove(Object o) {
+ return delegate.remove(o);
+ }
+
+ @Override public boolean removeAll(Collection c) {
+ return delegate.removeAll(c);
+ }
+
+ @Override public boolean retainAll(Collection c) {
+ return delegate.retainAll(c);
+ }
+
+ @Override public boolean contains(Object o) {
+ return delegate.contains(o);
+ }
+
+ @Override public int indexOf(Object o) {
+ return delegate.indexOf(o);
+ }
+
+ @Override public int lastIndexOf(Object o) {
+ return delegate.lastIndexOf(o);
+ }
+
+ @Override public Object[] toArray() {
+ return delegate.toArray();
+ }
+
+ @Override public T[] toArray(T[] a) {
+ return delegate.toArray(a);
+ }
+
+ @Override public boolean equals(Object o) {
+ return delegate.equals(o);
+ }
+
+ @Override public int hashCode() {
+ return delegate.hashCode();
+ }
+
+ // TODO: Once Gson targets Java 8 also override List.sort
+}
diff --git a/gson/src/main/java/com/google/gson/internal/UnsafeAllocator.java b/gson/src/main/java/com/google/gson/internal/UnsafeAllocator.java
index 429bac6b..fae6f802 100644
--- a/gson/src/main/java/com/google/gson/internal/UnsafeAllocator.java
+++ b/gson/src/main/java/com/google/gson/internal/UnsafeAllocator.java
@@ -20,7 +20,6 @@ import java.io.ObjectInputStream;
import java.io.ObjectStreamClass;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
-import java.lang.reflect.Modifier;
/**
* Do sneaky things to allocate objects without invoking their constructors.
@@ -31,38 +30,21 @@ import java.lang.reflect.Modifier;
public abstract class UnsafeAllocator {
public abstract T newInstance(Class c) throws Exception;
- /**
- * Check if the class can be instantiated by Unsafe allocator. If the instance has interface or abstract modifiers
- * return an exception message.
- * @param c instance of the class to be checked
- * @return if instantiable {@code null}, else a non-{@code null} exception message
- */
- static String checkInstantiable(Class c) {
- int modifiers = c.getModifiers();
- if (Modifier.isInterface(modifiers)) {
- return "Interfaces can't be instantiated! Register an InstanceCreator "
- + "or a TypeAdapter for this type. Interface name: " + c.getName();
- }
- if (Modifier.isAbstract(modifiers)) {
- return "Abstract classes can't be instantiated! Register an InstanceCreator "
- + "or a TypeAdapter for this type. Class name: " + c.getName();
- }
- return null;
- }
-
/**
* Asserts that the class is instantiable. This check should have already occurred
* in {@link ConstructorConstructor}; this check here acts as safeguard since trying
* to use Unsafe for non-instantiable classes might crash the JVM on some devices.
*/
private static void assertInstantiable(Class c) {
- String exceptionMessage = checkInstantiable(c);
+ String exceptionMessage = ConstructorConstructor.checkInstantiable(c);
if (exceptionMessage != null) {
throw new AssertionError("UnsafeAllocator is used for non-instantiable type: " + exceptionMessage);
}
}
- public static UnsafeAllocator create() {
+ public static final UnsafeAllocator INSTANCE = create();
+
+ private static UnsafeAllocator create() {
// try JVM
// public class Unsafe {
// public Object allocateInstance(Class type);
diff --git a/gson/src/main/java/com/google/gson/internal/bind/JsonTreeReader.java b/gson/src/main/java/com/google/gson/internal/bind/JsonTreeReader.java
index 4cd24e2d..88e654c8 100644
--- a/gson/src/main/java/com/google/gson/internal/bind/JsonTreeReader.java
+++ b/gson/src/main/java/com/google/gson/internal/bind/JsonTreeReader.java
@@ -93,6 +93,7 @@ public final class JsonTreeReader extends JsonReader {
@Override public void endObject() throws IOException {
expect(JsonToken.END_OBJECT);
+ pathNames[stackSize - 1] = null; // Free the last path name so that it can be garbage collected
popStack(); // empty iterator
popStack(); // object
if (stackSize > 0) {
@@ -165,16 +166,20 @@ public final class JsonTreeReader extends JsonReader {
}
}
- @Override public String nextName() throws IOException {
+ private String nextName(boolean skipName) throws IOException {
expect(JsonToken.NAME);
Iterator i = (Iterator) peekStack();
Map.Entry entry = (Map.Entry) i.next();
String result = (String) entry.getKey();
- pathNames[stackSize - 1] = result;
+ pathNames[stackSize - 1] = skipName ? "" : result;
push(entry.getValue());
return result;
}
+ @Override public String nextName() throws IOException {
+ return nextName(false);
+ }
+
@Override public String nextString() throws IOException {
JsonToken token = peek();
if (token != JsonToken.STRING && token != JsonToken.NUMBER) {
@@ -269,17 +274,26 @@ public final class JsonTreeReader extends JsonReader {
}
@Override public void skipValue() throws IOException {
- if (peek() == JsonToken.NAME) {
- nextName();
- pathNames[stackSize - 2] = "null";
- } else {
- popStack();
- if (stackSize > 0) {
- pathNames[stackSize - 1] = "null";
- }
- }
- if (stackSize > 0) {
- pathIndices[stackSize - 1]++;
+ JsonToken peeked = peek();
+ switch (peeked) {
+ case NAME:
+ @SuppressWarnings("unused")
+ String unused = nextName(true);
+ break;
+ case END_ARRAY:
+ endArray();
+ throw new IllegalStateException("Attempt to skip led outside its parent");
+ case END_OBJECT:
+ endObject();
+ throw new IllegalStateException("Attempt to skip led outside its parent");
+ case END_DOCUMENT:
+ throw new IllegalStateException("Attempt to skip led outside the document");
+ default:
+ popStack();
+ if (stackSize > 0) {
+ pathIndices[stackSize - 1]++;
+ }
+ break;
}
}
diff --git a/gson/src/main/java/com/google/gson/internal/bind/MapTypeAdapterFactory.java b/gson/src/main/java/com/google/gson/internal/bind/MapTypeAdapterFactory.java
index 166bae0f..78045ccf 100644
--- a/gson/src/main/java/com/google/gson/internal/bind/MapTypeAdapterFactory.java
+++ b/gson/src/main/java/com/google/gson/internal/bind/MapTypeAdapterFactory.java
@@ -40,7 +40,7 @@ import java.util.Map;
/**
* Adapts maps to either JSON objects or JSON arrays.
*
- *
Maps as JSON objects
+ *
Maps as JSON objects
* For primitive keys or when complex map key serialization is not enabled, this
* converts Java {@link Map Maps} to JSON Objects. This requires that map keys
* can be serialized as strings; this is insufficient for some key types. For
@@ -65,7 +65,7 @@ import java.util.Map;
* at com.google.gson.ObjectNavigator.navigateClassFields
* ...
*
- *
Maps as JSON arrays
+ *
Maps as JSON arrays
* An alternative approach taken by this type adapter when it is required and
* complex map key serialization is enabled is to encode maps as arrays of map
* entries. Each map entry is a two element array containing a key and a value.
diff --git a/gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java b/gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java
index 31a44e1a..5ddac50e 100644
--- a/gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java
+++ b/gson/src/main/java/com/google/gson/internal/bind/ReflectiveTypeAdapterFactory.java
@@ -19,6 +19,7 @@ package com.google.gson.internal.bind;
import com.google.gson.FieldNamingStrategy;
import com.google.gson.Gson;
import com.google.gson.JsonIOException;
+import com.google.gson.JsonParseException;
import com.google.gson.JsonSyntaxException;
import com.google.gson.ReflectionAccessFilter;
import com.google.gson.ReflectionAccessFilter.FilterResult;
@@ -38,11 +39,18 @@ import com.google.gson.stream.JsonReader;
import com.google.gson.stream.JsonToken;
import com.google.gson.stream.JsonWriter;
import java.io.IOException;
+import java.lang.reflect.AccessibleObject;
+import java.lang.reflect.Constructor;
import java.lang.reflect.Field;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Member;
+import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.lang.reflect.Type;
import java.util.ArrayList;
+import java.util.Arrays;
import java.util.Collections;
+import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
@@ -88,44 +96,59 @@ public final class ReflectiveTypeAdapterFactory implements TypeAdapterFactory {
List fieldNames = new ArrayList<>(alternates.length + 1);
fieldNames.add(serializedName);
- for (String alternate : alternates) {
- fieldNames.add(alternate);
- }
+ Collections.addAll(fieldNames, alternates);
return fieldNames;
}
- @Override public TypeAdapter create(Gson gson, final TypeToken type) {
+ @Override
+ public TypeAdapter create(Gson gson, final TypeToken type) {
Class raw = type.getRawType();
if (!Object.class.isAssignableFrom(raw)) {
return null; // it's a primitive!
}
- FilterResult filterResult = ReflectionAccessFilterHelper.getFilterResult(reflectionFilters, raw);
+ FilterResult filterResult =
+ ReflectionAccessFilterHelper.getFilterResult(reflectionFilters, raw);
if (filterResult == FilterResult.BLOCK_ALL) {
- throw new JsonIOException("ReflectionAccessFilter does not permit using reflection for "
- + raw + ". Register a TypeAdapter for this type or adjust the access filter.");
+ throw new JsonIOException(
+ "ReflectionAccessFilter does not permit using reflection for " + raw
+ + ". Register a TypeAdapter for this type or adjust the access filter.");
}
boolean blockInaccessible = filterResult == FilterResult.BLOCK_INACCESSIBLE;
+ // If the type is actually a Java Record, we need to use the RecordAdapter instead. This will always be false
+ // on JVMs that do not support records.
+ if (ReflectionHelper.isRecord(raw)) {
+ @SuppressWarnings("unchecked")
+ TypeAdapter adapter = (TypeAdapter) new RecordAdapter<>(raw,
+ getBoundFields(gson, type, raw, blockInaccessible, true), blockInaccessible);
+ return adapter;
+ }
+
ObjectConstructor constructor = constructorConstructor.get(type);
- return new Adapter<>(constructor, getBoundFields(gson, type, raw, blockInaccessible));
+ return new FieldReflectionAdapter<>(constructor, getBoundFields(gson, type, raw, blockInaccessible, false));
}
- private static void checkAccessible(Object object, Field field) {
- if (!ReflectionAccessFilterHelper.canAccess(field, Modifier.isStatic(field.getModifiers()) ? null : object)) {
- throw new JsonIOException("Field '" + field.getDeclaringClass().getName() + "#"
- + field.getName() + "' is not accessible and ReflectionAccessFilter does not "
- + "permit making it accessible. Register a TypeAdapter for the declaring type "
- + "or adjust the access filter.");
+ private static void checkAccessible(Object object, M member) {
+ if (!ReflectionAccessFilterHelper.canAccess(member, Modifier.isStatic(member.getModifiers()) ? null : object)) {
+ String memberDescription = ReflectionHelper.getAccessibleObjectDescription(member, true);
+ throw new JsonIOException(memberDescription + " is not accessible and ReflectionAccessFilter does not"
+ + " permit making it accessible. Register a TypeAdapter for the declaring type, adjust the"
+ + " access filter or increase the visibility of the element and its declaring type.");
}
}
private ReflectiveTypeAdapterFactory.BoundField createBoundField(
- final Gson context, final Field field, final String name,
+ final Gson context, final Field field, final Method accessor, final String name,
final TypeToken fieldType, boolean serialize, boolean deserialize,
final boolean blockInaccessible) {
+
final boolean isPrimitive = Primitives.isPrimitive(fieldType.getRawType());
+
+ int modifiers = field.getModifiers();
+ final boolean isStaticFinalField = Modifier.isStatic(modifiers) && Modifier.isFinal(modifiers);
+
JsonAdapter annotation = field.getAnnotation(JsonAdapter.class);
TypeAdapter mapped = null;
if (annotation != null) {
@@ -138,16 +161,32 @@ public final class ReflectiveTypeAdapterFactory implements TypeAdapterFactory {
@SuppressWarnings("unchecked")
final TypeAdapter