Document that other JVM languages are not fully supported #2666
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Marcono1234
commented
Apr 6, 2024
| @@ -8,6 +8,10 @@ There are a few open-source projects that can convert Java objects to JSON. Howe | |||
| > [!NOTE]\ | |||
| > Gson is currently in maintenance mode; existing bugs will be fixed, but large new features will likely not be added. If you want to add a new feature, please first search for existing GitHub issues, or create a new one to discuss the feature and get feedback. | |||
|
|
|||
| > [!IMPORTANT]\ | |||
There was a problem hiding this comment.
This uses the GitHub-specific alert syntax, similar to the > [!NOTE] above.
eamonnmcmanus
approved these changes
May 18, 2024
# for free
to join this conversation on GitHub.
Already have an account?
# to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Purpose
Document that other JVM languages are not fully supported
Description
Gson's main focus is on Java. Because Gson uses reflection it works in many cases also for other JVM languages such as Kotlin or Scala, but because it does not explicitly consider these languages, language-specific features which do not exist in Java don't work properly. See for example issues with kotlinIssues concerning the use of Gson with Kotlin
label.
Therefore this pull request adds a warning to prevent new users from investing a lot of time to use Gson with these languages just to notice in the end that it is not properly working or error-prone.
If at some point in the future Gson properly supports other JVM languages, the warning can be removed again. But (at least to me) it seems a bit unlikely that this will ever happen, because:
Actually this limitation mostly (or only) applies to reflection-based serialization and deserialization. Using only custom
TypeAdapters,JsonElement(and subclasses) orJsonReaderandJsonWriterwill probably work fine. However, explaining this might be a bit verbose, and most likely using reflection-based serialization is the most common use case. And even if users initially only use the non-reflective features, they might in the future use them and would then either have to migrate or mix multiple JSON libraries which often does not work that well.Feedback regarding the wording and where to document this (e.g. not in the README but instead somewhere else) is appreciated. I did not want to explicitly list the other JSON libraries because there are multiple and to not endorse specific ones when there are other ones which might be better suited for the specific use case of the user, or if new libraries emerge in the future.