Package com.cedarsoftware.io

Class ReadOptionsBuilder

java.lang.Object
com.cedarsoftware.io.ReadOptionsBuilder
public class ReadOptionsBuilder 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.

  • Constructor Details

    • ReadOptionsBuilder

      public ReadOptionsBuilder()
      Start with default options

    • ReadOptionsBuilder

      public ReadOptionsBuilder(ReadOptions copy)
      Start with a copy of another ReadOptions. If copy is null, then you get the default options.

  • Method Details

    • getDefaultReadOptions

      public static ReadOptions getDefaultReadOptions()
      Returns:
      Default ReadOptions - no construction needed, unmodifiable.

    • addPermanentClassFactory

      public static void addPermanentClassFactory(Class<?> sourceClass, JsonReader.ClassFactory factory)
      Call this method to add a factory class that will be used to create instances of another class. This is useful when you have a class that `json-io` cannot instantiate due to private or other constructor issues. Add a JsonReader.ClassFactory class (that you implement) and associate it to the passed in 'classToCreate'. Your JsonReader.ClassFactory class will be called with the Map (JsonObject) that contains the { ... } that should be loaded into your class. It is your ClassFactory implementations job to create the instance of the associated class, and then copy the values from the passed in Map to the Java instance you created.
      Parameters:
      sourceClass - String class name (fully qualified name) to associate to your ClassFactory implementation.
      factory - JsonReader.ClassFactory your ClassFactory implementation that creates/loads the associated class using the Map (JsonObject) of data passed to it.

    • assignInstantiator

      @Deprecated public static void assignInstantiator(Class<?> classToCreate, JsonReader.ClassFactory factory)
      Deprecated.
      use addPermanentClassFactory(java.lang.Class<?>, com.cedarsoftware.io.JsonReader.ClassFactory) instead.
      Parameters:
      classToCreate - Class that will need to use a JsonReader.ClassFactory for instantiation and loading.
      factory - JsonReader.ClassFactory instance that has been created to instantiate a difficult to create and load class (class c).

    • addPermanentCoercedType

      public static void addPermanentCoercedType(Class<?> sourceClass, Class<?> destinationClass)
      Call this method to add a permanent (JVM lifetime) coercion of one class to another during instance creation. Examples of classes that might need this are proxied classes such as HibernateBags, etc. That you want to create as regular jvm collections.
      Parameters:
      sourceClass - String class name (fully qualified name) that will be coerced to another type.
      destinationClass - Class to coerce to. For example, java.util.Collections$EmptyList to java.util.ArrayList.

    • addPermanentAlias

      public static void addPermanentAlias(Class<?> sourceClass, String alias)
      Call this method to add a permanent (JVM lifetime) alias of a class to an often shorter, name.
      Parameters:
      sourceClass - String class name (fully qualified name) 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 ReadsOptionsBuilder. Be careful doing so. In a micro-services environment, you want the receiving services to know as many substitutions as possible. It is important to control the aliases on the "written" side, to ensure that written JSON does not include aliases that the receiving micro-services do not yet 'understand.' Therefore, you should rarely need this API.

      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.

    • addPermanentReader

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

    • addPermanentNonReferenceableClass

      public static void addPermanentNonReferenceableClass(Class<?> clazz)
      Add a class permanently (JVM lifecycle) to the Non-referenceable list. All new ReadOptions instances created will automatically start with this, and you will not need to add it into the ReadOptions through the ReadOptionsBuilder each time.
      Parameters:
      clazz - Class to be added to the non-reference list. A class that is on this list, will be written out to the JSON fully, each time it is encountered, and never be written with an @ref. Use for very simple, atomic type (single field classes).

    • addPermanentNotImportedField

      public static void addPermanentNotImportedField(Class<?> clazz, String fieldName)
      Add a field to a class that should not be imported. Any class's field added here will be excluded when read from the JSON. The value will not be set (injected) into the associated Java instance.
      Parameters:
      clazz - Class on which fields will be excluded.
      fieldName - String field name to exclude for the given class.

    • addPermanentNonStandardSetter

      public static void addPermanentNonStandardSetter(Class<?> clazz, String fieldName, String alias)
      Add the String name of the "setter" (injector) associated to the field name. mappings for the passed in Class.
      Parameters:
      clazz - Class to which the association will be added.
      fieldName - String name of field that has a non-standard setter (injector)
      alias - String name of setter method that is used to write to the fieldName. An example is Throwable's initCause() setter which does not follow a standard naming convention (should be 'setCause()'). In this example, use addPermanentNonStandardSetter(Throwable.class, "cause", "initCause").

    • build

      public ReadOptions build()
      Returns:
      ReadOptions - built options

    • addInjectorFactory

      public ReadOptionsBuilder addInjectorFactory(InjectorFactory factory)
      Add a class to the injector factory list - allows to add injector to the class
      Parameters:
      factory - Class to add to the injector factory list.
      Returns:
      ReadOptionsBuilder for chained access.

    • addFieldFilter

      public ReadOptionsBuilder addFieldFilter(FieldFilter filter)
      Add a class to the field filter list - allows adding more field filter types
      Parameters:
      filter - FieldFilter to add
      Returns:
      ReadOptionsBuilder for chained access.

    • addNotCustomReaderClass

      public ReadOptionsBuilder addNotCustomReaderClass(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 reader (that could happen through inheritance).
      Parameters:
      notCustomClass - Class to add to the not-customized list.
      Returns:
      ReadOptionsBuilder for chained access.

    • replaceNotCustomReaderClasses

      public ReadOptionsBuilder replaceNotCustomReaderClasses(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:
      ReadOptionsBuilder for chained access.

    • addConverterOverride

      public ReadOptionsBuilder addConverterOverride(Class<?> source, Class<?> target, com.cedarsoftware.util.convert.Convert<?> conversionFunction)
      Parameters:
      source - source class.
      target - target class.
      conversionFunction - functional interface to run Conversion.
      Returns:
      ReadOptionsBuilder for chained access.

    • replaceCustomReaderClasses

      public ReadOptionsBuilder replaceCustomReaderClasses(Map<? extends Class<?>,? extends JsonReader.JsonClassReader> customReaderClasses)
      Parameters:
      customReaderClasses - Map of Class to JsonReader.JsonClassReader. Establish the passed in Map as the established Map of custom readers to be used when reading JSON. Using this method more than once, will set the custom readers to only the values from the Set in the last call made.
      Returns:
      ReadOptionsBuilder for chained access.

    • addCustomReaderClass

      public ReadOptionsBuilder addCustomReaderClass(Class<?> clazz, JsonReader.JsonClassReader customReader)
      Parameters:
      clazz - Class to add a custom reader for.
      customReader - JsonClassReader to use when the passed in Class is encountered during serialization. Custom readers are passed an empty instance. Use a ClassFactory if you want to instantiate and load the class in one step.
      Returns:
      ReadOptionsBuilder for chained access.

    • replaceClassFactories

      public ReadOptionsBuilder replaceClassFactories(Map<Class<?>,? extends JsonReader.ClassFactory> factories)
      Associate multiple ClassFactory instances to Classes that needs help being constructed and read in.
      Parameters:
      factories - Map of entries that are Class to Factory. The Factory class knows how to instantiate and load the class associated to it.
      Returns:
      ReadOptionsBuilder for chained access.

    • addClassFactory

      public ReadOptionsBuilder addClassFactory(Class<?> clazz, JsonReader.ClassFactory factory)
      Associate a ClassFactory to a Class that needs help being constructed and read in.
      Parameters:
      clazz - Class that is difficult to instantiate.
      factory - Class written to instantiate the 'clazz' and load it's values.
      Returns:
      ReadOptionsBuilder for chained access.

    • returnAsNativeJsonObjects

      public ReadOptionsBuilder returnAsNativeJsonObjects()
      Set to return as JSON_OBJECTS's (faster, useful for large, more simple object data sets). This returns as native json types (Map, Object[], long, double, boolean)

    • returnAsJavaObjects

      public ReadOptionsBuilder returnAsJavaObjects()
      Return as JAVA_OBJECT's the returned value will be of the class type passed into JsonReader.toJava(json, rootClass). This mode is good for cloning exact objects.

    • floatPointDouble

      public ReadOptionsBuilder floatPointDouble()
      Set Floating Point types to be returned as Doubles. This is the default.

    • floatPointBigDecimal

      public ReadOptionsBuilder floatPointBigDecimal()
      Set Floating Point types to be returned as BigDecimals.

    • floatPointBoth

      public ReadOptionsBuilder floatPointBoth()
      Set Floating Point types to be returned as either Doubles or BigDecimals, depending on precision required to hold the number sourced from JSON.

    • integerTypeLong

      public ReadOptionsBuilder integerTypeLong()
      Set Integer Types to be returned as Longs. This is the default.

    • integerTypeBigInteger

      public ReadOptionsBuilder integerTypeBigInteger()
      Set Integer Types to be returned as BigIntegers.

    • integerTypeBoth

      public ReadOptionsBuilder integerTypeBoth()
      Set Integer Types to be returned as either Longs or BigIntegers, depending on precision required to hold the number sourced from JSON.

    • classLoader

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

    • failOnUnknownType

      public ReadOptionsBuilder failOnUnknownType(boolean fail)
      Parameters:
      fail - boolean indicating whether we should fail on unknown type encountered.
      Returns:
      ReadOptionsBuilder for chained access.

    • unknownTypeClass

      public ReadOptionsBuilder unknownTypeClass(Class<?> c)
      Set a class to use when the JSON reader cannot instantiate a class. When that happens, it will throw a JsonIoException() if no 'unknownTypeClass' is set, otherwise it will create the instance of the class specified as the 'unknownTypeClass.' A common one to use, for example, if java.util.LinkedHashMap.
      Parameters:
      c - Class to instantiate when a String specified class in the JSON cannot be instantiated. Set to null if you want a JsonIoException to be thrown when this happens.
      Returns:
      ReadOptionsBuilder for chained access.

    • closeStream

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

    • maxDepth

      public ReadOptionsBuilder maxDepth(int maxDepth)
      Parameters:
      maxDepth - int maximum of the depth that JSON Objects {...} can be nested. Set this to prevent security risk from StackOverflow attack vectors.
      Returns:
      ReadOptionsBuilder for chained access.

    • lruSize

      public ReadOptionsBuilder lruSize(int lruSize)
      Parameters:
      lruSize - int maximum size of the LRU cache that holds reflective information like fields of a Class and injectors associated to a class.
      Returns:
      ReadOptionsBuilder for chained access.

    • allowNanAndInfinity

      public ReadOptionsBuilder allowNanAndInfinity(boolean allowNanAndInfinity)
      Parameters:
      allowNanAndInfinity - boolean 'allowNanAndInfinity' setting. true will allow Double and Floats to be read in as NaN and +Inf, -Inf [infinity], false and a JsonIoException will be thrown if these values are encountered
      Returns:
      ReadOptionsBuilder for chained access.

    • aliasTypeNames

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

    • aliasTypeName

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

    • aliasTypeName

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

    • removeAliasTypeNameMatching

      public ReadOptionsBuilder removeAliasTypeNameMatching(String typeNamePattern)
      Remove alias entries from this ReadOptionsBuilder 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:
      ReadOptionsBuilder for chained access.

    • setLocale

      public ReadOptionsBuilder setLocale(Locale locale)
      Parameters:
      locale - target locale for conversions
      Returns:
      ReadOptionsBuilder for chained access.

    • setCharset

      public ReadOptionsBuilder setCharset(Charset charset)
      Parameters:
      charset - source charset for conversions
      Returns:
      ReadOptionsBuilder for chained access.

    • setZoneId

      public ReadOptionsBuilder setZoneId(ZoneId zoneId)
      Parameters:
      zoneId - source charset for conversions
      Returns:
      ReadOptionsBuilder for chained access.

    • setTrueCharacter

      public ReadOptionsBuilder setTrueCharacter(Character ch)
      Parameters:
      ch - Character used when converting true -> char
      Returns:
      ReadOptionsBuilder for chained access.

    • setFalseCharacter

      public ReadOptionsBuilder setFalseCharacter(Character ch)
      Parameters:
      ch - Character used when converting false -> char
      Returns:
      ReadOptionsBuilder for chained access.

    • addCustomOption

      public ReadOptionsBuilder addCustomOption(String key, Object value)
      Add a custom option, which may be useful when writing custom readers.
      Parameters:
      key - String name of the custom option
      value - Object value of the custom option
      Returns:
      ReadOptionsBuilder for chained access.

    • coerceClass

      public ReadOptionsBuilder coerceClass(String sourceClassName, Class<?> destClass)
      Coerce a class from one type (named in the JSON) to another type. For example, converting "java.util.Collections$SingletonSet" to a LinkedHashSet.class.
      Parameters:
      sourceClassName - String class name to coerce to another type.
      destClass - Class to coerce into.
      Returns:
      ReadOptionsBuilder for chained access.

    • missingFieldHandler

      public ReadOptionsBuilder missingFieldHandler(JsonReader.MissingFieldHandler missingFieldHandler)
      Parameters:
      missingFieldHandler - JsonReader.MissingFieldHandler implementation to call. This method will be called when a field in the JSON is read in, yet there is no corresponding field on the destination object to receive the value.
      Returns:
      ReadOptionsBuilder for chained access.

    • addNonReferenceableClass

      public ReadOptionsBuilder 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:
      ReadOptionsBuilder for chained access.