JsonGenerator.Options (groovy 2.5.23 API)

groovy.json.JsonGenerator.Options

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`
`protected static String`	`JSON_DATE_FORMAT`
`protected static Locale`	`JSON_DATE_FORMAT_LOCALE`
`protected Set<Converter>`	`converters`
`protected String`	`dateFormat`
`protected Locale`	`dateLocale`
`protected boolean`	`disableUnicodeEscaping`
`protected boolean`	`excludeNulls`
`protected Set<String>`	`excludedFieldNames`
`protected Set<Class<?>>`	`excludedFieldTypes`
`protected TimeZone`	`timezone`

Constructor Summary

Constructors
Constructor and description
`JsonGenerator.Options ()`

Methods Summary

Methods
Type Params	Return Type	Name and description
	`Options`	`addConverter(Converter converter)` Registers a converter that will be called when a type it handles is encountered.
`<T>`	`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.
	`Options`	`dateFormat(String format)` Sets the date format that will be used to serialize `Date` objects.
	`Options`	`dateFormat(String format, Locale locale)` Sets the date format that will be used to serialize `Date` objects.
	`Options`	`disableUnicodeEscaping()` Disables the escaping of Unicode characters in JSON String values.
	`Options`	`excludeFieldsByName(CharSequence... fieldNames)` Excludes from the output any fields that match the specified names.
	`Options`	`excludeFieldsByName(Iterable<? extends CharSequence> fieldNames)` Excludes from the output any fields that match the specified names.
	`Options`	`excludeFieldsByType(Class<?>... types)` Excludes from the output any fields whose type is the same or is assignable to any of the given types.
	`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.
	`Options`	`excludeNulls()` Do not serialize `null` values.
	`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`	`wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- Field Detail
  - protected static final String DEFAULT_TIMEZONE
  - protected static final String JSON_DATE_FORMAT
  - protected static final Locale JSON_DATE_FORMAT_LOCALE
  - protected final Set<Converter> converters
  - protected String dateFormat
  - protected Locale dateLocale
  - protected boolean disableUnicodeEscaping
  - protected boolean excludeNulls
  - protected final Set<String> excludedFieldNames
  - protected final Set<Class<?>> excludedFieldTypes
  - protected TimeZone timezone
- Constructor Detail
  - public JsonGenerator.Options()
- 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 the 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
    - 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

Summary:
Field
Constructor
Method

| Detail:
Field
Constructor
Method

[Java] Class Options

Field Summary

Constructor Summary

Methods Summary

Inherited Methods Summary

Field Detail

protected static final String DEFAULT_TIMEZONE

protected static final String JSON_DATE_FORMAT

protected static final Locale JSON_DATE_FORMAT_LOCALE

protected final Set<Converter> converters

protected String dateFormat

protected Locale dateLocale

protected boolean disableUnicodeEscaping

protected boolean excludeNulls

protected final Set<String> excludedFieldNames

protected final Set<Class<?>> excludedFieldTypes

protected TimeZone timezone

Constructor Detail

public JsonGenerator.Options()

Method Detail

public Options addConverter(Converter converter)

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

public JsonGenerator build()

public Options dateFormat(String format)

public Options dateFormat(String format, Locale locale)

public Options disableUnicodeEscaping()

public Options excludeFieldsByName(CharSequence... fieldNames)

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

public Options excludeFieldsByType(Class<?>... types)

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

public Options excludeNulls()

public Options timezone(String timezone)