diff --git a/UserGuide.md b/UserGuide.md index f519865434..ee4532a9e7 100644 --- a/UserGuide.md +++ b/UserGuide.md @@ -378,12 +378,67 @@ This approach is practical only if the array appears as a top-level element or i ### Built-in Serializers and Deserializers -Gson has built-in serializers and deserializers for commonly used classes whose default representation may be inappropriate, for instance +Gson has built-in serializers and deserializers for commonly used classes whose default representation may be inappropriate. +Gson provides built-in serializers and deserializers for basic Java types (e.g., primitive types, strings, arrays) as well as some commonly used classes like `Date`, `BigInteger`, `BigDecimal`, and more. When you use Gson to convert Java objects to JSON or JSON to Java objects, these built-in serializers and deserializers handle the conversion automatically for these basic types and classes. -* `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 example, suppose you have a Java class `Person`: -For many more, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java). +```java +public class Person { +private String name; +private int age; +// constructors, getters, setters, etc. +} +``` +You can serialize an instance of `Person` to JSON using Gson like this: + +```java +Person person = new Person("John Doe", 30); +Gson gson = new Gson(); +String json = gson.toJson(person); +``` +The output JSON would be: `{"name":"John Doe","age":30}`. + +And you can deserialize the JSON back to a `Person` object like this: + +```java +String json = "{\"name\":\"Jane Smith\",\"age\":25}"; +Person person = gson.fromJson(json, Person.class); +``` +The `gson.fromJson()` method uses the built-in deserializers to convert the JSON back into a `Person` object. + +Gson also allows you to customize serialization and deserialization by providing your own custom serializers and deserializers for specific types if needed. + +Below is a list of some of the classes supported by Gson's built-in serializers and deserializers: + +* Primitive Types: + * `int`, `long`, `float`, `double`, `boolean`, `char`, `byte`, `short` and their wrapper types. +* Arrays: + * Arrays of primitive types and their wrappers. + * Arrays of objects. +* Collections: + * `java.util.Collection`: Collection of objects, and collection subtypes such as: + * `java.util.List`: List of objects. + * `java.util.Set`: Set of objects. + * `java.util.Map`: Map of key-value pairs. +* Date and Time: + * java.util.Date: Serialized as a Unix timestamp (milliseconds since January 1, 1970, 00:00:00 GMT). + * java.sql.Date: Serialized as a string in the format "yyyy-MM-dd". + * java.sql.Time: Serialized as a string in the format "HH:mm:ss". + * java.sql.Timestamp: Serialized as a string in the format "yyyy-MM-dd HH:mm:ss". +* BigInteger and BigDecimal: + * java.math.BigInteger: Serialized as a string. + * java.math.BigDecimal: Serialized as a string. +* Enum Types: + * Enum constants are serialized using their name by default. You can also customize the serialization using the `@SerializedName` annotation on an enum constant. +* Optional: + * java.util.Optional: Serializes the value if present; otherwise, it serializes as null. +* Custom Objects: + * Gson can automatically serialize and deserialize custom Java objects using reflection. By default, it serializes the non-static, non-transient fields of an object. + +It's important to note that Gson's built-in serializers and deserializers can handle nested objects and collections of objects as well. If a class is not supported by Gson's default behavior, you can provide custom serialization and deserialization logic using Gson's `TypeAdapter` class. + +For more of the built-in serializers and deserializers, 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).