Package cdc.converters

Class Converters

java.lang.Object
cdc.converters.Converters
public final class Converters extends Object
Registry of converters.
Author:
Damien Carbonne

  • Field Details

    • PRINTER

      public static final cdc.util.debug.Printable PRINTER

  • Method Details

    • elaborate

      public static void elaborate()

    • register

      public static void register(Converter<?,?> converter, String name, boolean isDefault, cdc.util.lang.FailureReaction reaction)
      Registers a converter.
      Parameters:
      converter - The converter.
      name - The converter name.
      isDefault - If true, this converter is a default one for target/source classes.
      reaction - The reaction to adopt in case of failure.
      Throws:
      IllegalArgumentException - when cconverter is null, or a converter with the same name is already registered, or a default converter is already registered.

    • register

      public static void register(Converter<?,?> converter, boolean isDefault, cdc.util.lang.FailureReaction reaction)
      Registers a converter using its class simple name as name.
      Parameters:
      converter - The converter.
      isDefault - If true, this converter is a default one for target/source classes.
      reaction - The reaction to adopt in case of failure.
      Throws:
      IllegalArgumentException - when cconverter is null, or a converter with the same name is already registered, or a default converter is already registered.

    • register

      public static void register(Converter<?,?> converter, boolean isDefault)

    • getNames

      public static Set<String> getNames()
      Returns:
      A set of all registered converters names.

    • hasConverter

      public static boolean hasConverter(String name)
      Returns true when a converter with a given name exists.
      Parameters:
      name - The converter name.
      Returns:
      true when a converter named name exists.

    • hasMatchingConverters

      public static boolean hasMatchingConverters(Class<?> sourceClass, Class<?> targetClass)
      Returns true when some converters matching source and target classes are registered.
      Parameters:
      sourceClass - The source class.
      targetClass - The target class.
      Returns:
      true when converters matching sourceClass and targetClass are registered.

    • hasCompliantConverters

      public static boolean hasCompliantConverters(Class<?> sourceClass, Class<?> targetClass)
      Returns true when some converters compliant with source and target classes are registered.
      Parameters:
      sourceClass - The source class.
      targetClass - The target class.
      Returns:
      true when converters compliant with sourceClass and targetClass are registered.

    • hasSpecialConverter

      public static boolean hasSpecialConverter(Class<?> sourceClass, Class<?> targetClass, SpecialConverterKind kind)
      Returns true when a special converter matches a pair of classes.

      WARNING: Only exact matching of classes is tested.

      Parameters:
      sourceClass - The source class.
      targetClass - The target class.
      kind - The special converter kind.
      Returns:
      true when a special converter from sourceClass to targetClass exists.

    • isSpecialConverter

      public static boolean isSpecialConverter(Converter<?,?> converter, SpecialConverterKind kind)
      Returns true when a converter is declared as a special one.
      Parameters:
      converter - The converter.
      kind - The special converter kind.
      Returns:
      true when converter is a special converter.

    • isSpecialConverterName

      public static boolean isSpecialConverterName(String name, SpecialConverterKind kind)
      Returns true if a name is the name of a default converter.
      Parameters:
      name - The name.
      kind - The special converter kind.
      Returns:
      true if name is the name of a default converter.

    • getConverter

      public static Converter<?,?> getConverter(String name, cdc.util.lang.FailureReaction reaction)
      Returns the converter that has a given name.
      Parameters:
      name - The name.
      reaction - The reaction to adopt when not converter is found.
      Returns:
      The converter named name or null.
      Throws:
      cdc.util.lang.NotFoundException - When reaction is FailureReaction.FAIL and no converter named name exists.

    • getConverter

      public static Converter<?,?> getConverter(String name)
      Returns the converter that has a given name.
      Parameters:
      name - The name.
      Returns:
      The converter named { @code name}.
      Throws:
      cdc.util.lang.NotFoundException - When no converter named name exists.

    • getMatchingConverter

      public static <S, T> Converter<S,T> getMatchingConverter(String name, Class<S> sourceClass, Class<T> targetClass, cdc.util.lang.FailureReaction reaction)
      Returns the converter that has a given name and matches source and target classes.
      Type Parameters:
      S - The source type.
      T - The target type.
      Parameters:
      name - The converter name.
      sourceClass - The source class.
      targetClass - The target class.
      reaction - The reaction to adopt when not converter is found.
      Returns:
      The matching converter or null.
      Throws:
      cdc.util.lang.NotFoundException - When reaction is FailureReaction.FAIL and no converter named name, matching sourceClass and targetClass exists.

    • getMatchingConverter

      public static <S, T> Converter<S,T> getMatchingConverter(String name, Class<S> sourceClass, Class<T> targetClass)
      Returns the converter that has a given name and matches source and target classes.
      Type Parameters:
      S - The source type.
      T - The target type.
      Parameters:
      name - The converter name.
      sourceClass - The source class.
      targetClass - The target class.
      Returns:
      The matching converter or null.
      Throws:
      cdc.util.lang.NotFoundException - When no converter named name, matching sourceClass and targetClass exists.

    • getCompliantConverter

      public static <S, T> Converter<? super S,? extends T> getCompliantConverter(String name, Class<S> sourceClass, Class<T> targetClass, cdc.util.lang.FailureReaction reaction)
      Returns the converter that has a given name and is compliant with source and target classes.
      Type Parameters:
      S - The source type.
      T - The target type.
      Parameters:
      name - The converter name.
      sourceClass - The source class.
      targetClass - The target class.
      reaction - The reaction to adopt when not converter is found.
      Returns:
      The compliant converter or null.
      Throws:
      cdc.util.lang.NotFoundException - When reaction is FailureReaction.FAIL and no converter named name, compliant with sourceClass and targetClass exists.

    • getCompliantConverter

      public static <S, T> Converter<? super S,? extends T> getCompliantConverter(String name, Class<S> sourceClass, Class<T> targetClass)
      Returns the converter that has a given name and is compliant with source and target classes.
      Type Parameters:
      S - The source type.
      T - The target type.
      Parameters:
      name - The converter name.
      sourceClass - The source class.
      targetClass - The target class.
      Returns:
      The compliant converter or null.
      Throws:
      cdc.util.lang.NotFoundException - When no converter named name, compliant with sourceClass and targetClass exists.

    • getSourceMatchingConverters

      public static <S> List<Converter<S,?>> getSourceMatchingConverters(Class<S> sourceClass)

    • getTargetMatchingConverters

      public static <T> List<Converter<?,T>> getTargetMatchingConverters(Class<T> targetClass)

    • getMatchingConverters

      public static <S, T> List<Converter<S,T>> getMatchingConverters(Class<S> sourceClass, Class<T> targetClass)
      Returns a list of all converters from a source class to a target class.
      Type Parameters:
      S - The source type.
      T - The target type.
      Parameters:
      sourceClass - The source class.
      targetClass - The target class.
      Returns:
      A list of all converters from sourceClass to targetClass.

    • getSourceCompliantConverters

      public static <S> Set<Converter<? super S,?>> getSourceCompliantConverters(Class<S> sourceClass, SpecialConverterKind kind)

    • getTargetCompliantConverters

      public static <T> Set<Converter<?,? extends T>> getTargetCompliantConverters(Class<T> targetClass, SpecialConverterKind kind)

    • getCompliantConverters

      public static <S, T> Set<Converter<? super S,? extends T>> getCompliantConverters(Class<S> sourceClass, Class<T> targetClass, SpecialConverterKind kind)

    • getMatchingSpecialConverter

      public static <S, T> Converter<S,T> getMatchingSpecialConverter(Class<S> sourceClass, Class<T> targetClass, SpecialConverterKind kind, cdc.util.lang.FailureReaction reaction)
      Returns the default converter associated to a pair of classes, if any.

      WARNING: Only exact matching of classes is tested.

      Type Parameters:
      S - The source type.
      T - The target type.
      Parameters:
      sourceClass - The source class.
      targetClass - The target class.
      kind - The special converter kind.
      reaction - The reaction to adopt when not converter is found.
      Returns:
      The default converter from sourceClass to targetClass or null.
      Throws:
      cdc.util.lang.NotFoundException - When reaction is FailureReaction.FAIL and no matching converter is found.

    • getMatchingSpecialConverter

      public static <S, T> Converter<S,T> getMatchingSpecialConverter(Class<S> sourceClass, Class<T> targetClass, SpecialConverterKind kind)

    • getCompliantSpecialConverter

      public static <S, T> Converter<? super S,? extends T> getCompliantSpecialConverter(Class<S> sourceClass, Class<T> targetClass, SpecialConverterKind kind, cdc.util.lang.FailureReaction reaction)
      Returns a compliant default converter for a pair of classes.

      WARNING: When there is a matching converter, it is returned.
      Otherwise, when several compliant converters exist, the returned one is selected using an non deterministic algorithm.

      Type Parameters:
      S - The source type.
      T - The target type.
      Parameters:
      sourceClass - The source class.
      targetClass - The target class.
      kind - The special converter kind.
      reaction - The reaction to adopt when not converter is found.
      Returns:
      A compliant default converter from sourceClass to targetClass or null.
      Throws:
      cdc.util.lang.NotFoundException - When reaction is FailureReaction.FAIL and no compliant converter is found.

    • getCompliantSpecialConverter

      public static <S, T> Converter<? super S,? extends T> getCompliantSpecialConverter(Class<S> sourceClass, Class<T> targetClass, SpecialConverterKind kind)

    • convertRaw

      public static Object convertRaw(String name, Object source)
      Converts a source object to a target object using a converter known by its name and parameters.
      Parameters:
      name - The converter name.
      source - The object to convert.
      Returns:
      The conversion of source using the converter named name with parameters params.
      Throws:
      ConversionException - when no converter is found.

    • convertRaw

      public static Object convertRaw(Object source, Class<?> sourceClass, Class<?> targetClass)
      Converts an object to a target class using an appropriate default converter.

      The default converter search is narrowed by source and target classes.

      null is converted to null.

      WARNING: it is the caller responsibility to use a valid sourceClass, compliant with source.

      Parameters:
      source - The source object.
      sourceClass - The source class, used to narrow search of compliant converters. It must be compliant with source.
      targetClass - The target class.
      Returns:
      The conversion of source to targetClass.
      Throws:
      ConversionException - when no matching default converter is found.

    • convertRaw

      public static Object convertRaw(Object source, Class<?> targetClass)
      Converts an object to a target class using an appropriate default converter.

      The default converter search is narrowed by class of source object and target class.

      null is converted to null.

      Parameters:
      source - The source object.
      targetClass - The target class.
      Returns:
      The conversion of source to targetClass.
      Throws:
      ConversionException - when no matching default converter is found.

    • convert

      public static <T> T convert(Object source, Class<?> sourceClass, Class<T> targetClass)
      Converts an object to a target class using an appropriate default converter narrowed from a source class

      WARNING: it is the caller responsibility to use a valid sourceClass, compliant with source.

      Type Parameters:
      T - The target type.
      Parameters:
      source - The source object.
      sourceClass - The source class, used to narrow search of compliant converters. It must be compliant with source.
      targetClass - The target class.
      Returns:
      The conversion of source to targetClass.
      Throws:
      ConversionException - when no matching default converter is found.

    • convert

      public static <T> T convert(Object source, Class<T> targetClass)
      Converts an object to a target class using an appropriate default converter.
      Type Parameters:
      T - The target type.
      Parameters:
      source - The source object.
      targetClass - The target class.
      Returns:
      The conversion of source to targetClass.
      Throws:
      ConversionException - when no matching default converter is found.

    • convert

      public static <T> void convert(Collection<?> input, Converter<?,? extends T> converter, Collection<T> output)
      Converts a collection using a converter.
      Type Parameters:
      T - The elements type.
      Parameters:
      input - The input collection.
      converter - The converter to use.
      output - The output collection.

    • toString

      public static String toString(Object object, cdc.util.lang.FailureReaction reaction)
      Converts an object to a string using default or single converters.

      If object is null, null is returned.
      toString() is used when no converter is found and reaction is not FAIL.

      Parameters:
      object - The object.
      reaction - The reaction to adopt when not converter is found.
      Returns:
      The conversion of object to string using a compliant default or single converter, or toString().
      Throws:
      cdc.util.lang.NotFoundException - When reaction is FailureReaction.FAIL and no compliant converter is found.

    • toString

      public static String toString(Object object)

    • flatten

      public static List<Converter<?,?>> flatten(Converter<?,?> converter)