Package com.cedarsoftware.io

Interface ReadOptions

public interface ReadOptions
This class contains all the "feature" control (options) for controlling json-io's flexibility in reading JSON. An instance of this class is passed to the JsonReader.toJson() APIs to set the desired features.

You can make this class immutable and then store the class for re-use. Call the ".build()" method and then no longer can any methods that change state be called - it will throw a JsonIoException.

This class can be created from another ReadOptions instance, using the "copy constructor" that takes a ReadOptions. All properties of the other ReadOptions will be copied to the new instance, except for the 'built' property. That always starts off as false (mutable) so that you can make changes to options.

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.

  • Method Details

    • isFloatingPointDouble

      boolean isFloatingPointDouble()
      Returns:
      true if floating point values should always be returned as Doubles. This is the default.

    • isFloatingPointBigDecimal

      boolean isFloatingPointBigDecimal()
      Returns:
      true if floating point values should always be returned as BigDecimals.

    • isFloatingPointBoth

      boolean isFloatingPointBoth()
      Returns:
      true if floating point values should always be returned dynamically, as Double or BigDecimal, favoring Double except when precision would be lost, then BigDecimal is returned.

    • isIntegerTypeLong

      boolean isIntegerTypeLong()
      Returns:
      true if integer values should always be returned as Longs. This is the default.

    • isIntegerTypeBigInteger

      boolean isIntegerTypeBigInteger()
      Returns:
      true if integer values should always be returned as BigIntegers.

    • isIntegerTypeBoth

      boolean isIntegerTypeBoth()
      Returns:
      true if integer values should always be returned dynamically, as Long or BigInteger, favoring Long except when precision would be lost, then BigInteger is returned.

    • isAllowNanAndInfinity

      boolean isAllowNanAndInfinity()

    • getClassLoader

      ClassLoader getClassLoader()
      Returns:
      ClassLoader to be used when reading JSON to resolve String named classes.

    • isFailOnUnknownType

      boolean isFailOnUnknownType()
      Returns:
      boolean true if an 'unknownTypeClass' is set, false if it is not sell (null).

    • getUnknownTypeClass

      Class<?> getUnknownTypeClass()
      Returns:
      the Class which will have unknown fields set upon it. Typically this is a Map derivative.

    • isCloseStream

      boolean isCloseStream()
      Returns:
      boolean 'true' if the InputStream should be closed when the reading is finished. The default is 'true.'

    • getMaxDepth

      int getMaxDepth()
      Returns:
      int maximum level the JSON can be nested. Once the parsing nesting level reaches this depth, a JsonIoException will be thrown instead of a StackOverflowException. Prevents security risk from StackOverflow attack vectors.

    • getMaxUnresolvedReferences

      int getMaxUnresolvedReferences()
      Returns:
      int maximum number of unresolved references allowed during JSON processing. Once this limit is reached, a JsonIoException will be thrown to prevent memory exhaustion from DoS attacks via unbounded forward references. Default is Integer.MAX_VALUE (unlimited).

    • getMaxStackDepth

      int getMaxStackDepth()
      Returns:
      int maximum traversal stack depth allowed during JSON processing. Once this limit is reached, a JsonIoException will be thrown to prevent stack overflow attacks via deeply nested structures. Default is Integer.MAX_VALUE (unlimited).

    • getMaxMapsToRehash

      int getMaxMapsToRehash()
      Returns:
      int maximum number of maps that can be queued for rehashing during JSON processing. Once this limit is reached, a JsonIoException will be thrown to prevent memory exhaustion from DoS attacks via excessive map creation. Default is Integer.MAX_VALUE (unlimited).

    • getMaxMissingFields

      int getMaxMissingFields()
      Returns:
      int maximum number of missing fields that can be tracked during JSON processing. Once this limit is reached, a JsonIoException will be thrown to prevent memory exhaustion from DoS attacks via excessive missing field tracking. Default is Integer.MAX_VALUE (unlimited).

    • getMaxObjectReferences

      int getMaxObjectReferences()
      Returns:
      int maximum number of object references that can be tracked during JSON processing. Once this limit is reached, a JsonIoException will be thrown to prevent memory exhaustion from DoS attacks via unbounded object reference growth. Default is 10,000,000 for backward compatibility.

    • getMaxReferenceChainDepth

      int getMaxReferenceChainDepth()
      Returns:
      int maximum depth of reference chains that can be traversed during JSON processing. Once this limit is reached, a JsonIoException will be thrown to prevent infinite loops from circular reference attacks. Default is 10,000 for backward compatibility.

    • getMaxEnumNameLength

      int getMaxEnumNameLength()
      Returns:
      int maximum length of enum name strings during JSON processing. Once this limit is reached, a JsonIoException will be thrown to prevent memory exhaustion from DoS attacks via excessively long enum names. Default is 256 for backward compatibility.

    • getMaxIdValue

      long getMaxIdValue()
      Returns:
      long maximum absolute value for @id and @ref values during JSON processing. Once this limit is exceeded, a JsonIoException will be thrown to prevent issues with extreme ID values. Default is 1,000,000,000 for backward compatibility.

    • getStringBufferSize

      int getStringBufferSize()
      Returns:
      int initial capacity for string parsing buffers during JSON processing. This affects memory allocation for string parsing operations. Default is 256 for backward compatibility.

    • getThreadLocalBufferSize

      int getThreadLocalBufferSize()
      Returns:
      int size for ThreadLocal string processing buffers during JSON parsing. This affects memory allocation for string processing operations. Default is 1024 for backward compatibility.

    • getLargeThreadLocalBufferSize

      int getLargeThreadLocalBufferSize()
      Returns:
      int size for ThreadLocal large string processing buffers during JSON parsing. This affects memory allocation for large string processing operations. Default is 8192 for backward compatibility.

    • getMaxAllowedLength

      int getMaxAllowedLength()
      Returns:
      int maximum allowed length for argument character processing in MetaUtils. Once this limit is exceeded, content will be truncated to prevent memory exhaustion. Default is 65536 (64KB) for backward compatibility.

    • getMaxFileContentSize

      int getMaxFileContentSize()
      Returns:
      int maximum file content size in bytes when loading resource files in MetaUtils. Once this limit is exceeded, a JsonIoException will be thrown to prevent memory exhaustion from DoS attacks via oversized resource files. Default is 1048576 (1MB) for backward compatibility.

    • getMaxLineCount

      int getMaxLineCount()
      Returns:
      int maximum number of lines when processing resource files in MetaUtils. Once this limit is exceeded, a JsonIoException will be thrown to prevent resource exhaustion from DoS attacks via files with excessive line counts. Default is 10000 for backward compatibility.

    • getMaxLineLength

      int getMaxLineLength()
      Returns:
      int maximum length per line when processing resource files in MetaUtils. Once this limit is exceeded, a JsonIoException will be thrown to prevent memory exhaustion from DoS attacks via excessively long lines. Default is 8192 (8KB) for backward compatibility.

    • getLruSize

      int getLruSize()
      Returns:
      int size of LRU Cache used to cache Class to Field and Class to injectors

    • getTypeNameAlias

      String getTypeNameAlias(String typeName)
      Alias Type Names, e.g. "ArrayList" instead of "java.util.ArrayList".
      Parameters:
      typeName - String name of type to fetch alias for. There are no default aliases.
      Returns:
      String alias name or null if type name is not aliased.

    • isClassCoerced

      boolean isClassCoerced(Class<?> clazz)
      Returns:
      boolean true if the passed in Class is being coerced to another type, false otherwise.

    • getCoercedClass

      Class<?> getCoercedClass(Class<?> c)
      Fetch the coerced class for the passed in fully qualified class name.
      Parameters:
      c - Class to coerce
      Returns:
      Class destination (coerced) class or null if there is none.

    • getMissingFieldHandler

      JsonReader.MissingFieldHandler getMissingFieldHandler()
      Returns:
      JsonReader.MissingFieldHandler to be called when a field in the JSON is read in, yet there is no corresponding field on the destination object to receive the field value.

    • isNonReferenceableClass

      boolean isNonReferenceableClass(Class<?> clazz)
      Parameters:
      clazz - Class to check to see if it is non-referenceable. Non-referenceable classes will always create a new instance when read in and never use @id/@ref. This uses more memory when the JSON is read in, as there will be a separate instance in memory for each occurrence. There are certain classes that json-io automatically treats as non-referenceable, like Strings, Enums, Class, and any Number instance (BigDecimal, AtomicLong, etc.) You can add to this list. Often, non-referenceable classes are useful for classes that can be defined in one line as a JSON, like a LocalDateTime, for example.
      Returns:
      boolean true if the passed in class is considered a non-referenceable class.

    • isNotCustomReaderClass

      boolean isNotCustomReaderClass(Class<?> clazz)
      Parameters:
      clazz - Class to see if it is on the not-customized list. Classes are added to this list when a class is being picked up through inheritance, and you don't want it to have a custom reader associated to it.
      Returns:
      boolean true if the passed in class is on the not-customized list, false otherwise.

    • isCustomReaderClass

      boolean isCustomReaderClass(Class<?> clazz)
      Parameters:
      clazz - Class to check to see if there is a custom reader associated to it.
      Returns:
      boolean true if there is an associated custom reader class associated to the passed in class, false otherwise.

    • getClassFactory

      JsonReader.ClassFactory getClassFactory(Class<?> c)
      Get the ClassFactory associated to the passed in class.
      Parameters:
      c - Class for which to fetch the ClassFactory.
      Returns:
      JsonReader.ClassFactory instance associated to the passed in class.

    • getCustomReader

      JsonReader.JsonClassReader getCustomReader(Class<?> c)
      Fetch the custom reader for the passed in Class. If it is cached (already associated to the passed in Class), return the same instance, otherwise, make a call to get the custom reader and store that result.
      Parameters:
      c - Class of object for which fetch a custom reader
      Returns:
      JsonClassReader for the custom class (if one exists), null otherwise.

    • isReturningJsonObjects

      boolean isReturningJsonObjects()
      Returns:
      true if returning items in basic JSON object format

    • isReturningJavaObjects

      boolean isReturningJavaObjects()
      Returns:
      true if returning items in full Java object formats. Useful for accurate reproduction of graphs into the orginal types such as when cloning objects.

    • getDeepInjectorMap

      Map<String,Injector> getDeepInjectorMap(Class<?> classToTraverse)

    • clearCaches

      void clearCaches()

    • getDeepDeclaredFields

      Map<String,Field> getDeepDeclaredFields(Class<?> c)
      Gets the declared fields for the full class hierarchy of a given class
      Parameters:
      c - - given class.
      Returns:
      Map - map of string fieldName to Field Object. This will have the deep list of fields for a given class.

    • getConverterOptions

      com.cedarsoftware.util.convert.ConverterOptions getConverterOptions()

    • getCustomOption

      Object getCustomOption(String key)
      Get a custom option
      Parameters:
      key - String name of the custom option
      Returns:
      Object value of the custom option

    • getMaxTypeResolutionCacheSize

      int getMaxTypeResolutionCacheSize()
      Returns:
      int maximum size of the type resolution cache used by JsonValue to avoid repeated type checks. Default is 1,000 entries. This prevents unbounded memory growth while maintaining performance benefits. The cache is used to store whether Java Types are fully resolved (no type variables).

    • getDefaultCollectionCapacity

      int getDefaultCollectionCapacity()
      Returns:
      int default initial capacity for newly created collections when no size information is available. This affects memory allocation for ArrayList, LinkedHashSet, and other collection types created during JSON parsing. Default is 16 for backward compatibility. Lower values save memory, higher values reduce reallocations.

    • getCollectionLoadFactor

      float getCollectionLoadFactor()
      Returns:
      float load factor used for hash-based collections (HashSet, LinkedHashSet, HashMap, LinkedHashMap). This controls when collections will resize based on their fill ratio. Default is 0.75f for backward compatibility. Lower values use more memory but provide better performance, higher values use less memory but may reduce performance.

    • getMinCollectionCapacity

      int getMinCollectionCapacity()
      Returns:
      int minimum initial capacity enforced for all collections regardless of detected size. This prevents extremely small initial allocations that could cause excessive reallocations. Default is 16 for backward compatibility. Set to 1 to disable minimum capacity enforcement.

    • getLinearSearchThreshold

      int getLinearSearchThreshold()
      Returns:
      int threshold for switching between linear and binary search in JsonObject operations. For arrays with size <= this threshold, linear search is used for better cache locality. For larger arrays, more sophisticated search algorithms may be used if applicable. Default is 8 for backward compatibility based on performance testing.