Merge branch 'main' into marcono1234/JsonAdapter-getDelegateAdapter

Troubleshooting.md

@@ -127,7 +127,7 @@ For example, let's assume you want to deserialize the following JSON data:
 }
 ```
 
-This will fail with an exception similar to this one: `MalformedJsonException: Use JsonReader.setLenient(true) to accept malformed JSON at line 5 column 4 path $.languages[2]`  
+This will fail with an exception similar to this one: `MalformedJsonException: Use JsonReader.setStrictness(Strictness.LENIENT) to accept malformed JSON at line 5 column 4 path $.languages[2]`  
 The problem here is the trailing comma (`,`) after `"French"`, trailing commas are not allowed by the JSON specification. The location information "line 5 column 4" points to the `]` in the JSON data (with some slight inaccuracies) because Gson expected another value after `,` instead of the closing `]`. The JSONPath `$.languages[2]` in the exception message also points there: `$.` refers to the root object, `languages` refers to its member of that name and `[2]` refers to the (missing) third value in the JSON array value of that member (numbering starts at 0, so it is `[2]` instead of `[3]`).  
 The proper solution here is to fix the malformed JSON data.
 
@@ -147,9 +147,12 @@ To spot syntax errors in the JSON data easily you can open it in an editor with
 
 **Reason:** Due to legacy reasons Gson performs parsing by default in lenient mode
 
-**Solution:** See [`Gson` class documentation](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/Gson.html#default-lenient) section "Lenient JSON handling"
-
-Note: Even in non-lenient mode Gson deviates slightly from the JSON specification, see [`JsonReader.setLenient`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/stream/JsonReader.html#setLenient(boolean)) for more details.
+**Solution:** If you are using Gson 2.11.0 or newer, call [`GsonBuilder.setStrictness`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/GsonBuilder.html#setStrictness(com.google.gson.Strictness)),
+[`JsonReader.setStrictness`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/stream/JsonReader.html#setStrictness(com.google.gson.Strictness))
+and [`JsonWriter.setStrictness`](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/stream/JsonWriter.html#setStrictness(com.google.gson.Strictness))
+with `Strictness.STRICT` to overwrite the default lenient behavior of `Gson` and make these classes strictly adhere to the JSON specification.
+Otherwise if you are using an older Gson version, see the [`Gson` class documentation](https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/Gson.html#default-lenient)
+section "JSON Strictness handling" for alternative solutions.
 
 ## <a id="unexpected-json-structure"></a> `IllegalStateException`: "Expected ... but was ..."
 

gson/src/main/java/com/google/gson/GsonBuilder.java

@@ -21,14 +21,15 @@
 import static com.google.gson.Gson.DEFAULT_ESCAPE_HTML;
 import static com.google.gson.Gson.DEFAULT_FORMATTING_STYLE;
 import static com.google.gson.Gson.DEFAULT_JSON_NON_EXECUTABLE;
-import static com.google.gson.Gson.DEFAULT_LENIENT;
 import static com.google.gson.Gson.DEFAULT_NUMBER_TO_NUMBER_STRATEGY;
 import static com.google.gson.Gson.DEFAULT_OBJECT_TO_NUMBER_STRATEGY;
 import static com.google.gson.Gson.DEFAULT_SERIALIZE_NULLS;
 import static com.google.gson.Gson.DEFAULT_SPECIALIZE_FLOAT_VALUES;
+import static com.google.gson.Gson.DEFAULT_STRICTNESS;
 import static com.google.gson.Gson.DEFAULT_USE_JDK_UNSAFE;
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import com.google.errorprone.annotations.InlineMe;
 import com.google.gson.annotations.Since;
 import com.google.gson.annotations.Until;
 import com.google.gson.internal.$Gson$Preconditions;
@@ -57,8 +58,7 @@
  * use {@code new Gson()}. {@code GsonBuilder} is best used by creating it, and then invoking its
  * various configuration methods, and finally calling create.</p>
  *
- * <p>The following is an example shows how to use the {@code GsonBuilder} to construct a Gson
- * instance:
+ * <p>The following example shows how to use the {@code GsonBuilder} to construct a Gson instance:
  *
  * <pre>
  * Gson gson = new GsonBuilder()
@@ -72,12 +72,16 @@
  *     .create();
  * </pre>
  *
- * <p>NOTES:
+ * <p>Notes:
  * <ul>
- * <li> the order of invocation of configuration methods does not matter.</li>
- * <li> The default serialization of {@link Date} and its subclasses in Gson does
+ * <li>The order of invocation of configuration methods does not matter.</li>
+ * <li>The default serialization of {@link Date} and its subclasses in Gson does
  *  not contain time-zone information. So, if you are using date/time instances,
  *  use {@code GsonBuilder} and its {@code setDateFormat} methods.</li>
+ * <li>By default no explicit {@link Strictness} is set; some of the {@link Gson} methods
+ *  behave as if {@link Strictness#LEGACY_STRICT} was used whereas others behave as
+ *  if {@link Strictness#LENIENT} was used. Prefer explicitly setting a strictness
+ *  with {@link #setStrictness(Strictness)} to avoid this legacy behavior.
  * </ul>
  *
  * @author Inderjeet Singh
@@ -101,7 +105,7 @@ public final class GsonBuilder {
   private boolean escapeHtmlChars = DEFAULT_ESCAPE_HTML;
   private FormattingStyle formattingStyle = DEFAULT_FORMATTING_STYLE;
   private boolean generateNonExecutableJson = DEFAULT_JSON_NON_EXECUTABLE;
-  private boolean lenient = DEFAULT_LENIENT;
+  private Strictness strictness = DEFAULT_STRICTNESS;
   private boolean useJdkUnsafe = DEFAULT_USE_JDK_UNSAFE;
   private ToNumberStrategy objectToNumberStrategy = DEFAULT_OBJECT_TO_NUMBER_STRATEGY;
   private ToNumberStrategy numberToNumberStrategy = DEFAULT_NUMBER_TO_NUMBER_STRATEGY;
@@ -120,7 +124,7 @@ public GsonBuilder() {
    * Constructs a GsonBuilder instance from a Gson instance. The newly constructed GsonBuilder
    * has the same configuration as the previously built Gson instance.
    *
-   * @param gson the gson instance whose configuration should by applied to a new GsonBuilder.
+   * @param gson the gson instance whose configuration should be applied to a new GsonBuilder.
    */
   GsonBuilder(Gson gson) {
     this.excluder = gson.excluder;
@@ -131,7 +135,7 @@ public GsonBuilder() {
     this.generateNonExecutableJson = gson.generateNonExecutableJson;
     this.escapeHtmlChars = gson.htmlSafe;
     this.formattingStyle = gson.formattingStyle;
-    this.lenient = gson.lenient;
+    this.strictness = gson.strictness;
     this.serializeSpecialFloatingPointValues = gson.serializeSpecialFloatingPointValues;
     this.longSerializationPolicy = gson.longSerializationPolicy;
     this.datePattern = gson.datePattern;
@@ -274,7 +278,7 @@ public GsonBuilder serializeNulls() {
    * {"x":2,"y":3}}.
    *
    * <p>Given the assumption above, a {@code Map<Point, String>} will be
-   * serialize as an array of arrays (can be viewed as an entry set of pairs).
+   * serialized as an array of arrays (can be viewed as an entry set of pairs).
    *
    * <p>Below is an example of serializing complex types as JSON arrays:
    * <pre> {@code
@@ -522,18 +526,40 @@ public GsonBuilder setFormattingStyle(FormattingStyle formattingStyle) {
   }
 
   /**
-   * Configures Gson to allow JSON data which does not strictly comply with the JSON specification.
+   * Sets the strictness of this builder to {@link Strictness#LENIENT}.
    *
-   * <p>Note: Due to legacy reasons most methods of Gson are always lenient, regardless of
-   * whether this builder method is used.
+   * @deprecated This method is equivalent to calling {@link #setStrictness(Strictness)} with
+   * {@link Strictness#LENIENT}: {@code setStrictness(Strictness.LENIENT)}
    *
-   * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
-   * @see JsonReader#setLenient(boolean)
-   * @see JsonWriter#setLenient(boolean)
+   * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern.
+   * @see JsonReader#setStrictness(Strictness)
+   * @see JsonWriter#setStrictness(Strictness)
+   * @see #setStrictness(Strictness)
    */
+  @Deprecated
+  @InlineMe(replacement = "this.setStrictness(Strictness.LENIENT)", imports = "com.google.gson.Strictness")
   @CanIgnoreReturnValue
   public GsonBuilder setLenient() {
-    lenient = true;
+    return setStrictness(Strictness.LENIENT);
+  }
+
+  /**
+   * Sets the strictness of this builder to the provided parameter.
+   *
+   * <p>This changes how strict the
+   * <a href="https://www.ietf.org/rfc/rfc8259.txt">RFC 8259 JSON specification</a> is enforced when parsing or
+   * writing JSON. For details on this, refer to {@link JsonReader#setStrictness(Strictness)} and
+   * {@link JsonWriter#setStrictness(Strictness)}.</p>
+   *
+   * @param strictness the new strictness mode. May not be {@code null}.
+   * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern.
+   * @see JsonReader#setStrictness(Strictness)
+   * @see JsonWriter#setStrictness(Strictness)
+   * @since $next-version$
+   */
+  @CanIgnoreReturnValue
+  public GsonBuilder setStrictness(Strictness strictness) {
+    this.strictness = Objects.requireNonNull(strictness);
     return this;
   }
 
@@ -574,7 +600,7 @@ public GsonBuilder setDateFormat(String pattern) {
   }
 
   /**
-   * Configures Gson to to serialize {@code Date} objects according to the style value provided.
+   * Configures Gson to serialize {@code Date} objects according to the style value provided.
    * You can call this method or {@link #setDateFormat(String)} multiple times, but only the last
    * invocation will be used to decide the serialization format.
    *
@@ -595,7 +621,7 @@ public GsonBuilder setDateFormat(int style) {
   }
 
   /**
-   * Configures Gson to to serialize {@code Date} objects according to the style value provided.
+   * Configures Gson to serialize {@code Date} objects according to the style value provided.
    * You can call this method or {@link #setDateFormat(String)} multiple times, but only the last
    * invocation will be used to decide the serialization format.
    *
@@ -712,7 +738,7 @@ public GsonBuilder registerTypeHierarchyAdapter(Class<?> baseType, Object typeAd
   }
 
   /**
-   * Section 2.4 of <a href="http://www.ietf.org/rfc/rfc4627.txt">JSON specification</a> disallows
+   * Section 6 of <a href="https://www.ietf.org/rfc/rfc8259.txt">JSON specification</a> disallows
    * special double values (NaN, Infinity, -Infinity). However,
    * <a href="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf">Javascript
    * specification</a> (see section 4.3.20, 4.3.22, 4.3.23) allows these values as valid Javascript
@@ -805,7 +831,7 @@ public Gson create() {
 
     return new Gson(excluder, fieldNamingPolicy, new HashMap<>(instanceCreators),
         serializeNulls, complexMapKeySerialization,
-        generateNonExecutableJson, escapeHtmlChars, formattingStyle, lenient,
+        generateNonExecutableJson, escapeHtmlChars, formattingStyle, strictness,
         serializeSpecialFloatingPointValues, useJdkUnsafe, longSerializationPolicy,
         datePattern, dateStyle, timeStyle, new ArrayList<>(this.factories),
         new ArrayList<>(this.hierarchyFactories), factories,

gson/src/main/java/com/google/gson/JsonElement.java

@@ -321,7 +321,8 @@ public String toString() {
     try {
       StringWriter stringWriter = new StringWriter();
       JsonWriter jsonWriter = new JsonWriter(stringWriter);
-      jsonWriter.setLenient(true);
+      // Make writer lenient because toString() must not fail, even if for example JsonPrimitive contains NaN
+      jsonWriter.setStrictness(Strictness.LENIENT);
       Streams.write(this, jsonWriter);
       return stringWriter.toString();
     } catch (IOException e) {

gson/src/main/java/com/google/gson/JsonParser.java

@@ -41,7 +41,7 @@ public JsonParser() {}
    * An exception is thrown if the JSON string has multiple top-level JSON elements,
    * or if there is trailing data.
    *
-   * <p>The JSON string is parsed in {@linkplain JsonReader#setLenient(boolean) lenient mode}.
+   * <p>The JSON string is parsed in {@linkplain JsonReader#setStrictness(Strictness) lenient mode}.
    *
    * @param json JSON text
    * @return a parse tree of {@link JsonElement}s corresponding to the specified JSON
@@ -57,7 +57,7 @@ public static JsonElement parseString(String json) throws JsonSyntaxException {
    * An exception is thrown if the JSON string has multiple top-level JSON elements,
    * or if there is trailing data.
    *
-   * <p>The JSON data is parsed in {@linkplain JsonReader#setLenient(boolean) lenient mode}.
+   * <p>The JSON data is parsed in {@linkplain JsonReader#setStrictness(Strictness) lenient mode}.
    *
    * @param reader JSON text
    * @return a parse tree of {@link JsonElement}s corresponding to the specified JSON
@@ -87,8 +87,8 @@ public static JsonElement parseReader(Reader reader) throws JsonIOException, Jso
    * Unlike the other {@code parse} methods, no exception is thrown if the JSON data has
    * multiple top-level JSON elements, or if there is trailing data.
    *
-   * <p>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
+   * <p>The JSON data is parsed in {@linkplain JsonReader#setStrictness(Strictness) lenient mode},
+   * regardless of the strictness setting of the provided reader. The strictness setting
    * of the reader is restored once this method returns.
    *
    * @throws JsonParseException if there is an IOException or if the specified
@@ -97,16 +97,16 @@ public static JsonElement parseReader(Reader reader) throws JsonIOException, Jso
    */
   public static JsonElement parseReader(JsonReader reader)
       throws JsonIOException, JsonSyntaxException {
-    boolean lenient = reader.isLenient();
-    reader.setLenient(true);
+    Strictness strictness = reader.getStrictness();
+    reader.setStrictness(Strictness.LENIENT);
     try {
       return Streams.parse(reader);
     } catch (StackOverflowError e) {
       throw new JsonParseException("Failed parsing JSON source: " + reader + " to Json", e);
     } catch (OutOfMemoryError e) {
       throw new JsonParseException("Failed parsing JSON source: " + reader + " to Json", e);
     } finally {
-      reader.setLenient(lenient);
+      reader.setStrictness(strictness);
     }
   }
 

gson/src/main/java/com/google/gson/JsonStreamParser.java

@@ -28,7 +28,7 @@
 /**
  * A streaming parser that allows reading of multiple {@link JsonElement}s from the specified reader
  * asynchronously. The JSON data is parsed in lenient mode, see also
- * {@link JsonReader#setLenient(boolean)}.
+ * {@link JsonReader#setStrictness(Strictness)}.
  *
  * <p>This class is conditionally thread-safe (see Item 70, Effective Java second edition). To
  * properly use this class across multiple threads, you will need to add some external
@@ -66,7 +66,7 @@ public JsonStreamParser(String json) {
    */
   public JsonStreamParser(Reader reader) {
     parser = new JsonReader(reader);
-    parser.setLenient(true);
+    parser.setStrictness(Strictness.LENIENT);
     lock = new Object();
   }
 

gson/src/main/java/com/google/gson/Strictness.java

@@ -0,0 +1,29 @@
+package com.google.gson;
+
+import com.google.gson.stream.JsonReader;
+import com.google.gson.stream.JsonWriter;
+
+/**
+ * Modes that indicate how strictly a JSON {@linkplain JsonReader reader} or
+ * {@linkplain JsonWriter writer} follows the syntax laid out in the
+ * <a href="https://www.ietf.org/rfc/rfc8259.txt">RFC 8259 JSON specification</a>.
+ *
+ * <p>You can look at {@link JsonReader#setStrictness(Strictness)} to see how the strictness
+ * affects the {@link JsonReader} and you can look at
+ * {@link JsonWriter#setStrictness(Strictness)} to see how the strictness
+ * affects the {@link JsonWriter}.</p>
+ *
+ * @see JsonReader#setStrictness(Strictness)
+ * @see JsonWriter#setStrictness(Strictness)
+ * @since $next-version$
+ */
+public enum Strictness {
+    /** Allow large deviations from the JSON specification. */
+    LENIENT,
+
+    /** Allow certain small deviations from the JSON specification for legacy reasons. */
+    LEGACY_STRICT,
+
+    /** Strict compliance with the JSON specification. */
+    STRICT
+}

gson/src/main/java/com/google/gson/TypeAdapter.java

@@ -134,10 +134,10 @@ public TypeAdapter() {
 
   /**
    * Converts {@code value} to a JSON document and writes it to {@code out}.
-   * Unlike Gson's similar {@link Gson#toJson(JsonElement, Appendable) toJson}
-   * method, this write is strict. Create a {@link
-   * JsonWriter#setLenient(boolean) lenient} {@code JsonWriter} and call
-   * {@link #write(JsonWriter, Object)} for lenient writing.
+   * The strictness {@link Strictness#LEGACY_STRICT} is used for writing the JSON data.
+   * To use a different strictness setting create a {@link JsonWriter}, call its
+   * {@link JsonWriter#setStrictness(Strictness)} method and then use
+   * {@link #write(JsonWriter, Object)} for writing.
    *
    * @param value the Java object to convert. May be null.
    * @since 2.2
@@ -207,10 +207,11 @@ public final TypeAdapter<T> nullSafe() {
   }
 
   /**
-   * Converts {@code value} to a JSON document. Unlike Gson's similar {@link
-   * Gson#toJson(Object) toJson} method, this write is strict. Create a {@link
-   * JsonWriter#setLenient(boolean) lenient} {@code JsonWriter} and call
-   * {@link #write(JsonWriter, Object)} for lenient writing.
+   * Converts {@code value} to a JSON document.
+   * The strictness {@link Strictness#LEGACY_STRICT} is used for writing the JSON data.
+   * To use a different strictness setting create a {@link JsonWriter}, call its
+   * {@link JsonWriter#setStrictness(Strictness)} method and then use
+   * {@link #write(JsonWriter, Object)} for writing.
    *
    * @throws JsonIOException wrapping {@code IOException}s thrown by {@link #write(JsonWriter, Object)}
    * @param value the Java object to convert. May be null.
@@ -253,10 +254,10 @@ public final JsonElement toJsonTree(T value) {
   public abstract T read(JsonReader in) throws IOException;
 
   /**
-   * Converts the JSON document in {@code in} to a Java object. Unlike Gson's
-   * similar {@link Gson#fromJson(Reader, Class) fromJson} method, this
-   * read is strict. Create a {@link JsonReader#setLenient(boolean) lenient}
-   * {@code JsonReader} and call {@link #read(JsonReader)} for lenient reading.
+   * Converts the JSON document in {@code in} to a Java object. The strictness
+   * {@link Strictness#LEGACY_STRICT} is used for reading the JSON data. To use a different
+   * strictness setting create a {@link JsonReader}, call its {@link JsonReader#setStrictness(Strictness)}
+   * method and then use {@link #read(JsonReader)} for reading.
    *
    * <p>No exception is thrown if the JSON data has multiple top-level JSON elements,
    * or if there is trailing data.
@@ -270,10 +271,10 @@ public final T fromJson(Reader in) throws IOException {
   }
 
   /**
-   * Converts the JSON document in {@code json} to a Java object. Unlike Gson's
-   * similar {@link Gson#fromJson(String, Class) fromJson} method, this read is
-   * strict. Create a {@link JsonReader#setLenient(boolean) lenient} {@code
-   * JsonReader} and call {@link #read(JsonReader)} for lenient reading.
+   * Converts the JSON document in {@code json} to a Java object. The strictness
+   * {@link Strictness#LEGACY_STRICT} is used for reading the JSON data. To use a different
+   * strictness setting create a {@link JsonReader}, call its {@link JsonReader#setStrictness(Strictness)}
+   * method and then use {@link #read(JsonReader)} for reading.
    *
    * <p>No exception is thrown if the JSON data has multiple top-level JSON elements,
    * or if there is trailing data.