Class StringConvert
- java.lang.Object
-
- org.joda.convert.StringConvert
-
public final class StringConvert extends java.lang.Object
Manager for conversion to and from aString
, acting as the main client interface.Support is provided for conversions based on the
StringConverter
interface or theToString
andFromString
annotations.StringConvert is thread-safe with concurrent caches.
-
-
Field Summary
Fields Modifier and Type Field Description private static TypedStringConverter<?>
CACHED_NULL
The cached null object.private java.util.concurrent.CopyOnWriteArrayList<StringConverterFactory>
factories
The list of factories.static StringConvert
INSTANCE
An immutable global instance.private java.util.concurrent.ConcurrentMap<java.lang.Class<?>,TypedStringConverter<?>>
registered
The cache of converters.
-
Constructor Summary
Constructors Constructor Description StringConvert()
Creates a new conversion manager including the JDK converters.StringConvert(boolean includeJdkConverters, StringConverterFactory... factories)
Creates a new conversion manager.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description <T> T
convertFromString(java.lang.Class<T> cls, java.lang.String str)
Converts the specified object from aString
.java.lang.String
convertToString(java.lang.Class<?> cls, java.lang.Object object)
Converts the specified object to aString
.java.lang.String
convertToString(java.lang.Object object)
Converts the specified object to aString
.static StringConvert
create()
Creates a new conversion manager including the extended standard set of converters.private <T> TypedStringConverter<T>
findAnyConverter(java.lang.Class<T> cls)
Finds a converter searching registered and annotated.<T> StringConverter<T>
findConverter(java.lang.Class<T> cls)
Finds a suitable converter for the type.StringConverter<java.lang.Object>
findConverterNoGenerics(java.lang.Class<?> cls)
Finds a suitable converter for the type with open generics.private <T> TypedStringConverter<T>
findConverterQuiet(java.lang.Class<T> cls)
Finds a converter searching registered and annotated.private <T> java.lang.reflect.Constructor<T>
findFromStringConstructorByType(java.lang.Class<T> cls)
Finds the conversion method.private java.lang.reflect.Method
findFromStringMethod(java.lang.Class<?> cls, java.lang.String methodName)
Finds the conversion method.private java.lang.reflect.Method
findToStringMethod(java.lang.Class<?> cls, java.lang.String methodName)
Finds the conversion method.<T> TypedStringConverter<T>
findTypedConverter(java.lang.Class<T> cls)
Finds a suitable converter for the type.TypedStringConverter<java.lang.Object>
findTypedConverterNoGenerics(java.lang.Class<?> cls)
Finds a suitable converter for the type with open generics.boolean
isConvertible(java.lang.Class<?> cls)
Checks if a suitable converter exists for the type.<T> void
register(java.lang.Class<T> cls, StringConverter<T> converter)
Registers a converter for a specific type.<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.void
registerFactory(StringConverterFactory factory)
Registers a converter factory.<T> void
registerMethodConstructor(java.lang.Class<T> cls, java.lang.String toStringMethodName)
Registers a converter for a specific type by method and constructor.<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.java.lang.String
toString()
Returns a simple string representation of the object.private void
tryRegister(java.lang.String className, java.lang.String fromStringMethodName)
Tries to register a class using the standard toString/parse pattern.private void
tryRegisterGuava()
Tries to register the Guava converters class.private void
tryRegisterJava8Optionals()
Tries to register the Java 8 optional classes.private void
tryRegisterTimeZone()
Tries to register the subclasses of TimeZone.
-
-
-
Field Detail
-
INSTANCE
public static final StringConvert INSTANCE
An immutable global instance.This instance cannot be added to using
register(java.lang.Class<T>, org.joda.convert.StringConverter<T>)
, however annotated classes are picked up. To register your own converters, simply create an instance of this class.
-
CACHED_NULL
private static final TypedStringConverter<?> CACHED_NULL
The cached null object.
-
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.
-
-
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 convertersfactories
- optional array of factories to use, not null
-
-
Method Detail
-
create
public static StringConvert create()
Creates a new conversion manager including the extended standard set of converters.The returned converter is a new instance that includes additional converters:
- JDK converters
NumericArrayStringConverterFactory
NumericObjectArrayStringConverterFactory
CharObjectArrayStringConverterFactory
ByteObjectArrayStringConverterFactory
BooleanArrayStringConverterFactory
BooleanObjectArrayStringConverterFactory
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.
- Returns:
- the new converter, not null
- Since:
- 1.5
-
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.
-
tryRegister
private void tryRegister(java.lang.String className, java.lang.String fromStringMethodName)
Tries to register a class using the standard toString/parse pattern.- Parameters:
className
- the class name, not null
-
convertToString
public java.lang.String convertToString(java.lang.Object object)
Converts the specified object to aString
.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 aString
.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 nullobject
- 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 aString
.This uses
findConverter(java.lang.Class<T>)
to provide the converter.- Type Parameters:
T
- the type to convert to- Parameters:
cls
- the class to convert to, not nullstr
- 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 beforefindConverter
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 theClass
object generics is known.The search algorithm first searches the registered converters. It then searches for
ToString
andFromString
annotations on the specified class, class hierarchy or immediate parent interfaces. Finally, it handlesEnum
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 theClass
object generics are unknown'?'. The returned type is declared withObject
instead of '?' to allow theToStringConverter
to be invoked.The search algorithm first searches the registered converters. It then searches for
ToString
andFromString
annotations on the specified class, class hierarchy or immediate parent interfaces. Finally, it handlesEnum
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 theClass
object generics is known.The search algorithm first searches the registered converters. It then searches for
ToString
andFromString
annotations on the specified class, class hierarchy or immediate parent interfaces. Finally, it handlesEnum
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 theClass
object generics are unknown'?'. The returned type is declared withObject
instead of '?' to allow theToStringConverter
to be invoked.The search algorithm first searches the registered converters. It then searches for
ToString
andFromString
annotations on the specified class, class hierarchy or immediate parent interfaces. Finally, it handlesEnum
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
-
findConverterQuiet
private <T> TypedStringConverter<T> findConverterQuiet(java.lang.Class<T> cls)
Finds 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, null if no converter
- Throws:
java.lang.RuntimeException
- if invalid
-
findAnyConverter
private <T> TypedStringConverter<T> findAnyConverter(java.lang.Class<T> cls)
Finds 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 nullconverter
- the String converter, not null- Throws:
java.lang.IllegalArgumentException
- if the class or converter are nulljava.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 nulltoString
- the to String converter, typically a method reference, not nullfromString
- the from String converter, typically a method reference, not null- Throws:
java.lang.IllegalArgumentException
- if the class or converter are nulljava.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
andFromString
. 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 nulltoStringMethodName
- the name of the method converting to a string, not nullfromStringMethodName
- the name of the method converting from a string, not null- Throws:
java.lang.IllegalArgumentException
- if the class or method name are null or invalidjava.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
andFromString
. 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 nulltoStringMethodName
- the name of the method converting to a string, not null- Throws:
java.lang.IllegalArgumentException
- if the class or method name are null or invalidjava.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 nullmethodName
- 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 nullmethodName
- 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
-
toString
public java.lang.String toString()
Returns a simple string representation of the object.- Overrides:
toString
in classjava.lang.Object
- Returns:
- the string representation, never null
-
-