GsonBuilder

Creates a GsonBuilder instance that can be used to build Gson with various configuration settings. GsonBuilder follows the builder pattern, and it is typically used by first invoking various configuration methods to set desired options, and finally calling create().

Configures Gson to apply the passed in exclusion strategy during deserialization. If this method is invoked numerous times with different exclusion strategy objects then the exclusion strategies that were added will be applied as a disjunction rule. This means that if one of the added exclusion strategies suggests that a field (or class) should be skipped then that field (or object) is skipped during its deserialization.

Configures Gson to apply the passed in exclusion strategy during serialization. If this method is invoked numerous times with different exclusion strategy objects then the exclusion strategies that were added will be applied as a disjunction rule. This means that if one of the added exclusion strategies suggests that a field (or class) should be skipped then that field (or object) is skipped during its serialization.

Creates a Gson instance based on the current configuration. This method is free of side-effects to this GsonBuilder instance and hence can be called multiple times.

By default, Gson escapes HTML characters such as < > etc. Use this option to configure Gson to pass-through HTML characters as is.

Configures Gson to exclude inner classes during serialization.

Enabling this feature will only change the serialized form if the map key is a complex type (i.e. non-primitive) in its serialized JSON form. The default implementation of map serialization uses toString() on the key; however, when this is called then one of the following cases apply:

Maps as JSON objects

Below is an example:

  Gson gson = new GsonBuilder()
       .register(Point.class, new MyPointTypeAdapter())
       .enableComplexMapKeySerialization()
       .create();

   Map<Point, String> original = new LinkedHashMap<Point, String>();
   original.put(new Point(5, 6), "a");
   original.put(new Point(8, 8), "b");
   System.out.println(gson.toJson(original, type));
 

  {
     "(5,6)": "a",
     "(8,8)": "b"
   
 }

Maps as JSON arrays

Given the assumption above, a Map<Point, String> will be serialize as an array of arrays (can be viewed as an entry set of pairs).

Below is an example of serializing complex types as JSON arrays:

 Gson gson = new GsonBuilder()
       .enableComplexMapKeySerialization()
       .create();

   Map<Point, String> original = new LinkedHashMap<Point, String>();
   original.put(new Point(5, 6), "a");
   original.put(new Point(8, 8), "b");
   System.out.println(gson.toJson(original, type));
 

 The JSON output would look as follows:
 
   [
     [
       {
         "x": 5,
         "y": 6
       ,
       "a"
     ],
     [
       {
         "x": 8,
         "y": 8
       },
       "b"
     ]
   ]
 }

Configures Gson to excludes all class fields that have the specified modifiers. By default, Gson will exclude all fields marked transient or static. This method will override that behavior.

Configures Gson to exclude all fields from consideration for serialization or deserialization that do not have the com.google.gson.annotations.Expose annotation.

Makes the output JSON non-executable in Javascript by prefixing the generated JSON with some special text. This prevents attacks from third-party sites through script sourcing. See Gson Issue 42 for details.

Configures Gson for custom serialization or deserialization. This method combines the registration of an TypeAdapter, InstanceCreator, JsonSerializer, and a JsonDeserializer. It is best used when a single object typeAdapter implements all the required interfaces for custom serialization with Gson. If a type adapter was previously registered for the specified type, it is overwritten.

This registers the type specified and no other types: you must manually register related types! For example, applications registering boolean.class should also register Boolean.class.

Register a factory for type adapters. Registering a factory is useful when the type adapter needs to be configured based on the type of the field being processed. Gson is designed to handle a large number of factories, so you should consider registering them to be at par with registering an individual type adapter.

Configures Gson for custom serialization or deserialization for an inheritance type hierarchy. This method combines the registration of a TypeAdapter, JsonSerializer and a JsonDeserializer. If a type adapter was previously registered for the specified type hierarchy, it is overridden. If a type adapter is registered for a specific type in the type hierarchy, it will be invoked instead of the one registered for the type hierarchy.

Configure Gson to serialize null fields. By default, Gson omits all fields that are null during serialization.

Section 2.4 of JSON specification disallows special double values (NaN, Infinity, -Infinity). However, Javascript specification (see section 4.3.20, 4.3.22, 4.3.23) allows these values as valid Javascript values. Moreover, most JavaScript engines will accept these special values in JSON without problem. So, at a practical level, it makes sense to accept these values as valid JSON even though JSON specification disallows them.

Gson always accepts these special values during deserialization. However, it outputs strictly compliant JSON. Hence, if it encounters a float value NaN, POSITIVE_INFINITY, NEGATIVE_INFINITY, or a double value NaN, POSITIVE_INFINITY, NEGATIVE_INFINITY, it will throw an IllegalArgumentException. This method provides a way to override the default behavior when you know that the JSON receiver will be able to handle these special values.

Configures Gson to serialize Date objects according to the pattern provided. You can call this method or setDateFormat(int) multiple times, but only the last invocation will be used to decide the serialization format.

The date format will be used to serialize and deserialize java.util.Date, java.sql.Timestamp and java.sql.Date.

Note that this pattern must abide by the convention provided by SimpleDateFormat class. See the documentation in java.text.SimpleDateFormat for more information on valid date and time patterns.

Configures Gson to to serialize Date objects according to the style value provided. You can call this method or setDateFormat(String) multiple times, but only the last invocation will be used to decide the serialization format.

Note that this style value should be one of the predefined constants in the DateFormat class. See the documentation in java.text.DateFormat for more information on the valid style constants.

Configures Gson to to serialize Date objects according to the style value provided. You can call this method or setDateFormat(String) multiple times, but only the last invocation will be used to decide the serialization format.

Note that this style value should be one of the predefined constants in the DateFormat class. See the documentation in java.text.DateFormat for more information on the valid style constants.

Configures Gson to apply a set of exclusion strategies during both serialization and deserialization. Each of the strategies will be applied as a disjunction rule. This means that if one of the strategies suggests that a field (or class) should be skipped then that field (or object) is skipped during serializaiton/deserialization.

Configures Gson to apply a specific naming policy to an object's field during serialization and deserialization.

Configures Gson to apply a specific naming policy strategy to an object's field during serialization and deserialization.

Configures Gson to apply a specific serialization policy for Long and long objects.

Configures Gson to output Json that fits in a page for pretty printing. This option only affects Json serialization.

Configures Gson to enable versioning support.