Package de.gebit.integrity.parameter.conversion

## Class AbstractModularValueConverter

- java.lang.Object
- - de.gebit.integrity.parameter.conversion.AbstractModularValueConverter

- All Implemented Interfaces:
    `ValueConverter`
  Direct Known Subclasses:
    `DefaultModularValueConverter`

      public abstract class AbstractModularValueConverter
      extends Object
      implements ValueConverter

  Abstract base class for a value converter which uses conversion classes to determine how a given value is to be converted into a desired form. This modularity makes it easy to extend the converter with additional conversions.
  Author:
    Rene Schneider - initial API and implementation

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected static class` | `AbstractModularValueConverter.ConversionKey` | This class defines a key for efficient searching for conversions in maps.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected com.google.inject.Provider<ConversionContext>` | `conversionContextProvider` | The conversion context provider.
    `protected com.google.inject.Injector` | `injector` | The Guice injector.
    `protected ParameterResolver` | `parameterResolver` | The parameter resolver.
    `protected StandardOperationProcessor` | `standardOperationProcessor` | The processor for standard operations.
    `protected VariableManager` | `variableManager` | The variable manager.
    `protected WrapperFactory` | `wrapperFactory` | The wrapper factory.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AbstractModularValueConverter()` | Default constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `addConversion​(Class<? extends Conversion<?,​?>> aConversion)` | Adds the given conversion class to the map of available conversions.
    `protected Object` | `convertEncapsulatedConstantValueToTargetType​(Class<?> aTargetType, Class<?> aParameterizedType, ConstantValue aValue, ConversionContext aConversionContext, Set<Object> someVisitedValues)` | Converts a given `ValueOrEnumValueOrOperation` to a given Java type class, if possible.
    `protected Object` | `convertEncapsulatedValueCollectionToTargetType​(Class<?> aTargetType, Class<?> aParameterizedType, ValueOrEnumValueOrOperationCollection aCollection, ConversionContext aConversionContext, Set<Object> someVisitedValues)` | Converts a given value collection to a given Java type class, if possible.
    `protected Object` | `convertEncapsulatedValueToTargetType​(Class<?> aTargetType, Class<?> aParameterizedType, ValueOrEnumValueOrOperation aValue, ConversionContext aConversionContext, Set<Object> someVisitedValues)` | Converts a given `ValueOrEnumValueOrOperation` to a given Java type class, if possible.
    `protected Object` | `convertPlainValueToTargetType​(Class<?> aTargetType, Class<?> aParameterizedType, Object aValue, ConversionContext aConversionContext, Set<Object> someVisitedValues)` | Converts a given plain value (no instance of `ValueOrEnumValueOrOperation` or `ValueOrEnumValueOrOperationCollection`) to a given Java type class, if possible.
    `Object` | `convertValue​(Class<?> aTargetType, Class<?> aParameterizedType, Object aValue, ConversionContext aConversionContext)` | Convert a given single Integrity or Java type value to a given target type (which is always a Java type).
    `Object` | `convertValue​(Class<?> aTargetType, Class<?> aParameterizedType, Object aValue, ConversionContext aConversionContext, Set<Object> someVisitedObjects)` | Extended version of #convertValue(Class, Class, Object, UnresolvableVariableHandling).
    `Object` | `convertValue​(Class<?> aTargetType, Object aValue, ConversionContext aConversionContext)` | Convert a given single Integrity or Java type value to a given target type (which is always a Java type).
    `FormattedString` | `convertValueToFormattedString​(Object aValue, boolean aForceIntermediateMapFlag, ConversionContext aConversionContext)` | Converts a given value to a formattedString.
    `FormattedString[]` | `convertValueToFormattedStringArray​(Object aValue, ConversionContext aConversionContext)` | Converts a given value to a formatted String array.
    `String` | `convertValueToString​(Object aValue, boolean aForceIntermediateMapFlag, ConversionContext aConversionContext)` | Converts a given value to a String.
    `String[]` | `convertValueToStringArray​(Object aValue, ConversionContext aConversionContext)` | Converts a given value to a String array.
    `FormattedString[]` | `convertValueToStringArray​(Object aValue, ConversionContext aConversionContext, Set<Object> someVisitedValues)` | Extended version of `#convertValueToStringArray(Object, UnresolvableVariableHandling)`.
    `protected <C extends Conversion> C` | `createConversionInstance​(Class<C> aConversionClass, Set<Object> someVisitedValues)` | Creates an instance of the given conversion class.
    `protected int` | `determineConversionPriority​(Class<? extends Conversion<?,​?>> aConversion)` | Determines the priority of the given conversion class.
    `protected Class<? extends Conversion<?,​?>>` | `filterConversionClass​(Class<? extends Conversion<?,​?>> aConversionClass, Class<?> aSourceType, Class<?> aTargetType, ConversionContext aConversionContext, boolean aDefaultConversionFlag)` | This filtering method has the ability to replace a conversion class found by the normal lookup before it's actually used.
    `protected Conversion<?,​?>` | `findAndInstantiateConversion​(Class<?> aSourceType, Class<?> aTargetType, Set<Object> someVisitedValues, ConversionContext aConversionContext)` | Searches all known conversions for a match which is able to convert a given source type into a given target type.
    `protected Class<? extends Conversion<?,​?>>` | `findConversion​(Class<?> aSourceType, Class<?> aTargetType, Set<Object> someVisitedValues, ConversionContext aConversionContext)` | Searches all known conversions for a match which is able to convert a given source type into a given target type.
    `protected Class<? extends Conversion<?,​?>>` | `findConversionRecursive​(Class<?> aSourceType, Class<?> aTargetType, ConversionContext aConversionContext)` | Searches all known conversions for a match which is able to convert a given source type into a given target type.
    `protected Class<? extends Conversion<?,​?>>` | `findDerivedConversionRecursive​(Class<?> aSourceType, Class<?> aTargetType, ConversionContext aConversionContext)` | Searches all known derived conversions for a match which is able to convert a given source type into a subclass of a given target type.
    `protected byte[]` | `handleConversionOfStringToByteArray​(String aSource)` | Handles the special case of issue #66: single string to byte array.
    `protected Byte[]` | `handleConversionOfStringToByteWrapperArray​(String aSource)` | Handles the special case of issue #66: single string to byte array.
    `protected byte[]` | `handleConversionOfStringValueToByteArray​(StringValue aSource)` | Handles the special case of issue #66: single string to byte array.
    `protected Byte[]` | `handleConversionOfStringValueToByteWrapperArray​(StringValue aSource)` | Handles the special case of issue #66: single string to byte array.
    `protected abstract void` | `initializeConversions()` | Implement this method to initialize known conversions.
    `protected void` | `initializeSearchBlockers()` | Initializes the contents of `conversionSearchBlockers`.
    `ConversionContext` | `safeguardConversionContext​(ConversionContext aContext)` | This method creates a default conversion context in case none is provided, and returns the provided context otherwise.
    `protected Class<? extends Conversion<?,​?>>` | `searchDerivedConversionMap​(Class<?> aSourceType, Class<?> aTargetType)` | Searches the derived conversion map for a match.
    `protected <T extends Collection> T` | `wrapInCollection​(Class<T> aCollectionType, Object anArrayOrSingleType)` | Wraps a value (or an array of values) in a collection of the given type.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### parameterResolver

          @Inject
          protected ParameterResolver parameterResolver

      The parameter resolver.

    - #### variableManager

          @Inject(optional=true)
          protected VariableManager variableManager

      The variable manager.

    - #### wrapperFactory

          @Inject(optional=true)
          protected WrapperFactory wrapperFactory

      The wrapper factory.

    - #### standardOperationProcessor

          @Inject
          protected StandardOperationProcessor standardOperationProcessor

      The processor for standard operations.

    - #### injector

          @Inject
          protected com.google.inject.Injector injector

      The Guice injector. Required to inject stuff into instances of conversions.

    - #### conversionContextProvider

          @Inject
          protected com.google.inject.Provider<ConversionContext> conversionContextProvider

      The conversion context provider.

  - ### Constructor Detail

    - #### AbstractModularValueConverter

          public AbstractModularValueConverter()

      Default constructor. Initializes all conversions and search blockers.

  - ### Method Detail

    - #### initializeConversions

          protected abstract void initializeConversions()

      Implement this method to initialize known conversions.

    - #### initializeSearchBlockers

          protected void initializeSearchBlockers()

      Initializes the contents of `conversionSearchBlockers`.

    - #### convertValue

          public Object convertValue​(Class<?> aTargetType,
                                     Object aValue,
                                     ConversionContext aConversionContext)
                              throws ParameterUtil.UnresolvableVariableException,
                                     UnexecutableException

      Description copied from interface: `ValueConverter`
      Convert a given single Integrity or Java type value to a given target type (which is always a Java type).
      Specified by:
        `convertValue` in interface `ValueConverter`
      Parameters:
        `aTargetType` - the target type
        `aValue` - the value
        `aConversionContext` - controls some conversion parameters and rules; may be null if the default `ConversionContext` values shall be used
      Returns:
        the converted object
      Throws:
        `ParameterUtil.UnresolvableVariableException`
        `UnexecutableException`

    - #### convertValue

          public Object convertValue​(Class<?> aTargetType,
                                     Class<?> aParameterizedType,
                                     Object aValue,
                                     ConversionContext aConversionContext)
                              throws ParameterUtil.UnresolvableVariableException,
                                     UnexecutableException

      Description copied from interface: `ValueConverter`
      Convert a given single Integrity or Java type value to a given target type (which is always a Java type).
      Specified by:
        `convertValue` in interface `ValueConverter`
      Parameters:
        `aTargetType` - the target type
        `aParameterizedType` - the parameterized (via generics) type attached to the given target type, if applicable - for example if a conversion to List is desired, the target type is List, and the parameterized type is Integer
        `aValue` - the value
        `aConversionContext` - controls some conversion parameters and rules; may be null if the default `ConversionContext` values shall be used
      Returns:
        the converted object
      Throws:
        `ParameterUtil.UnresolvableVariableException`
        `UnexecutableException`

    - #### convertValue

          public Object convertValue​(Class<?> aTargetType,
                                     Class<?> aParameterizedType,
                                     Object aValue,
                                     ConversionContext aConversionContext,
                                     Set<Object> someVisitedObjects)
                              throws ParameterUtil.UnresolvableVariableException,
                                     UnexecutableException

      Extended version of #convertValue(Class, Class, Object, UnresolvableVariableHandling).
      Parameters:
        `aTargetType` -
        `aParameterizedType` -
        `aValue` -
        `aConversionContext` -
        `someVisitedObjects` -
      Returns:
      Throws:
        `ParameterUtil.UnresolvableVariableException`
        `ClassNotFoundException`
        `UnexecutableException`
        `InstantiationException`

    - #### convertPlainValueToTargetType

          protected Object convertPlainValueToTargetType​(Class<?> aTargetType,
                                                         Class<?> aParameterizedType,
                                                         Object aValue,
                                                         ConversionContext aConversionContext,
                                                         Set<Object> someVisitedValues)

      Converts a given plain value (no instance of `ValueOrEnumValueOrOperation` or `ValueOrEnumValueOrOperationCollection`) to a given Java type class, if possible.
      Parameters:
        `aTargetType` - the target type
        `aParameterizedType` - the parameterized (via generics) type attached to the given target type, if applicable - for example if a conversion to List is desired, the target type is List, and the parameterized type is Integer
        `aValue` - the value
        `aConversionContext` - defines some parameters controlling how the conversion is done in detail
      Returns:
        the converted value

    - #### convertEncapsulatedValueToTargetType

          protected Object convertEncapsulatedValueToTargetType​(Class<?> aTargetType,
                                                                Class<?> aParameterizedType,
                                                                ValueOrEnumValueOrOperation aValue,
                                                                ConversionContext aConversionContext,
                                                                Set<Object> someVisitedValues)
                                                         throws ParameterUtil.UnresolvableVariableException,
                                                                UnexecutableException

      Converts a given `ValueOrEnumValueOrOperation` to a given Java type class, if possible.
      Parameters:
        `aTargetType` - the target type
        `aParameterizedType` - the parameterized (via generics) type attached to the given target type, if applicable - for example if a conversion to List is desired, the target type is List, and the parameterized type is Integer
        `aValue` - the value
        `aConversionContext` - defines some parameters controlling how the conversion is done in detail
      Returns:
        the converted value
      Throws:
        `ParameterUtil.UnresolvableVariableException`
        `ClassNotFoundException`
        `InstantiationException`
        `UnexecutableException`

    - #### convertEncapsulatedConstantValueToTargetType

          protected Object convertEncapsulatedConstantValueToTargetType​(Class<?> aTargetType,
                                                                        Class<?> aParameterizedType,
                                                                        ConstantValue aValue,
                                                                        ConversionContext aConversionContext,
                                                                        Set<Object> someVisitedValues)
                                                                 throws ParameterUtil.UnresolvableVariableException,
                                                                        UnexecutableException

      Converts a given `ValueOrEnumValueOrOperation` to a given Java type class, if possible.
      Parameters:
        `aTargetType` - the target type
        `aParameterizedType` - the parameterized (via generics) type attached to the given target type, if applicable - for example if a conversion to List is desired, the target type is List, and the parameterized type is Integer
        `aValue` - the value
        `aConversionContext` - defines some parameters controlling how the conversion is done in detail
      Returns:
        the converted value
      Throws:
        `ParameterUtil.UnresolvableVariableException`
        `ClassNotFoundException`
        `InstantiationException`
        `UnexecutableException`

    - #### convertEncapsulatedValueCollectionToTargetType

          protected Object convertEncapsulatedValueCollectionToTargetType​(Class<?> aTargetType,
                                                                          Class<?> aParameterizedType,
                                                                          ValueOrEnumValueOrOperationCollection aCollection,
                                                                          ConversionContext aConversionContext,
                                                                          Set<Object> someVisitedValues)
                                                                   throws ParameterUtil.UnresolvableVariableException,
                                                                          UnexecutableException

      Converts a given value collection to a given Java type class, if possible. Will return an array if the collection contains more than one item.
      Parameters:
        `aTargetType` - the target type
        `aParameterizedType` - the parameterized (via generics) type attached to the given target type, if applicable - for example if a conversion to List is desired, the target type is List, and the parameterized type is Integer
        `aCollection` - the value collection
        `aConversionContext` - defines some parameters controlling how the conversion is done in detail
      Returns:
        the converted value
      Throws:
        `ParameterUtil.UnresolvableVariableException`
        `ClassNotFoundException`
        `UnexecutableException`
        `InstantiationException`

    - #### wrapInCollection

          protected <T extends Collection> T wrapInCollection​(Class<T> aCollectionType,
                                                              Object anArrayOrSingleType)

      Wraps a value (or an array of values) in a collection of the given type.
      Parameters:
        `aCollectionType` - the collection type
        `anArrayOrSingleType` - the array or value to wrap
      Returns:
        the collection

    - #### convertValueToString

          public String convertValueToString​(Object aValue,
                                             boolean aForceIntermediateMapFlag,
                                             ConversionContext aConversionContext)

      Description copied from interface: `ValueConverter`
      Converts a given value to a String. This method is intended to be used for the output of values (for example in test results, on the console etc). In comparison to `#convertValueToStringArray(Object, UnresolvableVariableHandling)`, this method always returns only a single String value, concatenating arrays first if necessary.
      Specified by:
        `convertValueToString` in interface `ValueConverter`
      Parameters:
        `aValue` - the value (can be an Integrity-internal type or a plain Java Object)
        `aForceIntermediateMapFlag` - whether the conversion should force the usage of an intermediate map (useful for bean types)
        `aConversionContext` - controls some conversion parameters and rules; may be null if the default `ConversionContext` values shall be used
      Returns:
        the string

    - #### convertValueToFormattedString

          public FormattedString convertValueToFormattedString​(Object aValue,
                                                               boolean aForceIntermediateMapFlag,
                                                               ConversionContext aConversionContext)

      Description copied from interface: `ValueConverter`
      Converts a given value to a formattedString. This method is intended to be used for the output of values (for example in test results, on the console etc). In comparison to `#convertValueToStringArray(Object, UnresolvableVariableHandling)`, this method always returns only a single String value, concatenating arrays first if necessary.
      Specified by:
        `convertValueToFormattedString` in interface `ValueConverter`
      Parameters:
        `aValue` - the value (can be an Integrity-internal type or a plain Java Object)
        `aForceIntermediateMapFlag` - whether the conversion should force the usage of an intermediate map (useful for bean types)
        `aConversionContext` - controls some conversion parameters and rules; may be null if the default `ConversionContext` values shall be used
      Returns:
        the string

    - #### convertValueToStringArray

          public String[] convertValueToStringArray​(Object aValue,
                                                    ConversionContext aConversionContext)

      Description copied from interface: `ValueConverter`
      Converts a given value to a String array. This method is intended to be used for the output of values (for example in test results, on the console etc).
      Specified by:
        `convertValueToStringArray` in interface `ValueConverter`
      Parameters:
        `aValue` - the value (can be an Integrity-internal type or a plain Java Object)
        `aConversionContext` - controls some conversion parameters and rules; may be null if the default `ConversionContext` values shall be used
      Returns:
        the string array

    - #### convertValueToFormattedStringArray

          public FormattedString[] convertValueToFormattedStringArray​(Object aValue,
                                                                      ConversionContext aConversionContext)

      Description copied from interface: `ValueConverter`
      Converts a given value to a formatted String array. This method is intended to be used for the output of values (for example in test results, on the console etc).
      Specified by:
        `convertValueToFormattedStringArray` in interface `ValueConverter`
      Parameters:
        `aValue` - the value (can be an Integrity-internal type or a plain Java Object)
        `aConversionContext` - controls some conversion parameters and rules; may be null if the default `ConversionContext` values shall be used
      Returns:
        the string array

    - #### convertValueToStringArray

          public FormattedString[] convertValueToStringArray​(Object aValue,
                                                             ConversionContext aConversionContext,
                                                             Set<Object> someVisitedValues)

      Extended version of `#convertValueToStringArray(Object, UnresolvableVariableHandling)`.
      Parameters:
        `aValue` -
        `aConversionContext` -
        `someVisitedValues` -
      Returns:

    - #### addConversion

          protected void addConversion​(Class<? extends Conversion<?,​?>> aConversion)

      Adds the given conversion class to the map of available conversions.
      Parameters:
        `aConversion` - the conversion to add

    - #### determineConversionPriority

          protected int determineConversionPriority​(Class<? extends Conversion<?,​?>> aConversion)

      Determines the priority of the given conversion class.
      Parameters:
        `aConversion` - the conversion to introspect
      Returns:
        the numeric priority

    - #### findAndInstantiateConversion

          protected Conversion<?,​?> findAndInstantiateConversion​(Class<?> aSourceType,
                                                                       Class<?> aTargetType,
                                                                       Set<Object> someVisitedValues,
                                                                       ConversionContext aConversionContext)
                                                                throws InstantiationException,
                                                                       IllegalAccessException

      Searches all known conversions for a match which is able to convert a given source type into a given target type. This instantiates a found conversion class.
      Parameters:
        `aSourceType` - the source type
        `aTargetType` - the target type
        `someVisitedValues` -
        `aConversionContext` - The conversion context
      Returns:
        a ready-to-use, instantiated conversion, or null if none was found
      Throws:
        `InstantiationException`
        `IllegalAccessException`

    - #### findConversion

          protected Class<? extends Conversion<?,​?>> findConversion​(Class<?> aSourceType,
                                                                          Class<?> aTargetType,
                                                                          Set<Object> someVisitedValues,
                                                                          ConversionContext aConversionContext)

      Searches all known conversions for a match which is able to convert a given source type into a given target type. Returns the conversion class (must be instantiated before actually converting something).
      Parameters:
        `aSourceType` - the source type
        `aTargetType` - the target type
        `aConversionContext` - The conversion context
      Returns:
        a conversion class, or null if none was found

    - #### findDerivedConversionRecursive

          protected Class<? extends Conversion<?,​?>> findDerivedConversionRecursive​(Class<?> aSourceType,
                                                                                          Class<?> aTargetType,
                                                                                          ConversionContext aConversionContext)

      Searches all known derived conversions for a match which is able to convert a given source type into a subclass of a given target type. If there are multiple matches (which is likely, if the target type is very generic), the conversion with the highest priority wins.
      Parameters:
        `aSourceType` - the source type
        `aTargetType` - the target type
      Returns:
        a conversion class, or null if none was found

    - #### searchDerivedConversionMap

          protected Class<? extends Conversion<?,​?>> searchDerivedConversionMap​(Class<?> aSourceType,
                                                                                      Class<?> aTargetType)

      Searches the derived conversion map for a match. If one or multiple are found, the one with the highest priority is returned (the lists in the map are pre-sorted that way).
      Parameters:
        `aSourceType` - the source type
        `aTargetType` - the target type
      Returns:
        a conversion class, or null if none was found

    - #### findConversionRecursive

          protected Class<? extends Conversion<?,​?>> findConversionRecursive​(Class<?> aSourceType,
                                                                                   Class<?> aTargetType,
                                                                                   ConversionContext aConversionContext)

      Searches all known conversions for a match which is able to convert a given source type into a given target type. Returns the conversion class (must be instantiated before actually converting something).
      Parameters:
        `aSourceType` - the source type
        `aTargetType` - the target type
        `aConversionContext` - The conversion context
      Returns:
        a conversion class, or null if none was found

    - #### filterConversionClass

          protected Class<? extends Conversion<?,​?>> filterConversionClass​(Class<? extends Conversion<?,​?>> aConversionClass,
                                                                                 Class<?> aSourceType,
                                                                                 Class<?> aTargetType,
                                                                                 ConversionContext aConversionContext,
                                                                                 boolean aDefaultConversionFlag)

      This filtering method has the ability to replace a conversion class found by the normal lookup before it's actually used. This is the point at which special rules (for example dictated by the `ConversionContext`) may be enforced.
      Parameters:
        `aConversionClass` - the conversion class in question
        `aSourceType` - the source type
        `aTargetType` - the target type
        `aConversionContext` - the conversion context to use
        `aDefaultConversionFlag` - whether this is a default conversion or specifically requested to match the target type
      Returns:
        the conversion class to use, which may be the input class or any other replacement

    - #### createConversionInstance

          protected <C extends Conversion> C createConversionInstance​(Class<C> aConversionClass,
                                                                      Set<Object> someVisitedValues)
                                                               throws InstantiationException,
                                                                      IllegalAccessException

      Creates an instance of the given conversion class. This also injects the Guice dependencies.
      Parameters:
        `aConversionClass` - the conversion
      Returns:
        the new instance
      Throws:
        `InstantiationException`
        `IllegalAccessException`

    - #### safeguardConversionContext

          public ConversionContext safeguardConversionContext​(ConversionContext aContext)

      This method creates a default conversion context in case none is provided, and returns the provided context otherwise.
      Parameters:
        `aContext` - the context to safeguard
      Returns:
        a context (guaranteed not to return null)

    - #### handleConversionOfStringToByteArray

          protected byte[] handleConversionOfStringToByteArray​(String aSource)

      Handles the special case of issue #66: single string to byte array.
      Parameters:
        `aSource` - the string to convert
      Returns:
        the byte array

    - #### handleConversionOfStringToByteWrapperArray

          protected Byte[] handleConversionOfStringToByteWrapperArray​(String aSource)

      Handles the special case of issue #66: single string to byte array.
      Parameters:
        `aSource` - the string to convert
      Returns:
        the byte array (using the wrapper type)

    - #### handleConversionOfStringValueToByteArray

          protected byte[] handleConversionOfStringValueToByteArray​(StringValue aSource)

      Handles the special case of issue #66: single string to byte array.
      Parameters:
        `aSource` - the string to convert (wrapper type)
      Returns:
        the byte array

    - #### handleConversionOfStringValueToByteWrapperArray

          protected Byte[] handleConversionOfStringValueToByteWrapperArray​(StringValue aSource)

      Handles the special case of issue #66: single string to byte array.
      Parameters:
        `aSource` - the string to convert (wrapper type)
      Returns:
        the byte array (using the wrapper type)