repository·main·Indexed 12 days ago
https://github.com/google/gsonA Java library for converting Java objects to JSON and JSON strings back into Java objects. It supports arbitrary objects without requiring source code access, provides extensive support for Java Generics, and includes a specialized protobuf module for Protocol Buffers serialization. Compatible with Java 6+ and Android API level 19+, with recommended version 2.14.0.
Gson is a Java library designed to convert Java Objects into their JSON representation (serialization) and convert JSON strings back into equivalent Java objects (deserialization).
Key capabilities include:
The proto module provides a specialized JSON serializer and deserializer for Protocol Buffers (protobuf) messages. This allows you to convert protobuf-generated Java objects to and from JSON format using Gson.
Note: The artifacts created by this module are currently not deployed to Maven Central. You may need to build the module locally or include it via a local repository dependency.
By default, Gson serializes java.util.Map as a JSON object.
Key behaviors:
toString() on Map keys. null keys are converted to the string "null".TypeToken to specify the types of keys and values.toString(), use GsonBuilder.enableComplexMapKeySerialization(). This will serialize the Map as a JSON array of key-value pairs if any key is a complex type (array or object).// Standard Map Serialization
Gson gson = new Gson();
Map<String, String> stringMap = new LinkedHashMap<>();
stringMap.put("key", "value");
stringMap.put(null, "null-entry");
String json = gson.toJson(stringMap); // ==> {"key":"value","null":"null-entry"}
// Complex Map Key Serialization
Gson gsonComplex = new GsonBuilder().enableComplexMapKeySerialization().create();
Map<PersonName, Integer> complexMap = new LinkedHashMap<>();
// ... put items ...
String jsonComplex = gsonComplex.toJson(complexMap);
// ==> [[{"firstName":"John","lastName":"Doe"},30], ...]GraalVM Native Image requires explicit configuration of class members accessed via reflection.
When using Gson with Native Image, you can use the existing reflection metadata provided in the repository located at:
src/test/resources/META-INF/native-image/reflect-config.json.
Alternatively, you can automatically generate a metadata file by running tests with the -Dagent=true flag, which utilizes the GraalVM Maven plugin's agent support.
# Example of running with the agent to generate metadata
mvn clean test --activate-profiles native-image-test -Dagent=trueGson converts Java objects to JSON and vice versa.
Key behaviors:
transient are ignored.static or provide a custom InstanceCreator.null.class BagOfPrimitives {
private int value1 = 1;
private String value2 = "abc";
private transient int value3 = 3;
BagOfPrimitives() {}
}
// Serialization
BagOfPrimitives obj = new BagOfPrimitives();
Gson gson = new Gson();
String json = gson.toJson(obj);
// ==> {"value1":1,"value2":"abc"}
// Deserialization
BagOfPrimitives obj2 = gson.fromJson(json, BagOfPrimitives.class);When deserializing a JSON string into a Java object, Gson navigates the type tree of the target object rather than the JSON tree.
This approach provides several benefits:
The primary entry point for the library is the Gson class.
new Gson(): Creates a default instance of Gson with standard settings.GsonBuilder: Use this class when you need to customize the Gson instance, such as configuring versioning support, field naming strategies, or custom serialization behaviors.Gson instances are stateless and thread-safe; you can and should reuse a single Gson instance for multiple serialization and deserialization operations to improve performance.
// Create a default instance
Gson gson = new Gson();
// Create a customized instance
Gson customGson = new GsonBuilder()
.setPrettyPrinting()
.create();You can manage different versions of an object by using the @Since(version) annotation on classes or fields. To enforce this, configure your Gson instance with setVersion(version). Fields with a version higher than the configured version will be ignored.
public class VersionedClass {
@Since(1.1) private final String newerField;
@Since(1.0) private final String newField;
private final String field;
// ...
}
// Only serializes fields with version <= 1.0
Gson gson = new GsonBuilder().setVersion(1.0).create();
String jsonOutput = gson.toJson(versionedObject);Gson is fields-based. It uses all fields in the inheritance hierarchy to deduce JSON elements, with the following exceptions:
transient, static, or synthetic are ignored.getXXX or isXXX), Gson relies on the fields themselves. This avoids issues where getter names are semantic rather than property-based.If you are running on Java 9 or newer, Gson provides a JPMS module descriptor (module name com.google.gson). You may optionally include the following JDK modules:
java.sql: Enables default adapters for certain SQL date and time classes.jdk.unsupported: Allows Gson to use sun.misc.Unsafe to create instances of classes that lack a no-args constructor. Warning: Use this with caution as Unsafe is not available in all environments. You can disable this behavior using GsonBuilder.disableJdkUnsafe().Gson is a Java library designed to convert Java Objects into JSON representations and vice-versa.
Key Features:
toJson() and fromJson() methods for easy conversion.