Package groovy.json

Class 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 Detail

      • JSON_DATE_FORMAT_LOCALE

        protected static final Locale JSON_DATE_FORMAT_LOCALE

      • excludeNulls

        protected boolean excludeNulls

      • disableUnicodeEscaping

        protected boolean disableUnicodeEscaping

      • dateFormat

        protected String dateFormat

      • dateLocale

        protected Locale dateLocale

      • excludedFieldNames

        protected final Set<String> excludedFieldNames

      • excludedFieldTypes

        protected final Set<Class<?>> excludedFieldTypes

    • Constructor Detail

      • Options

        public Options()

    • Method Detail

      • 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,
                                              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.

        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