public final class StringConvert
extends java.lang.Object
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.
Modifier and Type | Field and 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 and Description |
---|
StringConvert()
Creates a new conversion manager including the JDK converters.
|
StringConvert(boolean includeJdkConverters,
StringConverterFactory... factories)
Creates a new conversion manager.
|
Modifier and Type | Method and Description |
---|---|
<T> T |
convertFromString(java.lang.Class<T> cls,
java.lang.String str)
Converts the specified object from a
String . |
java.lang.String |
convertToString(java.lang.Class<?> cls,
java.lang.Object object)
Converts the specified object to a
String . |
java.lang.String |
convertToString(java.lang.Object object)
Converts the specified object to a
String . |
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.
|
public static final StringConvert 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.
private static final TypedStringConverter<?> CACHED_NULL
private final java.util.concurrent.CopyOnWriteArrayList<StringConverterFactory> factories
private final java.util.concurrent.ConcurrentMap<java.lang.Class<?>,TypedStringConverter<?>> registered
public StringConvert()
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.
public StringConvert(boolean includeJdkConverters, StringConverterFactory... factories)
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.
includeJdkConverters
- true to include the JDK convertersfactories
- optional array of factories to use, not nullpublic static StringConvert create()
The returned converter is a new instance that includes additional 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.
private void tryRegisterGuava()
className
- the class name, not nullprivate void tryRegister(java.lang.String className, java.lang.String fromStringMethodName)
className
- the class name, not nullpublic java.lang.String convertToString(java.lang.Object object)
String
.
This uses findConverter(java.lang.Class<T>)
to provide the converter.
object
- the object to convert, null returns nulljava.lang.RuntimeException
- (or subclass) if unable to convertpublic java.lang.String convertToString(java.lang.Class<?> cls, java.lang.Object object)
String
.
This uses findConverter(java.lang.Class<T>)
to provide the converter.
The class can be provided to select a more specific converter.
cls
- the class to convert from, not nullobject
- the object to convert, null returns nulljava.lang.RuntimeException
- (or subclass) if unable to convertpublic <T> T convertFromString(java.lang.Class<T> cls, java.lang.String str)
String
.
This uses findConverter(java.lang.Class<T>)
to provide the converter.
T
- the type to convert tocls
- the class to convert to, not nullstr
- the string to convert, null returns nulljava.lang.RuntimeException
- (or subclass) if unable to convertpublic boolean isConvertible(java.lang.Class<?> cls)
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.
cls
- the class to find a converter for, null returns falsepublic <T> StringConverter<T> findConverter(java.lang.Class<T> cls)
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 in the
class hierarchy and immediate parent interfaces.
It then searches for ToString
and FromString
annotations on the
specified class, class hierarchy or immediate parent interfaces.
Finally, it handles Enum
instances.
T
- the type of the convertercls
- the class to find a converter for, not nulljava.lang.RuntimeException
- (or subclass) if no converter foundpublic StringConverter<java.lang.Object> findConverterNoGenerics(java.lang.Class<?> cls)
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 in the
class hierarchy and immediate parent interfaces.
It then searches for ToString
and FromString
annotations on the
specified class, class hierarchy or immediate parent interfaces.
Finally, it handles Enum
instances.
cls
- the class to find a converter for, not nullObject
to avoid generics, not nulljava.lang.RuntimeException
- (or subclass) if no converter foundpublic <T> TypedStringConverter<T> findTypedConverter(java.lang.Class<T> cls)
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 in the
class hierarchy and immediate parent interfaces.
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.
T
- the type of the convertercls
- the class to find a converter for, not nulljava.lang.RuntimeException
- (or subclass) if no converter foundpublic TypedStringConverter<java.lang.Object> findTypedConverterNoGenerics(java.lang.Class<?> cls)
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 in the
class hierarchy and immediate parent interfaces.
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.
cls
- the class to find a converter for, not nullObject
to avoid generics, not nulljava.lang.RuntimeException
- (or subclass) if no converter foundprivate <T> TypedStringConverter<T> findConverterQuiet(java.lang.Class<T> cls)
T
- the type of the convertercls
- the class to find a method for, not nulljava.lang.RuntimeException
- if invalidprivate <T> TypedStringConverter<T> findAnyConverter(java.lang.Class<T> cls)
T
- the type of the convertercls
- the class to find a method for, not nulljava.lang.RuntimeException
- if invalidpublic void registerFactory(StringConverterFactory factory)
This will be registered ahead of all existing factories.
No new factories may be registered for the global singleton.
factory
- the converter factory, not nulljava.lang.IllegalStateException
- if trying to alter the global singletonpublic <T> void register(java.lang.Class<T> cls, StringConverter<T> converter)
The converter will be used for subclasses unless overidden.
No new converters may be registered for the global singleton.
T
- the type of the convertercls
- the class to register a converter for, not nullconverter
- the String converter, not nulljava.lang.IllegalArgumentException
- if the class or converter are nulljava.lang.IllegalStateException
- if trying to alter the global singletonpublic <T> void register(java.lang.Class<T> cls, ToStringConverter<T> toString, FromStringConverter<T> fromString)
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.
T
- the type of the convertercls
- 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 nulljava.lang.IllegalArgumentException
- if the class or converter are nulljava.lang.IllegalStateException
- if trying to alter the global singletonpublic <T> void registerMethods(java.lang.Class<T> cls, java.lang.String toStringMethodName, java.lang.String fromStringMethodName)
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");
T
- the type of the convertercls
- 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 nulljava.lang.IllegalArgumentException
- if the class or method name are null or invalidjava.lang.IllegalStateException
- if trying to alter the global singletonpublic <T> void registerMethodConstructor(java.lang.Class<T> cls, java.lang.String toStringMethodName)
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");
T
- the type of the convertercls
- the class to register a converter for, not nulltoStringMethodName
- the name of the method converting to a string, not nulljava.lang.IllegalArgumentException
- if the class or method name are null or invalidjava.lang.IllegalStateException
- if trying to alter the global singletonprivate java.lang.reflect.Method findToStringMethod(java.lang.Class<?> cls, java.lang.String methodName)
cls
- the class to find a method for, not nullmethodName
- the name of the method to find, not nulltoString
private java.lang.reflect.Method findFromStringMethod(java.lang.Class<?> cls, java.lang.String methodName)
cls
- the class to find a method for, not nullmethodName
- the name of the method to find, not nulltoString
private <T> java.lang.reflect.Constructor<T> findFromStringConstructorByType(java.lang.Class<T> cls)
T
- the type of the convertercls
- the class to find a method for, not nulltoString
public java.lang.String toString()
toString
in class java.lang.Object