Package: groovy.json

## [Java] Class JsonGenerator.Options

- groovy.json.JsonGenerator.Options

-     public class JsonGenerator.Options
      extends Object

  A builder used to construct a JsonGenerator instance that allows control over the serialized JSON output. If you do not need to customize the output it is recommended to use the static `JsonOutput.toJson` methods.

  Example:

           def generator = new groovy.json.JsonGenerator.Options()
                               .excludeNulls()
                               .dateFormat('yyyy')
                               .excludeFieldsByName('bar', 'baz')
                               .excludeFieldsByType(java.sql.Date)
                               .build()

           def input = [foo: null, lastUpdated: Date.parse('yyyy-MM-dd', '2014-10-24'),
                         bar: 'foo', baz: 'foo', systemDate: new java.sql.Date(new Date().getTime())]

           assert generator.toJson(input) == '{"lastUpdated":"2014"}'

  Since:
    2.5.0

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected static String` | `DEFAULT_TIMEZONE` | Default time zone ID used for JSON date values.
    `protected static String` | `JSON_DATE_FORMAT` | Default date format pattern used for JSON date values.
    `protected static Locale` | `JSON_DATE_FORMAT_LOCALE` | Default locale used with the JSON date format pattern.
    `protected Set<Converter>` | `converters` | Registered converters applied before default serialization.
    `protected String` | `dateFormat` | Date format pattern used when serializing dates.
    `protected Locale` | `dateLocale` | Locale used when serializing dates.
    `protected boolean` | `disableUnicodeEscaping` | Indicates whether Unicode escaping should be disabled.
    `protected boolean` | `excludeNulls` | Indicates whether `null` values should be omitted.
    `protected Set<String>` | `excludedFieldNames` | Field names excluded from generated JSON objects.
    `protected Set<Class<?>>` | `excludedFieldTypes` | Field types excluded from generated JSON objects.
    `protected TimeZone` | `timezone` | Time zone used when serializing dates.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `Options()` Creates an options builder with the default JSON serialization settings.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public Options` | `addConverter(Converter converter)` Registers a converter that will be called when a type it handles is encountered.
    `<T>` | `public Options` | `addConverter(Class<T> type, Closure<?> closure)` Registers a closure that will be called when the specified type or subtype is serialized.
    `` | `public JsonGenerator` | `build()` Creates a JsonGenerator that is based on the current options.
    `` | `public Options` | `dateFormat(String format)` Sets the date format that will be used to serialize `Date` objects.
    `` | `public Options` | `dateFormat(String format, Locale locale)` Sets the date format that will be used to serialize `Date` objects.
    `` | `public Options` | `disableUnicodeEscaping()` Disables the escaping of Unicode characters in JSON String values.
    `` | `public Options` | `excludeFieldsByName(CharSequence fieldNames)` Excludes from the output any fields that match the specified names.
    `` | `public Options` | `excludeFieldsByName(Iterable<? extends CharSequence> fieldNames)` Excludes from the output any fields that match the specified names.
    `` | `public Options` | `excludeFieldsByType(Class<?> types)` Excludes from the output any fields whose type is the same or is assignable to any of the given types.
    `` | `public Options` | `excludeFieldsByType(Iterable<Class<?>> types)` Excludes from the output any fields whose type is the same or is assignable to any of the given types.
    `` | `public Options` | `excludeNulls()` Do not serialize `null` values.
    `` | `public Options` | `timezone(String timezone)` Sets the time zone that will be used to serialize dates.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### protected static final String DEFAULT_TIMEZONE

      Default time zone ID used for JSON date values.

    - #### protected static final String JSON_DATE_FORMAT

      Default date format pattern used for JSON date values.

    - #### protected static final Locale JSON_DATE_FORMAT_LOCALE

      Default locale used with the JSON date format pattern.

    - #### protected final Set<Converter> converters

      Registered converters applied before default serialization.

    - #### protected String dateFormat

      Date format pattern used when serializing dates.

    - #### protected Locale dateLocale

      Locale used when serializing dates.

    - #### protected boolean disableUnicodeEscaping

      Indicates whether Unicode escaping should be disabled.

    - #### protected boolean excludeNulls

      Indicates whether `null` values should be omitted.

    - #### protected final Set<String> excludedFieldNames

      Field names excluded from generated JSON objects.

    - #### protected final Set<Class<?>> excludedFieldTypes

      Field types excluded from generated JSON objects.

    - #### protected TimeZone timezone

      Time zone used when serializing dates.

  - ### Constructor Detail

    - #### public Options()

      Creates an options builder with the default JSON serialization settings.

  - ### Method Detail

    - #### public Options addConverter(Converter converter)

      Registers a converter that will be called when a type it handles is encountered.

      Parameters:
        `converter` - to register
      Returns:
        a reference to this `Options` instance

    - #### <T> public Options addConverter(Class<T> type, @ClosureParams(value=FromString.class, options={"T","T,String"})
      Closure<?> closure)

      Registers a closure that will be called when the specified type or subtype is serialized.

      The closure must accept either 1 or 2 parameters. The first parameter is required and will be instance of the `type` for which the closure is registered. The second optional parameter should be of type `String` and, if available, will be passed the name of the key associated with this value if serializing a JSON Object. This parameter will be `null` when serializing a JSON Array or when there is no way to determine the name of the key.

      Example:

               def generator = new groovy.json.JsonGenerator.Options()
                                   .addConverter(URL) { URL u ->
                                       u.getHost()
                                   }
                                   .build()

               def input = [domain: new URL('http://groovy-lang.org/json.html#_parser_variants')]

               assert generator.toJson(input) == '{"domain":"groovy-lang.org"}'

      If two or more closures are registered for the exact same type the last closure based on the order they were specified will be used. When serializing an object its type is compared to the list of registered types in the order they were given and the closure for the first suitable type will be called. Therefore, it is important to register more specific types first.

      Parameters:
        `type` - the type to convert
        `closure` - called when the registered type or any type assignable to the given type is encountered
      Type Parameters:
        `T` - the type this converter is registered to handle
      Returns:
        a reference to this `Options` instance
      Throws:
        NullPointerException if the given type or closure is null
        IllegalArgumentException if the given closure does not accept a parameter of the given type

    - #### public JsonGenerator build()

      Creates a JsonGenerator that is based on the current options.

      Returns:
        a fully configured JsonGenerator

    - #### public Options dateFormat(String format)

      Sets the date format that will be used to serialize `Date` objects. This must be a valid pattern for SimpleDateFormat and the date formatter will be constructed with the default locale of Locale.US.

      Parameters:
        `format` - date format pattern used to serialize dates
      Returns:
        a reference to this `Options` instance
      Throws:
        NullPointerException if the given pattern is null
        IllegalArgumentException if the given pattern is invalid

    - #### public Options dateFormat(String format, Locale locale)

      Sets the date format that will be used to serialize `Date` objects. This must be a valid pattern for SimpleDateFormat.

      Parameters:
        `format` - date format pattern used to serialize dates
        `locale` - the locale whose date format symbols will be used
      Returns:
        a reference to this `Options` instance
      Throws:
        IllegalArgumentException if the given pattern is invalid

    - #### public Options disableUnicodeEscaping()

      Disables the escaping of Unicode characters in JSON String values.

      Returns:
        a reference to this `Options` instance

    - #### public Options excludeFieldsByName(CharSequence fieldNames)

      Excludes from the output any fields that match the specified names.

      Parameters:
        `fieldNames` - name of the field to exclude from the output
      Returns:
        a reference to this `Options` instance

    - #### public Options excludeFieldsByName(Iterable<? extends CharSequence> fieldNames)

      Excludes from the output any fields that match the specified names.

      Parameters:
        `fieldNames` - collection of names to exclude from the output
      Returns:
        a reference to this `Options` instance

    - #### public Options excludeFieldsByType(Class<?> types)

      Excludes from the output any fields whose type is the same or is assignable to any of the given types.

      Parameters:
        `types` - excluded from the output
      Returns:
        a reference to this `Options` instance

    - #### public Options excludeFieldsByType(Iterable<Class<?>> types)

      Excludes from the output any fields whose type is the same or is assignable to any of the given types.

      Parameters:
        `types` - collection of types to exclude from the output
      Returns:
        a reference to this `Options` instance

    - #### public Options excludeNulls()

      Do not serialize `null` values.

      Returns:
        a reference to this `Options` instance

    - #### public Options timezone(String timezone)

      Sets the time zone that will be used to serialize dates.

      Parameters:
        `timezone` - used to serialize dates
      Returns:
        a reference to this `Options` instance
      Throws:
        NullPointerException if the given timezone is null