-
Notifications
You must be signed in to change notification settings - Fork 4.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fix and add the documentation for Built-in Serializers and Deserializers #2441
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -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: | ||||||
|
||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is there a specific reason why you chose to use a numbered list here? A numbered list suggests some kind of ordering or priorities and I am not sure if that is correct here, or needed. Maybe a regular unordered list would be better? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @Marcono1234 Sure, changed to unordered list. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @Lalitha333, just to clarify, you are still working on these changes, right? Or did you forget to push the commits? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @Marcono1234 Sorry for the delay, yes I’m going to push the changes as per review comments. |
||||||
* 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. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should probably unindent this by one level because
Suggested change
|
||||||
* 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". | ||||||
Comment on lines
+425
to
+428
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The format you are describing here for all of these date and time types seems to be incorrect. They might be what one would hope or expect, but sadly due to legacy reasons Gson is not using these formats by default. Maybe the documentation could say something like:
|
||||||
* BigInteger and BigDecimal: | ||||||
* java.math.BigInteger: Serialized as a string. | ||||||
* java.math.BigDecimal: Serialized as a string. | ||||||
Comment on lines
+430
to
+431
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "Serialized as a string" is misleading, because they are actually serialized as JSON number. Maybe it should say something like this?
|
||||||
* 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). | ||||||
|
||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe it would be good to include
URL
andURI
in the list below again with a description like "Serialized as their string representation" or similar, since these types might also be somewhat common.