Package cdc.converters

Class Converters

  • public final class Converters
extends Object
    Registry of converters.
    Author:
    Damien Carbonne

    • Field Detail

      • PRINTER

        public static final cdc.util.debug.Printable PRINTER

    • Method Detail

      • elaborate

        public static boolean 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 [@code 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.

      • 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.

      • 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<?> targetClass)
        Converts an object to a target class using an appropriate default converter.

        null is converted to null.

        Parameters:
        source - The source object.
        targetClass - The target class.
        Returns:
        The conversion of source to [@code 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 [@code 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)