-
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?
Fix and add the documentation for Built-in Serializers and Deserializers #2441
Conversation
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
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.
Thanks! This looks really useful, and is definitely better than only referring the user to the internal implementation details.
If you think this resolves the GitHub issue you mentioned in the description, could you please edit the description to contain "Closes #..."; this way GitHub automatically recognizes this.
A few of my comments below might be nit-picky, feel free to consider them as suggestions, you don't have to follow them strictly. However, it looks like in some cases you also described the serialized output incorrectly.
Note that I am not a direct project member, and they might think differently.
UserGuide.md
Outdated
For example, suppose you have a Java class `Person`: | ||
|
||
```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. |
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.
Not sure if this section here with the Person
example is needed since there are already multiple examples for object serialization above, and also this is not directly about the built-in serializers.
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 comment
The 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 comment
The 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 comment
The 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 comment
The 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.
UserGuide.md
Outdated
Below is a list of some of the classes supported by Gson's built-in serializers and deserializers: | ||
|
||
1. Primitive Types: | ||
* `int, Integer, long, Long, float, Float, double, Double, boolean, Boolean, char, Character, byte, Byte, short, Short.` |
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.
Could you please format each type separately as code, e.g. int
, long
, ...
Having this formatted as one single code line looks a bit weird.
Also, maybe omit the wrapper types and just add something like "(and their wrappers)" at the end to make it easier to read.
UserGuide.md
Outdated
* 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 comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe instead of listing List
and Set
separately, write something like the following because Gson actually supports any Collection
:
java.util.Collection
: Collection of objects, and collection subtypes such asList
orSet
.
And also in general maybe format the class names here and below as code, e.g. "java.util.Map
" instead of just "java.util.Map".
UserGuide.md
Outdated
5. BigInteger and BigDecimal: | ||
* java.math.BigInteger: Serialized as a string. | ||
* java.math.BigDecimal: Serialized as a string. | ||
6. Enumerations: |
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 call it "Enum Types" in the header here as well, that might be clearer than "Enumerations".
UserGuide.md
Outdated
7. Optional: | ||
* java.util.Optional: Serializes the value if present; otherwise, it serializes as null. | ||
8. Custom Objects: | ||
* Gson can automatically serialize and deserialize custom Java objects using reflection. It serializes the non-static, non-transient fields of an object. |
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.
* Gson can automatically serialize and deserialize custom Java objects using reflection. It serializes the non-static, non-transient fields of an object. | |
* Gson can automatically serialize and deserialize custom Java objects using reflection. By default, it serializes the non-static, non-transient fields of an object. |
(Because this can be customized)
UserGuide.md
Outdated
8. Custom Objects: | ||
* Gson can automatically serialize and deserialize custom Java objects using reflection. 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 JsonSerializer and JsonDeserializer interfaces. |
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 this should rather recommend TypeAdapter
since the documentation for JsonSerializer
and JsonDeserializer
also recommend TypeAdapter
for performance reasons.
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 JsonSerializer and JsonDeserializer interfaces. | |
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. |
Or maybe even omit this sentence because the section "Custom Serialization and Deserialization" is directly below this.
UserGuide.md
Outdated
* java.util.List: List of objects. | ||
* java.util.Set: Set of objects. | ||
* java.util.Map: Map of key-value pairs. | ||
4. Date and Time: |
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 this should also refer to GsonBuilder.setDateFormat(...)
|
||
* `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/"` |
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
and URI
in the list below again with a description like "Serialized as their string representation" or similar, since these types might also be somewhat common.
UserGuide.md
Outdated
8. Custom Objects: | ||
* Gson can automatically serialize and deserialize custom Java objects using reflection. 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 JsonSerializer and JsonDeserializer interfaces. | ||
|
||
For many more, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java). |
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 reword this a bit to give a bit more context, for example:
For many more, see the internal class [`TypeAdapters`](gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java). | |
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). |
Thanks for your changes! Do you want to address some or all of the other review comments as well? |
I believe I made all the requested changes. Please let me know if I have missed any. |
* `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 comment
The reason will be displayed to describe this comment to others. Learn more.
Should probably unindent this by one level because Map
is not a subtype of Collection
* `java.util.Map`: Map of key-value pairs. | |
* `java.util.Map`: Map of key-value pairs. |
@Lalitha333, yes there are a few unresolved points (I also just added a new single comment about your follow-up commit); see the GitHub documentation for how you can browse them. If you addressed a comment, feel free to mark it as "resolved". Also, in case you don't want to address a comment, it might be good if you could write a short reply explaining this, so it is clear that you did not accidentally marked it as "resolved". |
Purpose
This PR has updates to the documentation on built-in serializers and deserializers with examples and types supported w.r.t an issue opened for missing/incorrect documentation.
"Closes #620" -->
Description
Updated the Built-in Serializers and deserializers section under UserGuide
#620
Checklist
null
@since $next-version$
(
$next-version$
is a special placeholder which is automatically replaced during release)TestCase
)mvn clean verify javadoc:jar
passes without errors