This is the main class for using Gson. Gson is typically used by first constructing a Gson instance and then invoking toJson(Object) or fromJson(String, Class) methods on it. Gson instances are Thread-safe so you can reuse them freely across multiple threads.

You can create a Gson instance by invoking new Gson() if the default configuration is all you need. You can also use GsonBuilder to build a Gson instance with various configuration options such as versioning support, pretty printing, custom newline, custom indent, custom JsonSerializers, JsonDeserializers, and InstanceCreators.

Here is an example of how Gson is used for a simple Class:

Gson gson = new Gson(); // Or use new GsonBuilder().create();
MyType target = new MyType();
String json = gson.toJson(target); // serializes target to JSON
MyType target2 = gson.fromJson(json, MyType.class); // deserializes json into target2

If the type of the object that you are converting is a ParameterizedType (i.e. has at least one type argument, for example List<MyType>) then for deserialization you must use a fromJson method with Type or TypeToken parameter to specify the parameterized type. For serialization specifying a Type or TypeToken is optional, otherwise Gson will use the runtime type of the object. TypeToken is a class provided by Gson which helps creating parameterized types. Here is an example showing how this can be done:

TypeToken<List<MyType>> listType = new TypeToken<List<MyType>>() {};
List<MyType> target = new LinkedList<MyType>();
target.add(new MyType(1, "abc"));

Gson gson = new Gson();
// For serialization you normally do not have to specify the type, Gson will use
// the runtime type of the objects, however you can also specify it explicitly
String json = gson.toJson(target, listType.getType());

// But for deserialization you have to specify the type
List<MyType> target2 = gson.fromJson(json, listType);

See the Gson User Guide for a more complete set of examples.

JSON Strictness handling

For legacy reasons most of the Gson methods allow JSON data which does not comply with the JSON specification when no explicit strictness is set (the default). To specify the strictness of a Gson instance, you should set it through GsonBuilder#setStrictness(Strictness).

For older Gson versions, which don't have the strictness mode API, the following workarounds can be used:

Serialization

1. Use getAdapter(Class) to obtain the adapter for the type to be serialized
2. When using an existing JsonWriter, manually apply the writer settings of this Gson instance listed by newJsonWriter(Writer).
   Otherwise, when not using an existing JsonWriter, use newJsonWriter(Writer) to construct one.
3. Call TypeAdapter#write(JsonWriter, Object)

Deserialization

1. Use getAdapter(Class) to obtain the adapter for the type to be deserialized
2. When using an existing JsonReader, manually apply the reader settings of this Gson instance listed by newJsonReader(Reader).
   Otherwise, when not using an existing JsonReader, use newJsonReader(Reader) to construct one.
3. Call TypeAdapter#read(JsonReader)
4. Call JsonReader#peek() and verify that the result is JsonToken#END_DOCUMENT to make sure there is no trailing data

Note that the JsonReader created this way is only 'legacy strict', it mostly adheres to the JSON specification but allows small deviations. See JsonReader#setStrictness(Strictness) for details.

new TypeToken<Collection<Foo>>(){}

new TypeToken<Collection<Foo>>(){}

new TypeToken<Collection<Foo>>(){}

new TypeToken<Collection<Foo>>(){}

Type typeOfSrc = new TypeToken<Collection<Foo>>(){}.getType();

Type typeOfSrc = new TypeToken<Collection<Foo>>(){}.getType();

Type typeOfSrc = new TypeToken<Collection<Foo>>(){}.getType();