diff --git a/gson/src/main/java/com/google/gson/TypeAdapter.java b/gson/src/main/java/com/google/gson/TypeAdapter.java index d15b1e080c..405fb12ac2 100644 --- a/gson/src/main/java/com/google/gson/TypeAdapter.java +++ b/gson/src/main/java/com/google/gson/TypeAdapter.java @@ -34,8 +34,7 @@ * 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 - * adapter for an (X,Y) coordinate point:
{@code - * + * adapter for an (X,Y) coordinate point:{@code * public class PointAdapter extends TypeAdapter{ * public Point read(JsonReader reader) throws IOException { * if (reader.peek() == JsonToken.NULL) { @@ -85,8 +84,7 @@ * guarantees of {@link Gson} might not apply. * * To use a custom type adapter with Gson, you must register it with a - * {@link GsonBuilder}:
{@code - * + * {@link GsonBuilder}:{@code * GsonBuilder builder = new GsonBuilder(); * builder.registerTypeAdapter(Point.class, new PointAdapter()); * // if PointAdapter didn't check for nulls in its read/write methods, you should instead use @@ -102,14 +100,12 @@ //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 -// +// and deserialize JSON. Here is an example for deserialization:{@code // String json = "{'origin':'0,0','points':['1,2','3,4']}"; // TypeAdapter-// And an example for serialization:graphAdapter = gson.getAdapter(Graph.class); // Graph graph = graphAdapter.fromJson(json); // } {@code -// +// And an example for serialization:{@code // Graph graph = new Graph(...); // TypeAdaptergraphAdapter = gson.getAdapter(Graph.class); // String json = graphAdapter.toJson(graph); @@ -134,12 +130,12 @@ public TypeAdapter() { /** * Converts {@code value} to a JSON document and writes it to {@code out}. - * 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. + * A {@link JsonWriter} with default configuration is used for writing the + * JSON data. To customize this behavior, create a {@link JsonWriter}, configure + * it and then use {@link #write(JsonWriter, Object)} instead. + * + * @param value the Java object to convert. May be {@code null}. * @since 2.2 */ public final void toJson(Writer out, T value) throws IOException { @@ -151,8 +147,7 @@ public final void toJson(Writer out, T value) throws IOException { * This wrapper method is used to make a type adapter null tolerant. In general, a * type adapter is required to handle nulls in write and read methods. Here is how this * is typically done:
- *{@code - * + *{@code * Gson gson = new GsonBuilder().registerTypeAdapter(Foo.class, * new TypeAdapter* You can avoid this boilerplate handling of nulls by wrapping your type adapter with * this method. Here is how we will rewrite the above example: - *() { * public Foo read(JsonReader in) throws IOException { @@ -173,8 +168,7 @@ public final void toJson(Writer out, T value) throws IOException { * } {@code - * + *{@code * Gson gson = new GsonBuilder().registerTypeAdapter(Foo.class, * new TypeAdapter() { * public Foo read(JsonReader in) throws IOException { @@ -208,13 +202,13 @@ public final TypeAdapter nullSafe() { /** * 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. + * + * A {@link JsonWriter} with default configuration is used for writing the + * JSON data. To customize this behavior, create a {@link JsonWriter}, configure + * it and then use {@link #write(JsonWriter, Object)} instead. * * @throws JsonIOException wrapping {@code IOException}s thrown by {@link #write(JsonWriter, Object)} - * @param value the Java object to convert. May be null. + * @param value the Java object to convert. May be {@code null}. * @since 2.2 */ public final String toJson(T value) { @@ -230,7 +224,7 @@ public final String toJson(T value) { /** * Converts {@code value} to a JSON tree. * - * @param value the Java object to convert. May be null. + * @param value the Java object to convert. May be {@code null}. * @return the converted JSON tree. May be {@link JsonNull}. * @throws JsonIOException wrapping {@code IOException}s thrown by {@link #write(JsonWriter, Object)} * @since 2.2 @@ -249,20 +243,22 @@ public final JsonElement toJsonTree(T value) { * Reads one JSON value (an array, object, string, number, boolean or null) * and converts it to a Java object. Returns the converted object. * - * @return the converted Java object. May be null. + * @return the converted Java object. May be {@code null}. */ public abstract T read(JsonReader in) throws IOException; /** - * 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. + * Converts the JSON document in {@code in} to a Java object. + * + *
A {@link JsonReader} with default configuration (that is with + * {@link Strictness#LEGACY_STRICT} as strictness) is used for reading the JSON data. + * To customize this behavior, create a {@link JsonReader}, configure it and then + * use {@link #read(JsonReader)} instead. * *
No exception is thrown if the JSON data has multiple top-level JSON elements, * or if there is trailing data. * - * @return the converted Java object. May be null. + * @return the converted Java object. May be {@code null}. * @since 2.2 */ public final T fromJson(Reader in) throws IOException { @@ -271,15 +267,17 @@ public final T fromJson(Reader in) throws IOException { } /** - * 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. + * Converts the JSON document in {@code json} to a Java object. + * + *
A {@link JsonReader} with default configuration (that is with + * {@link Strictness#LEGACY_STRICT} as strictness) is used for reading the JSON data. + * To customize this behavior, create a {@link JsonReader}, configure it and then + * use {@link #read(JsonReader)} instead. * *
No exception is thrown if the JSON data has multiple top-level JSON elements, * or if there is trailing data. * - * @return the converted Java object. May be null. + * @return the converted Java object. May be {@code null}. * @since 2.2 */ public final T fromJson(String json) throws IOException { @@ -290,7 +288,7 @@ public final T fromJson(String json) throws IOException { * Converts {@code jsonTree} to a Java object. * * @param jsonTree the JSON element to convert. May be {@link JsonNull}. - * @return the converted Java object. May be null. + * @return the converted Java object. May be {@code null}. * @throws JsonIOException wrapping {@code IOException}s thrown by {@link #read(JsonReader)} * @since 2.2 */ diff --git a/gson/src/main/java/com/google/gson/stream/JsonReader.java b/gson/src/main/java/com/google/gson/stream/JsonReader.java index 0c1cbe2af3..d49bd779b3 100644 --- a/gson/src/main/java/com/google/gson/stream/JsonReader.java +++ b/gson/src/main/java/com/google/gson/stream/JsonReader.java @@ -19,6 +19,8 @@ package com.google.gson.stream; +import com.google.gson.Gson; +import com.google.gson.GsonBuilder; import com.google.gson.Strictness; import com.google.gson.internal.InvalidStateException; import com.google.gson.internal.JsonReaderInternalAccess; @@ -68,6 +70,16 @@ * Null literals can be consumed using either {@link #nextNull()} or {@link * #skipValue()}. * + *
Configuration
+ * The behavior of this reader can be customized with the following methods: + *+ *
+ * + * The default configuration of {@code JsonReader} instances used internally by + * the {@link Gson} class differs, and can be adjusted with the various + * {@link GsonBuilder} methods. + * *- {@link #setStrictness(Strictness)}, the default is {@link Strictness#LEGACY_STRICT} + *
Example
* Suppose we'd like to parse a stream of messages such as the following:{@code * [ diff --git a/gson/src/main/java/com/google/gson/stream/JsonWriter.java b/gson/src/main/java/com/google/gson/stream/JsonWriter.java index a97c5158d6..07848b0682 100644 --- a/gson/src/main/java/com/google/gson/stream/JsonWriter.java +++ b/gson/src/main/java/com/google/gson/stream/JsonWriter.java @@ -26,6 +26,8 @@ import com.google.errorprone.annotations.CanIgnoreReturnValue; import com.google.gson.FormattingStyle; +import com.google.gson.Gson; +import com.google.gson.GsonBuilder; import com.google.gson.Strictness; import java.io.Closeable; import java.io.Flushable; @@ -61,6 +63,20 @@ * Finally close the object using {@link #endObject()}. * * + *Configuration
+ * The behavior of this writer can be customized with the following methods: + *+ *
+ * + * The default configuration of {@code JsonWriter} instances used internally by + * the {@link Gson} class differs, and can be adjusted with the various + * {@link GsonBuilder} methods. + * *- {@link #setFormattingStyle(FormattingStyle)}, the default is {@link FormattingStyle#COMPACT} + *
- {@link #setHtmlSafe(boolean)}, by default HTML characters are not escaped + * in the JSON output + *
- {@link #setStrictness(Strictness)}, the default is {@link Strictness#LEGACY_STRICT} + *
- {@link #setSerializeNulls(boolean)}, by default {@code null} is serialized + *
Example
* Suppose we'd like to encode a stream of messages such as the following:{@code * [