From 409ddb6c46979b8c22f8ef38f054fcc51aa2409f Mon Sep 17 00:00:00 2001 From: Marcono1234 Date: Mon, 27 Jun 2022 11:53:47 +0200 Subject: [PATCH] Improve user guide formatting and update links --- UserGuide.md | 52 +++++++++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/UserGuide.md b/UserGuide.md index ca00ae4170..e7e316673f 100644 --- a/UserGuide.md +++ b/UserGuide.md @@ -70,20 +70,23 @@ Gson was originally created for use inside Google where it is currently used in The primary class to use is [`Gson`](gson/src/main/java/com/google/gson/Gson.java) which you can just create by calling `new Gson()`. There is also a class [`GsonBuilder`](gson/src/main/java/com/google/gson/GsonBuilder.java) available that can be used to create a Gson instance with various settings like version control and so on. -The Gson instance does not maintain any state while invoking Json operations. So, you are free to reuse the same object for multiple Json serialization and deserialization operations. +The Gson instance does not maintain any state while invoking JSON operations. So, you are free to reuse the same object for multiple JSON serialization and deserialization operations. ## Using Gson with Gradle/Android -``` + +```gradle dependencies { implementation 'com.google.code.gson:gson:2.9.0' } ``` + ## Using Gson with Maven + To use Gson with Maven2/3, you can use the Gson version available in Maven Central by adding the following dependency: ```xml - + com.google.code.gson gson @@ -93,7 +96,7 @@ To use Gson with Maven2/3, you can use the Gson version available in Maven Centr ``` -That is it, now your maven project is Gson enabled. +That is it, now your Maven project is Gson enabled. ### Primitives Examples @@ -130,7 +133,7 @@ class BagOfPrimitives { // Serialization BagOfPrimitives obj = new BagOfPrimitives(); Gson gson = new Gson(); -String json = gson.toJson(obj); +String json = gson.toJson(obj); // ==> json is {"value1":1,"value2":"abc"} ``` @@ -161,23 +164,23 @@ Gson can serialize static nested classes quite easily. Gson can also deserialize static nested classes. However, Gson can **not** automatically deserialize the **pure inner classes since their no-args constructor also need a reference to the containing Object** which is not available at the time of deserialization. You can address this problem by either making the inner class static or by providing a custom InstanceCreator for it. Here is an example: ```java -public class A { - public String a; +public class A { + public String a; - class B { + class B { - public String b; + public String b; public B() { // No args constructor for B } - } + } } ``` **NOTE**: The above class B can not (by default) be serialized with Gson. -Gson can not deserialize `{"b":"abc"}` into an instance of B since the class B is an inner class. If it was defined as static class B then Gson would have been able to deserialize the string. Another solution is to write a custom instance creator for B. +Gson can not deserialize `{"b":"abc"}` into an instance of B since the class B is an inner class. If it was defined as static class B then Gson would have been able to deserialize the string. Another solution is to write a custom instance creator for B. ```java public class InstanceCreatorForB implements InstanceCreator { @@ -205,7 +208,7 @@ gson.toJson(ints); // ==> [1,2,3,4,5] gson.toJson(strings); // ==> ["abc", "def", "ghi"] // Deserialization -int[] ints2 = gson.fromJson("[1,2,3,4,5]", int[].class); +int[] ints2 = gson.fromJson("[1,2,3,4,5]", int[].class); // ==> ints2 will be same as ints ``` @@ -318,7 +321,7 @@ gson.fromJson(json, foo.getClass()); // Fails to deserialize foo.value as Bar The above code fails to interpret value as type Bar because Gson invokes `foo.getClass()` to get its class information, but this method returns a raw class, `Foo.class`. This means that Gson has no way of knowing that this is an object of type `Foo`, and not just plain `Foo`. -You can solve this problem by specifying the correct parameterized type for your generic type. You can do this by using the [`TypeToken`](https://static.javadoc.io/com.google.code.gson/gson/2.8.5/com/google/gson/reflect/TypeToken.html) class. +You can solve this problem by specifying the correct parameterized type for your generic type. You can do this by using the [`TypeToken`](https://javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/reflect/TypeToken.html) class. ```java Type fooType = new TypeToken>() {}.getType(); @@ -326,6 +329,7 @@ gson.toJson(foo, fooType); gson.fromJson(json, fooType); ``` + The idiom used to get `fooType` actually defines an anonymous local inner class containing a method `getType()` that returns the fully parameterized type. ### Serializing and Deserializing Collection with Objects of Arbitrary Types @@ -374,7 +378,7 @@ Gson has built-in serializers and deserializers for commonly used classes whose * `java.net.URL` to match it with strings like `"https://github.com/google/gson/"` * `java.net.URI` to match it with strings like `"/google/gson/"` -For many more, see the internal class [`TypeAdapters`](https://github.com/google/gson/blob/master/gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java). +For many more, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java). You can also find source code for some commonly used classes such as JodaTime at [this page](https://sites.google.com/site/gson/gson-type-adapters-for-common-classes-1). @@ -383,8 +387,8 @@ You can also find source code for some commonly used classes such as JodaTime at Sometimes default representation is not what you want. This is often the case when dealing with library classes (DateTime, etc). Gson allows you to register your own custom serializers and deserializers. This is done by defining two parts: -* Json Serializers: Need to define custom serialization for an object -* Json Deserializers: Needed to define custom deserialization for a type +* JSON Serializers: Need to define custom serialization for an object +* JSON Deserializers: Needed to define custom deserialization for a type * Instance Creators: Not needed if no-args constructor is available or a deserializer is registered @@ -511,10 +515,12 @@ The default JSON output that is provided by Gson is a compact JSON format. This If you would like to use the Pretty Print feature, you must configure your `Gson` instance using the `GsonBuilder`. The `JsonFormatter` is not exposed through our public API, so the client is unable to configure the default print settings/margins for the JSON output. For now, we only provide a default `JsonPrintFormatter` that has default line length of 80 character, 2 character indentation, and 4 character right margin. The following is an example shows how to configure a `Gson` instance to use the default `JsonPrintFormatter` instead of the `JsonCompactFormatter`: -``` + +```java Gson gson = new GsonBuilder().setPrettyPrinting().create(); String jsonOutput = gson.toJson(someObject); ``` + ### Null Object Support The default behaviour that is implemented in Gson is that `null` object fields are ignored. This allows for a more compact output format; however, the client must define a default value for these fields as the JSON format is converted back into its Java form. @@ -625,7 +631,7 @@ This feature provides a way where you can mark certain fields of your objects to #### User Defined Exclusion Strategies -If the above mechanisms for excluding fields and class type do not work for you then you can always write your own exclusion strategy and plug it into Gson. See the [`ExclusionStrategy`](https://static.javadoc.io/com.google.code.gson/gson/2.8.5/com/google/gson/ExclusionStrategy.html) JavaDoc for more information. +If the above mechanisms for excluding fields and class type do not work for you then you can always write your own exclusion strategy and plug it into Gson. See the [`ExclusionStrategy`](https://javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/ExclusionStrategy.html) JavaDoc for more information. The following example shows how to exclude fields marked with a specific `@Foo` annotation and excludes top-level types (or declared field type) of class `String`. @@ -678,13 +684,13 @@ public static void main(String[] args) { The output is: -``` +```json {"longField":1234} ``` ### JSON Field Naming Support -Gson supports some pre-defined field naming policies to convert the standard Java field names (i.e., camel cased names starting with lower case --- `sampleFieldNameInJava`) to a Json field name (i.e., `sample_field_name_in_java` or `SampleFieldNameInJava`). See the [FieldNamingPolicy](https://static.javadoc.io/com.google.code.gson/gson/2.8.5/com/google/gson/FieldNamingPolicy.html) class for information on the pre-defined naming policies. +Gson supports some pre-defined field naming policies to convert the standard Java field names (i.e., camel cased names starting with lower case --- `sampleFieldNameInJava`) to a JSON field name (i.e., `sample_field_name_in_java` or `SampleFieldNameInJava`). See the [FieldNamingPolicy](https://javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/FieldNamingPolicy.html) class for information on the pre-defined naming policies. It also has an annotation based strategy to allows clients to define custom names on a per field basis. Note, that the annotation based strategy has field name validation which will raise "Runtime" exceptions if an invalid field name is provided as the annotation value. @@ -709,11 +715,11 @@ System.out.println(jsonRepresentation); The output is: -``` +```json {"custom_naming":"first","SomeOtherField":"second"} ``` -If you have a need for custom naming policy ([see this discussion](https://groups.google.com/group/google-gson/browse_thread/thread/cb441a2d717f6892)), you can use the [@SerializedName](https://static.javadoc.io/com.google.code.gson/gson/2.8.5/com/google/gson/annotations/SerializedName.html) annotation. +If you have a need for custom naming policy ([see this discussion](https://groups.google.com/group/google-gson/browse_thread/thread/cb441a2d717f6892)), you can use the [@SerializedName](https://javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/annotations/SerializedName.html) annotation. ### Sharing State Across Custom Serializers and Deserializers @@ -731,7 +737,7 @@ In addition Gson's object model and data binding, you can use Gson to read from ## Issues in Designing Gson -See the [Gson design document](https://github.com/google/gson/blob/master/GsonDesignDocument.md "Gson design document") for a discussion of issues we faced while designing Gson. It also include a comparison of Gson with other Java libraries that can be used for Json conversion. +See the [Gson design document](GsonDesignDocument.md "Gson design document") for a discussion of issues we faced while designing Gson. It also include a comparison of Gson with other Java libraries that can be used for JSON conversion. ## Future Enhancements to Gson