Package org.joda.convert

Class StringConvert

  • public final class StringConvert
extends java.lang.Object
    Manager for conversion to and from a String, acting as the main client interface.

    Support is provided for conversions based on the StringConverter interface or the ToString and FromString annotations.

    StringConvert is thread-safe with concurrent caches.

    • Field Detail

      • LOG

        static final boolean LOG
        Errors in class initialization are hard to debug. Set -Dorg.joda.convert.debug=true on the command line to add extra logging to System.err

      • CACHED_NULL

        private static final TypedStringConverter<?> CACHED_NULL
        The cached null object. Ensure this is above public constants.

      • factories

        private final java.util.concurrent.CopyOnWriteArrayList<StringConverterFactory> factories
        The list of factories.

      • registered

        private final java.util.concurrent.ConcurrentMap<java.lang.Class<?>,​TypedStringConverter<?>> registered
        The cache of converters.

      • fromStrings

        private final java.util.concurrent.ConcurrentMap<java.lang.Class<?>,​FromStringConverter<?>> fromStrings
        The cache of from-strings.

    • Constructor Detail

      • StringConvert

        public StringConvert()
        Creates a new conversion manager including the JDK converters.

        The convert instance is mutable in a thread-safe manner. Converters may be altered at any time, including the JDK converters. It is strongly recommended to only alter the converters before performing actual conversions.

      • StringConvert

        public StringConvert​(boolean includeJdkConverters,
                     StringConverterFactory... factories)
        Creates a new conversion manager.

        The convert instance is mutable in a thread-safe manner. Converters may be altered at any time, including the JDK converters. It is strongly recommended to only alter the converters before performing actual conversions.

        If specified, the factories will be queried in the order specified.

        Parameters:
        includeJdkConverters - true to include the JDK converters
        factories - optional array of factories to use, not null

    • Method Detail

      • tryRegisterGuava

        private void tryRegisterGuava()
        Tries to register the Guava converters class.

      • tryRegisterJava8Optionals

        private void tryRegisterJava8Optionals()
        Tries to register the Java 8 optional classes.

      • tryRegisterTimeZone

        private void tryRegisterTimeZone()
        Tries to register the subclasses of TimeZone. Try various things, doesn't matter if the map entry gets overwritten.

      • tryRegisterJava8

        private void tryRegisterJava8()
        Tries to register Java 8 classes.

      • tryRegisterThreeTenBackport

        private void tryRegisterThreeTenBackport()
        Tries to register ThreeTen backport classes.

      • tryRegisterThreeTenOld

        private void tryRegisterThreeTenOld()
        Tries to register ThreeTen ThreeTen/JSR-310 classes v0.6.3 and beyond.

      • tryRegister

        private void tryRegister​(java.lang.String className,
                         java.lang.String fromStringMethodName)
                  throws java.lang.ClassNotFoundException
        Tries to register a class using the standard toString/parse pattern.
        Parameters:
        className - the class name, not null
        Throws:
        java.lang.ClassNotFoundException - if the class does not exist

      • convertToString

        public java.lang.String convertToString​(java.lang.Object object)
        Converts the specified object to a String.

        This uses findConverter(java.lang.Class<T>) to provide the converter.

        Parameters:
        object - the object to convert, null returns null
        Returns:
        the converted string, may be null
        Throws:
        java.lang.RuntimeException - (or subclass) if unable to convert

      • convertToString

        public java.lang.String convertToString​(java.lang.Class<?> cls,
                                        java.lang.Object object)
        Converts the specified object to a String.

        This uses findConverter(java.lang.Class<T>) to provide the converter. The class can be provided to select a more specific converter.

        Parameters:
        cls - the class to convert from, not null
        object - the object to convert, null returns null
        Returns:
        the converted string, may be null
        Throws:
        java.lang.RuntimeException - (or subclass) if unable to convert

      • convertFromString

        public <T> T convertFromString​(java.lang.Class<T> cls,
                               java.lang.String str)
        Converts the specified object from a String.

        This uses findFromStringConverter(java.lang.Class<T>) to provide the converter.

        Type Parameters:
        T - the type to convert to
        Parameters:
        cls - the class to convert to, not null
        str - the string to convert, null returns null
        Returns:
        the converted object, may be null
        Throws:
        java.lang.RuntimeException - (or subclass) if unable to convert

      • isConvertible

        public boolean isConvertible​(java.lang.Class<?> cls)
        Checks if a suitable converter exists for the type.

        This performs the same checks as the findConverter methods. Calling this before findConverter will cache the converter.

        Note that all exceptions, including developer errors are caught and hidden.

        Parameters:
        cls - the class to find a converter for, null returns false
        Returns:
        true if convertible
        Since:
        1.5

      • findConverter

        public <T> StringConverter<T> findConverter​(java.lang.Class<T> cls)
        Finds a suitable converter for the type.

        This returns an instance of StringConverter for the specified class. This is designed for user code where the Class object generics is known.

        The search algorithm first searches the registered converters. It then searches for ToString and FromString annotations on the specified class, class hierarchy or immediate parent interfaces. Finally, it handles Enum instances.

        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to find a converter for, not null
        Returns:
        the converter, not null
        Throws:
        java.lang.RuntimeException - (or subclass) if no converter found

      • findConverterNoGenerics

        public StringConverter<java.lang.Object> findConverterNoGenerics​(java.lang.Class<?> cls)
        Finds a suitable converter for the type with open generics.

        This returns an instance of StringConverter for the specified class. This is designed for framework usage where the Class object generics are unknown'?'. The returned type is declared with Object instead of '?' to allow the ToStringConverter to be invoked.

        The search algorithm first searches the registered converters. It then searches for ToString and FromString annotations on the specified class, class hierarchy or immediate parent interfaces. Finally, it handles Enum instances.

        Parameters:
        cls - the class to find a converter for, not null
        Returns:
        the converter, using Object to avoid generics, not null
        Throws:
        java.lang.RuntimeException - (or subclass) if no converter found
        Since:
        1.5

      • findTypedConverter

        public <T> TypedStringConverter<T> findTypedConverter​(java.lang.Class<T> cls)
        Finds a suitable converter for the type.

        This returns an instance of TypedStringConverter for the specified class. This is designed for user code where the Class object generics is known.

        The search algorithm first searches the registered converters. It then searches for ToString and FromString annotations on the specified class, class hierarchy or immediate parent interfaces. Finally, it handles Enum instances.

        The returned converter may be queried for the effective type of the conversion. This can be used to find the best type to send in a serialized form.

        NOTE: Changing the method return type of findConverter(Class) would be source compatible but not binary compatible. As this is a low-level library, binary compatibility is important, hence the addition of this method.

        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to find a converter for, not null
        Returns:
        the converter, not null
        Throws:
        java.lang.RuntimeException - (or subclass) if no converter found
        Since:
        1.7

      • findTypedConverterNoGenerics

        public TypedStringConverter<java.lang.Object> findTypedConverterNoGenerics​(java.lang.Class<?> cls)
        Finds a suitable converter for the type with open generics.

        This returns an instance of TypedStringConverter for the specified class. This is designed for framework usage where the Class object generics are unknown'?'. The returned type is declared with Object instead of '?' to allow the ToStringConverter to be invoked.

        The search algorithm first searches the registered converters. It then searches for ToString and FromString annotations on the specified class, class hierarchy or immediate parent interfaces. Finally, it handles Enum instances.

        The returned converter may be queried for the effective type of the conversion. This can be used to find the best type to send in a serialized form.

        NOTE: Changing the method return type of findConverterNoGenerics(Class) would be source compatible but not binary compatible. As this is a low-level library, binary compatibility is important, hence the addition of this method.

        Parameters:
        cls - the class to find a converter for, not null
        Returns:
        the converter, using Object to avoid generics, not null
        Throws:
        java.lang.RuntimeException - (or subclass) if no converter found
        Since:
        1.7

      • findFromStringConverter

        public <T> FromStringConverter<T> findFromStringConverter​(java.lang.Class<T> cls)
        Finds a suitable from-string converter for the type.

        This returns an instance of FromStringConverter for the specified class. In most cases this is identical to findConverter(Class). However, it is permitted to have a FromString annotation without a ToString annotation, and this method catches that use case.

        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to find a converter for, not null
        Returns:
        the converter, not null
        Throws:
        java.lang.RuntimeException - (or subclass) if no converter found

      • findConverterQuiet

        private <T> TypedStringConverter<T> findConverterQuiet​(java.lang.Class<T> cls)

      • lookupConverter

        private <T> TypedStringConverter<T> lookupConverter​(java.lang.Class<T> cls)
        Lookup a converter searching registered and annotated.
        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to find a method for, not null
        Returns:
        the converter, not null
        Throws:
        java.lang.RuntimeException - if invalid

      • registerFactory

        public void registerFactory​(StringConverterFactory factory)
        Registers a converter factory.

        This will be registered ahead of all existing factories.

        No new factories may be registered for the global singleton.

        Parameters:
        factory - the converter factory, not null
        Throws:
        java.lang.IllegalStateException - if trying to alter the global singleton
        Since:
        1.5

      • register

        public <T> void register​(java.lang.Class<T> cls,
                         StringConverter<T> converter)
        Registers a converter for a specific type.

        The converter will be used for subclasses unless overidden.

        No new converters may be registered for the global singleton.

        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to register a converter for, not null
        converter - the String converter, not null
        Throws:
        java.lang.IllegalArgumentException - if the class or converter are null
        java.lang.IllegalStateException - if trying to alter the global singleton

      • register

        public <T> void register​(java.lang.Class<T> cls,
                         ToStringConverter<T> toString,
                         FromStringConverter<T> fromString)
        Registers a converter for a specific type using two separate converters.

        This method registers a converter for the specified class. It is primarily intended for use with JDK 1.8 method references or lambdas: 

          sc.register(Distance.class, Distance::toString, Distance::parse);
        The converter will be used for subclasses unless overidden.

        No new converters may be registered for the global singleton.

        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to register a converter for, not null
        toString - the to String converter, typically a method reference, not null
        fromString - the from String converter, typically a method reference, not null
        Throws:
        java.lang.IllegalArgumentException - if the class or converter are null
        java.lang.IllegalStateException - if trying to alter the global singleton
        Since:
        1.3

      • registerMethods

        public <T> void registerMethods​(java.lang.Class<T> cls,
                                java.lang.String toStringMethodName,
                                java.lang.String fromStringMethodName)
        Registers a converter for a specific type by method names.

        This method allows the converter to be used when the target class cannot have annotations added. The two method names must obey the same rules as defined by the annotations ToString and FromString. The converter will be used for subclasses unless overidden.

        No new converters may be registered for the global singleton.

        For example, convert.registerMethods(Distance.class, "toString", "parse");

        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to register a converter for, not null
        toStringMethodName - the name of the method converting to a string, not null
        fromStringMethodName - the name of the method converting from a string, not null
        Throws:
        java.lang.IllegalArgumentException - if the class or method name are null or invalid
        java.lang.IllegalStateException - if trying to alter the global singleton

      • registerMethodConstructor

        public <T> void registerMethodConstructor​(java.lang.Class<T> cls,
                                          java.lang.String toStringMethodName)
        Registers a converter for a specific type by method and constructor.

        This method allows the converter to be used when the target class cannot have annotations added. The two method name and constructor must obey the same rules as defined by the annotations ToString and FromString. The converter will be used for subclasses unless overidden.

        No new converters may be registered for the global singleton.

        For example, convert.registerMethodConstructor(Distance.class, "toString");

        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to register a converter for, not null
        toStringMethodName - the name of the method converting to a string, not null
        Throws:
        java.lang.IllegalArgumentException - if the class or method name are null or invalid
        java.lang.IllegalStateException - if trying to alter the global singleton

      • findToStringMethod

        private java.lang.reflect.Method findToStringMethod​(java.lang.Class<?> cls,
                                                    java.lang.String methodName)
        Finds the conversion method.
        Parameters:
        cls - the class to find a method for, not null
        methodName - the name of the method to find, not null
        Returns:
        the method to call, null means use toString

      • findFromStringMethod

        private java.lang.reflect.Method findFromStringMethod​(java.lang.Class<?> cls,
                                                      java.lang.String methodName)
        Finds the conversion method.
        Parameters:
        cls - the class to find a method for, not null
        methodName - the name of the method to find, not null
        Returns:
        the method to call, null means use toString

      • findFromStringConstructorByType

        private <T> java.lang.reflect.Constructor<T> findFromStringConstructorByType​(java.lang.Class<T> cls)
        Finds the conversion method.
        Type Parameters:
        T - the type of the converter
        Parameters:
        cls - the class to find a method for, not null
        Returns:
        the method to call, null means use toString

      • loadType

        static java.lang.Class<?> loadType​(java.lang.String fullName)
                            throws java.lang.ClassNotFoundException
        Throws:
        java.lang.ClassNotFoundException

      • loadPrimitiveType

        private static java.lang.Class<?> loadPrimitiveType​(java.lang.String fullName,
                                                    java.lang.ClassNotFoundException ex)
                                             throws java.lang.ClassNotFoundException
        Throws:
        java.lang.ClassNotFoundException

      • toString

        public java.lang.String toString()
        Returns a simple string representation of the object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the string representation, never null