Skip to content
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.

Sign up for GitHub

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

Clarify in documentation that Gson might cache strategy results #2215

Merged
merged 2 commits into from
Oct 4, 2022
Merged

Clarify in documentation that Gson might cache strategy results #2215

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7f947e2
Clarify in documentation that Gson might cache strategy results
Marcono1234 Oct 2, 2022
acff285
Improve wording; mention that adapter factory results are cached as well
Marcono1234 Oct 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions gson/src/main/java/com/google/gson/GsonBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,10 @@ public GsonBuilder setFieldNamingPolicy(FieldNamingPolicy namingConvention) {
* Configures Gson to apply a specific naming strategy to an object's fields during
* serialization and deserialization.
*
* <p>The Gson instance might only use the field naming strategy once for a field and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I would use {@link Gson} here to make it clear that we are talking about the class here (in the previous paragraph we are talking about Gson the project).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a similar concern, being afraid that users might think Gson statically (for all Gson instances) caches the results. That is why I chose "Gson instance", but I have now changed it to "The created Gson instance". In the context of this builder I hope this should be clear enough.

In this specific line where you added the comment I don't think a {@link Gson} would be needed. The previous paragraph is also about the Gson instance and not about specifying a naming strategy globally. Or did I misunderstand you?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is fine now. I would probably use {@link} or {@code} every time we're talking about Gson the class, since Gson is also the name of the project. But that's probably overly fussy.

* cache the result. It is not guaranteed that the strategy will be used again every
* time the value of a field is serialized or deserialized.
*
* @param fieldNamingStrategy the naming strategy to apply to the fields
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
* @since 1.3
Expand Down Expand Up @@ -402,6 +406,10 @@ public GsonBuilder setNumberToNumberStrategy(ToNumberStrategy numberToNumberStra
* JSON null is written to output, and when deserialized the JSON value is skipped and
* {@code null} is returned.
*
* <p>The Gson instance might only use an exclusion strategy once for a field or class and
* cache the result. It is not guaranteed that the strategy will be used again every time
* the value of a field or a class is serialized or deserialized.
*
* @param strategies the set of strategy object to apply during object (de)serialization.
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
* @since 1.4
Expand Down Expand Up @@ -703,6 +711,10 @@ public GsonBuilder disableJdkUnsafe() {
* all classes for which no {@link TypeAdapter} has been registered, and for which no
* built-in Gson {@code TypeAdapter} exists.
*
* <p>The Gson instance might only use an access filter once for a class or its members
* and cache the result. It is not guaranteed that the filter will be used again every
* time a class or its members are accessed during serialization or deserialization.
*
* @param filter filter to add
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
* @since 2.9.1
Expand Down
10 changes: 7 additions & 3 deletions gson/src/main/java/com/google/gson/annotations/JsonAdapter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@
* </pre>
*
* Since User class specified UserJsonAdapter.class in &#64;JsonAdapter annotation, it
* will automatically be invoked to serialize/deserialize User instances. <br>
* will automatically be invoked to serialize/deserialize User instances.
*
* <p> Here is an example of how to apply this annotation to a field.
* <pre>
Expand All @@ -80,10 +80,14 @@
*
* <p>The class referenced by this annotation must be either a {@link
* TypeAdapter} or a {@link TypeAdapterFactory}, or must implement one
* or both of {@link JsonDeserializer} or {@link JsonSerializer}.
* Using {@link TypeAdapterFactory} makes it possible to delegate
* or both of {@link JsonDeserializer} or {@link JsonSerializer}.
* Using {@link TypeAdapterFactory} makes it possible to delegate
* to the enclosing {@code Gson} instance.
*
* <p>Gson might cache the adapter it created for a {@code @JsonAdapter}
* annotation. It is not guaranteed that a new adapter is created every
* time the annotated class or field is serialized or deserialized.
*
* @since 2.3
*
* @author Inderjeet Singh
Expand Down