Package groovy.json

# Class JsonGenerator.Options

java.lang.Object
groovy.json.JsonGenerator.Options

Enclosing interface:
  JsonGenerator

public static 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
  Modifier and Type
  Field
  Description
  `protected final Set<JsonGenerator.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 static final String`
  `DEFAULT_TIMEZONE`
  Default time zone ID used for JSON date values.
  `protected boolean`
  `disableUnicodeEscaping`
  Indicates whether Unicode escaping should be disabled.
  `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 boolean`
  `excludeNulls`
  Indicates whether `null` values should be omitted.
  `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 TimeZone`
  `timezone`
  Time zone used when serializing dates.

- ## Constructor Summary

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

- ## Method Summary

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

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### JSON_DATE_FORMAT

    protected static final String JSON_DATE_FORMAT
    Default date format pattern used for JSON date values.
    See Also:
      - Constant Field Values

  - ### JSON_DATE_FORMAT_LOCALE

    protected static final Locale JSON_DATE_FORMAT_LOCALE
    Default locale used with the JSON date format pattern.

  - ### DEFAULT_TIMEZONE

    protected static final String DEFAULT_TIMEZONE
    Default time zone ID used for JSON date values.
    See Also:
      - Constant Field Values

  - ### excludeNulls

    protected boolean excludeNulls
    Indicates whether `null` values should be omitted.

  - ### disableUnicodeEscaping

    protected boolean disableUnicodeEscaping
    Indicates whether Unicode escaping should be disabled.

  - ### dateFormat

    protected String dateFormat
    Date format pattern used when serializing dates.

  - ### dateLocale

    protected Locale dateLocale
    Locale used when serializing dates.

  - ### timezone

    protected TimeZone timezone
    Time zone used when serializing dates.

  - ### converters

    protected final Set<JsonGenerator.Converter> converters
    Registered converters applied before default serialization.

  - ### excludedFieldNames

    protected final Set<String> excludedFieldNames
    Field names excluded from generated JSON objects.

  - ### excludedFieldTypes

    protected final Set<Class<?>> excludedFieldTypes
    Field types excluded from generated JSON objects.

- ## Constructor Details

  - ### Options

    public Options()
    Creates an options builder with the default JSON serialization settings.

- ## Method Details

  - ### excludeNulls

    public JsonGenerator.Options excludeNulls()
    Do not serialize `null` values.
    Returns:
      a reference to this `Options` instance

  - ### disableUnicodeEscaping

    public JsonGenerator.Options disableUnicodeEscaping()
    Disables the escaping of Unicode characters in JSON String values.
    Returns:
      a reference to this `Options` instance

  - ### dateFormat

    public JsonGenerator.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

  - ### dateFormat

    public JsonGenerator.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

  - ### timezone

    public JsonGenerator.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

  - ### addConverter

    public JsonGenerator.Options addConverter(JsonGenerator.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

  - ### addConverter

    public <T> JsonGenerator.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.

    Type Parameters:
      `T` - the type this converter is registered to handle
    Parameters:
      `type` - the type to convert
      `closure` - called when the registered type or any type assignable to the given type is encountered
    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

  - ### excludeFieldsByName

    public JsonGenerator.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

  - ### excludeFieldsByName

    public JsonGenerator.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

  - ### excludeFieldsByType

    public JsonGenerator.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

  - ### excludeFieldsByType

    public JsonGenerator.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

  - ### build

    public JsonGenerator build()
    Creates a `JsonGenerator` that is based on the current options.
    Returns:
      a fully configured `JsonGenerator`