Package com.cedarsoftware.io

Class WriteOptionsBuilder

java.lang.Object
com.cedarsoftware.io.WriteOptionsBuilder
public class WriteOptionsBuilder extends Object
Builder class for building the writeOptions.
Author:
John DeRegnaucourt ([email protected]), Kenny Partlow ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

  • Field Details

  • Constructor Details

    • WriteOptionsBuilder

      public WriteOptionsBuilder()
      Start with default options

    • WriteOptionsBuilder

      public WriteOptionsBuilder(WriteOptions copy)
      Copy another WriteOptions as a starting point. If null is passed in, then you get the default options.

  • Method Details

    • addPermanentAlias

      public static void addPermanentAlias(Class<?> clazz, String alias)
      Call this method to add a permanent (JVM lifetime) alias of a class to an often shorter, name. All WriteOptions will automatically be created with any permanent aliases added to them.
      Parameters:
      clazz - Class that will be aliased by a shorter name in the JSON.
      alias - Shorter alias name, for example, "ArrayList" as opposed to "java.util.ArrayList"

    • removePermanentAliasTypeNamesMatching

      public static void removePermanentAliasTypeNamesMatching(String classNamePattern)
      Call this method to remove alias patterns from the WriteOptionsBuilder so that when it writes JSON, the classes that match the passed in pattern are not aliased. This API matches your wildcard pattern of *, ?, and characters against class names in its cache. It removes the entries (className to aliasName) from the cache to prevent the resultant classes from being aliased during output.
      Parameters:
      classNamePattern - String pattern to match class names. This String matches using a wild-card pattern, where * matches anything and ? matches one character. As many * or ? can be used as needed.

    • addPermanentExcludedField

      public static void addPermanentExcludedField(Class<?> clazz, String fieldName)
      Call this method to add a permanent (JVM lifetime) excluded field name of class. All WriteOptions will automatically be created this field field on the excluded list.
      Parameters:
      clazz - Class that contains the named field.
      fieldName - to be excluded.

    • addPermanentNonRef

      public static void addPermanentNonRef(Class<?> clazz)
      Call this method to add a permanent (JVM lifetime) class that should not be treated as referencable when being written out to JSON. This means it will never have an @id nor @ref. This feature is useful for small, immutable classes.
      Parameters:
      clazz - Class that will no longer be treated as referenceable when being written to JSON.

    • addPermanentWriter

      public static void addPermanentWriter(Class<?> clazz, JsonWriter.JsonClassWriter writer)
      Call this method to add a custom JSON writer to json-io. It will associate the Class 'c' to the writer you pass in. The writers are found with isAssignableFrom(). If this is too broad, causing too many classes to be associated to the custom writer, you can indicate that json-io should not use a custom write for a particular class, by calling the addNotCustomWrittenClass() method. This method will add the custom writer such that it will be there permanently, for the life of the JVM (static).
      Parameters:
      clazz - Class to assign a custom JSON writer to
      writer - The JsonClassWriter which will write the custom JSON format of class.

    • addPermanentNonStandardGetter

      public static void addPermanentNonStandardGetter(Class<?> clazz, String field, String methodName)
      This option permits adding non-standard getters (used when writing JSON) that access properties from objects, where the method name does not follow a standard setter/getter property name. For example, on java.time.Instance, to get the 'second' field, the accessor method is 'getEpochSecond()'. Anything added here will automatically be made in all WriteOptions.
      Parameters:
      clazz - Class that has the non-standard getter. java.time.Instance in the example above.
      field - String name of the class property. 'second' in the example above.
      methodName - The name of the non-standard method used to get the field value. 'getEpochSecond' in the example above.

    • addPermanentFieldFilter

      public static void addPermanentFieldFilter(String name, FieldFilter fieldFilter)
      Add a FieldFilter that is JVM lifecycle scoped.
      Parameters:
      fieldFilter - FieldFilter class used to eliminate fields from being included in the serialized JSON.

    • addPermanentMethodFilter

      public static void addPermanentMethodFilter(String name, MethodFilter methodFilter)
      Add a MethodFilter that is JVM lifecycle scoped. All WriteOptions instances will contain this filter.
      Parameters:
      name - String name of this particular MethodFilter instance.
      methodFilter - MethodFilter class used to eliminate a particular accessor method from being used.

    • addPermanentNamedMethodFilter

      public static void addPermanentNamedMethodFilter(String name, Class<?> clazz, String methodName)
      Add a MethodFilter that is JVM lifecycle scoped. All WriteOptions instances will contain this filter.
      Parameters:
      name - String name of this particular method filter instance.
      clazz - class that contains the method to be filtered (can be derived class, with field defined on parent class).
      methodName - String name of no-argument method to be filtered.

    • addPermanentAccessorFactory

      public static void addPermanentAccessorFactory(String name, AccessorFactory factory)
      Add an AccessorFactory that is JVM lifecycle scoped. All WriteOptions instances will contain this AccessorFactory. It is the job of an AccessorFactory to provide a possible method name for a particular field. json-io ships with a GetMethodAccessorFactory and an IsMethodAccessFactory. These produce a possible method name for a given field. When a field on a Java class is being accessed (read), and it cannot be obtained directly, then all AccessoryFactory instances will be consulted until an API can be used to read the field.
      Parameters:
      name - String name of AccessorFactory. Each factory should have it's own unique name. This will allow these to be defined in a file, later if needed.
      factory - AccessorFactory subclass.

    • classLoader

      public WriteOptionsBuilder classLoader(ClassLoader loader)
      Parameters:
      loader - ClassLoader to use when writing JSON to resolve String named classes.
      Returns:
      WriteOptionsBuilder for chained access.

    • shortMetaKeys

      public WriteOptionsBuilder shortMetaKeys(boolean shortMetaKeys)
      Parameters:
      shortMetaKeys - boolean true to turn on short meta-keys, false for long.
      Returns:
      WriteOptionsBuilder for chained access.

    • aliasTypeNames

      public WriteOptionsBuilder aliasTypeNames(Map<String,String> aliases)
      Parameters:
      aliases - Map containing String class names to alias names. The passed in Map will be copied, and be the new baseline settings.
      Returns:
      WriteOptionsBuilder for chained access.

    • aliasTypeName

      public WriteOptionsBuilder aliasTypeName(Class<?> type, String alias)
      Parameters:
      type - Class to alias
      alias - String shorter name to use, typically.
      Returns:
      WriteOptionsBuilder for chained access.

    • aliasTypeName

      public WriteOptionsBuilder aliasTypeName(String typeName, String alias)
      Parameters:
      typeName - String class name
      alias - String shorter name to use, typically.
      Returns:
      WriteOptionsBuilder for chained access.

    • removeAliasTypeNamesMatching

      public WriteOptionsBuilder removeAliasTypeNamesMatching(String typeNamePattern)
      Remove alias entries from this WriteOptionsBuilder instance where the Java fully qualified string class name matches the passed in wildcard pattern.
      Parameters:
      typeNamePattern - String pattern to match class names. This String matches using a wild-card pattern, where * matches anything and ? matches one character. As many * or ? can be used as needed.
      Returns:
      WriteOptionsBuilder for chained access.

    • showTypeInfoAlways

      public WriteOptionsBuilder showTypeInfoAlways()
      Set to always show type
      Returns:
      WriteOptionsBuilder for chained access.

    • showTypeInfoNever

      public WriteOptionsBuilder showTypeInfoNever()
      Set to never show type
      Returns:
      WriteOptionsBuilder for chained access.

    • showTypeInfoMinimal

      public WriteOptionsBuilder showTypeInfoMinimal()
      Set to show minimal type. This means that when the type of object can be inferred, a type field will not be output. A Field that points to an instance of the same time, or a typed [] of objects don't need the type info. However, an Object[], a Collection with no generics, the reader will need to know what type the JSON object is, in order to instantiate the write Java class to which the information will be copied.
      Returns:
      WriteOptionsBuilder for chained access.

    • prettyPrint

      public WriteOptionsBuilder prettyPrint(boolean prettyPrint)
      Parameters:
      prettyPrint - boolean 'prettyPrint' setting, true to turn on, false will turn off.
      Returns:
      WriteOptionsBuilder for chained access.

    • writeLongsAsStrings

      public WriteOptionsBuilder writeLongsAsStrings(boolean writeLongsAsStrings)
      Parameters:
      writeLongsAsStrings - boolean true to turn on writing longs as Strings, false to write them as native JSON longs.
      Returns:
      WriteOptionsBuilder for chained access.

    • skipNullFields

      public WriteOptionsBuilder skipNullFields(boolean skipNullFields)
      Parameters:
      skipNullFields - boolean setting, where true indicates fields with null values will not be written to the JSON, false will allow the field to still be written.
      Returns:
      WriteOptionsBuilder for chained access.

    • forceMapOutputAsTwoArrays

      public WriteOptionsBuilder forceMapOutputAsTwoArrays(boolean forceMapOutputAsTwoArrays)
      Parameters:
      forceMapOutputAsTwoArrays - boolean 'forceMapOutputAsTwoArrays' setting. true will force Java Maps to be written out as two parallel arrays, once for keys, one array for values. false will write out one JSON { } object, if all keys are Strings. If not, then the Map will be output as two parallel arrays (@keys:[...], @values:[...]).
      Returns:
      WriteOptionsBuilder for chained access.

    • allowNanAndInfinity

      public WriteOptionsBuilder allowNanAndInfinity(boolean allowNanAndInfinity)
      Parameters:
      allowNanAndInfinity - boolean 'allowNanAndInfinity' setting. true will allow Double and Floats to be output as NAN and INFINITY, false and these values will come across as null.
      Returns:
      WriteOptionsBuilder for chained access.

    • writeEnumsAsString

      public WriteOptionsBuilder writeEnumsAsString()
      Option to write out enums as a String, it will write out the enum.name() field. This is the default way enums will be written out.
      Returns:
      WriteOptionsBuilder for chained access.

    • writeEnumAsJsonObject

      public WriteOptionsBuilder writeEnumAsJsonObject(boolean writePublicFieldsOnly)
      Option to write out all the member fields of an enum. You can also filter the field to write out only the public fields on the enum.
      Parameters:
      writePublicFieldsOnly - boolean, only write out the public fields when writing enums as objects
      Returns:
      WriteOptionsBuilder for chained access.

    • closeStream

      public WriteOptionsBuilder closeStream(boolean closeStream)
      Parameters:
      closeStream - boolean set to 'true' to have JsonIo close the OutputStream when it is finished writing to it. The default is 'true'. If false, the OutputStream will not be closed, allowing you to continue writing further. Example, NDJSON that has new line eliminated JSON objects repeated.
      Returns:
      WriteOptionsBuilder for chained access.

    • setCustomWrittenClasses

      public WriteOptionsBuilder setCustomWrittenClasses(Map<Class<?>,JsonWriter.JsonClassWriter> customWrittenClasses)
      Parameters:
      customWrittenClasses - Map of Class to JsonWriter.JsonClassWriter. Establish the passed in Map as the established Map of custom writers to be used when writing JSON. Using this method more than once, will set the custom writers to only the values from the Set in the last call made.
      Returns:
      WriteOptionsBuilder for chained access.

    • addCustomWrittenClasses

      public WriteOptionsBuilder addCustomWrittenClasses(Map<Class<?>,JsonWriter.JsonClassWriter> customWrittenClasses)
      Parameters:
      customWrittenClasses - Map of Class to JsonWriter.JsonClassWriter. Adds all custom writers into the custom writers map.
      Returns:
      WriteOptionsBuilder for chained access.

    • addCustomWrittenClass

      public WriteOptionsBuilder addCustomWrittenClass(Class<?> clazz, JsonWriter.JsonClassWriter customWriter)
      Parameters:
      clazz - Class to add a custom writer for.
      customWriter - JsonClassWriter to use when the passed in Class is encountered during serialization.
      Returns:
      WriteOptionsBuilder for chained access.

    • addNotCustomWrittenClass

      public WriteOptionsBuilder addNotCustomWrittenClass(Class<?> notCustomClass)
      Add a class to the not-customized list - the list of classes that you do not want to be picked up by a custom writer (that could happen through inheritance).
      Parameters:
      notCustomClass - Class to add to the not-customized list.
      Returns:
      WriteOptionsBuilder for chained access.

    • setNotCustomWrittenClasses

      public WriteOptionsBuilder setNotCustomWrittenClasses(Collection<Class<?>> notCustomClasses)
      Parameters:
      notCustomClasses - initialize the list of classes on the non-customized list. All prior associations will be dropped and this Collection will establish the new list.
      Returns:
      WriteOptionsBuilder for chained access.

    • addIncludedField

      public WriteOptionsBuilder addIncludedField(Class<?> clazz, String includedFieldName)
      Parameters:
      clazz - Class to add a single field to be included in the written JSON.
      includedFieldName - String name of field to include in written JSON.
      Returns:
      WriteOptionsBuilder for chained access.

    • addIncludedFields

      public WriteOptionsBuilder addIncludedFields(Class<?> clazz, Collection<String> includedFieldNames)
      Parameters:
      clazz - Class to add a Collection of fields to be included in written JSON.
      includedFieldNames - Collection of String name of fields to include in written JSON.
      Returns:
      WriteOptionsBuilder for chained access.

    • addIncludedFields

      public WriteOptionsBuilder addIncludedFields(Map<Class<?>,Collection<String>> includedFieldNames)
      Parameters:
      includedFieldNames - Map of Class's mapped to Collection of String field names to include in the written JSON.
      Returns:
      WriteOptionsBuilder for chained access.

    • addExcludedField

      public WriteOptionsBuilder addExcludedField(Class<?> clazz, String excludedFieldName)
      Parameters:
      clazz - Class to add a single field to be excluded.
      excludedFieldName - String name of field to exclude from written JSON.
      Returns:
      WriteOptionsBuilder for chained access.

    • addExcludedFields

      public WriteOptionsBuilder addExcludedFields(Class<?> clazz, Collection<String> excludedFields)
      Parameters:
      clazz - Class to add a Collection of fields to be excluded in written JSON.
      excludedFields - Collection of String name of fields to exclude in written JSON.
      Returns:
      WriteOptionsBuilder for chained access.

    • addExcludedFields

      public WriteOptionsBuilder addExcludedFields(Map<Class<?>,Collection<String>> excludedFieldNames)
      Parameters:
      excludedFieldNames - Map of Class's mapped to Collection of String field names to exclude from written JSON.
      Returns:
      WriteOptionsBuilder for chained access.

    • isoDateFormat

      public WriteOptionsBuilder isoDateFormat()
      Change the date-time format to the ISO date format: "yyyy-MM-dd". This is for java.util.Data and java.sql.Date.
      Returns:
      WriteOptionsBuilder for chained access.

    • isoDateTimeFormat

      public WriteOptionsBuilder isoDateTimeFormat()
      Change the date-time format to the ISO date-time format: "yyyy-MM-dd'T'HH:mm:ss" (default). This is for java.util.Date and java.sql.Date.
      Returns:
      WriteOptionsBuilder for chained access.

    • longDateFormat

      public WriteOptionsBuilder longDateFormat()
      Change the java.uti.Date and java.sql.Date format output to a "long," the number of seconds since Jan 1, 1970 at midnight. Useful if you do not need to see the JSON, and want to keep the format smaller. This is for java.util.Date and java.sql.Date.
      Returns:
      WriteOptionsBuilder for chained access.

    • dateTimeFormat

      public WriteOptionsBuilder dateTimeFormat(String format)
      Change the date-time format to the passed in format. The format pattens can be found in the Java Doc for the java.time.format.DateTimeFormatter class. There are many constants you can use, as well as the definition of how to construct your own patterns. This is for java.util.Date and java.sql.Date.
      Returns:
      WriteOptionsBuilder for chained access.

    • addNonStandardGetter

      public WriteOptionsBuilder addNonStandardGetter(Class<?> c, String fieldName, String methodName)
      This option permits adding non-standard accessors (used when writing JSON) that access properties from objects, where the method name does not follow a standard setter/getter property name. For example, on java.time.Instance, to get the 'second' field, the accessor method is 'getEpochSecond()'.
      Parameters:
      c - Class that has the non-standard accessor. java.time.Instance in the example above.
      fieldName - String name of the class property. 'second' in the example above.
      methodName - The name of the non-standard method used to get the field value. 'getEpochSecond' in the example above.
      Returns:
      WriteOptionsBuilder for chained access.

    • addNonReferenceableClass

      public WriteOptionsBuilder addNonReferenceableClass(Class<?> clazz)
      Parameters:
      clazz - class to add to be considered a non-referenceable object. Just like an "int" for example, any class added here will never use an @id/@ref pair. The downside, is that when read, each instance, even if the same as another, will use memory.
      Returns:
      WriteOptionsBuilder for chained access.

    • addCustomOption

      public WriteOptionsBuilder addCustomOption(String key, Object value)
      Add a custom option, which may be useful when writing custom writers. To remove a custom option, add the option with the appropriate key and null as the value.
      Parameters:
      key - String name of the custom option
      value - Object value of the custom option
      Returns:
      WriteOptionsBuilder for chained access.

    • addFieldFilter

      public WriteOptionsBuilder addFieldFilter(String filterName, FieldFilter filter)
      Add FieldFilter to the field filter chain. FieldFilters are presented a chance to eliminate a field by returning true from its boolean filter() method. If any FieldFilter returns true, the field is excluded.
      Parameters:
      filterName - String name of filter
      filter - FieldFilter to add
      Returns:
      WriteOptionsBuilder for chained access.

    • removeFieldFilter

      public WriteOptionsBuilder removeFieldFilter(String filterName)
      Remove named FieldFilter from the filter chain.
      Parameters:
      filterName - String name of FieldFilter to delete
      Returns:
      WriteOptionsBuilder for chained access.

    • addMethodFilter

      public WriteOptionsBuilder addMethodFilter(String filterName, MethodFilter methodFilter)
      Add MethodFilter to the filter chain. MethodFilters are presented a chance to eliminate a "getter" type accessing method by returning true from the boolean filter() method. If any MethodFilter returns true, the accessor method is excluded. This means it will drop back to use field access (attempting to access private field in same module with setAccessible()). This API is used when you want to write your own implementation of a MethodFilter.
      Parameters:
      filterName - String name of filter
      methodFilter - MethodFilter to add
      Returns:
      WriteOptionsBuilder for chained access.

    • addNamedMethodFilter

      public WriteOptionsBuilder addNamedMethodFilter(String filterName, Class<?> clazz, String methodName)
      Add a NamedMethodFilter to the filter chain. NamedMethodFilters are presented a chance to eliminate a "getter" type accessing method by returning true from the boolean filter() method. If the NamedMethodFilter matches a class and accessor method name, and it has no args, is public, and non-static, the accessor method is excluded. This means it will drop back to use field access (attempting to access private field in same module with setAccessible()).
      Parameters:
      filterName - String name of filter
      clazz - Class containing method to filter
      methodName - String name of method to not use for accessing value.
      Returns:
      WriteOptionsBuilder for chained access.

    • removeMethodFilter

      public WriteOptionsBuilder removeMethodFilter(String filterName)
      Remove named MethodFilter from the method filter chain.
      Parameters:
      filterName - String name of filter
      Returns:
      WriteOptionsBuilder for chained access.

    • addAccessorFactory

      public WriteOptionsBuilder addAccessorFactory(String factoryName, AccessorFactory accessorFactory)
      Add AccessorFactory to the accessor factories chain. AccessFactories permit adding a standard pattern of locating "read" methods, for example, there is a built-in "get" and "is" AccessoryFactory.
      Parameters:
      factoryName - String name of accessor factory
      accessorFactory - AccessorFactory to add
      Returns:
      WriteOptionsBuilder for chained access.

    • removeAccessorFactory

      public WriteOptionsBuilder removeAccessorFactory(String factoryName)
      Remove named AccessorFactory from the access factories.
      Parameters:
      factoryName - String name of accessor filter
      Returns:
      WriteOptionsBuilder for chained access.

    • build

      public WriteOptions build()
      Seal the instance of this class so that no more changes can be made to it.
      Returns:
      WriteOptionsBuilder for chained access.