Package org.joda.convert

Class StringConvert

java.lang.Object

org.joda.convert.StringConvert

public final class StringConvert
extends 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 Summary

Fields

Modifier and Type	Field	Description
private static final TypedStringConverter<?>	CACHED_NULL	The cached null object.
private final CopyOnWriteArrayList<StringConverterFactory>	factories	The list of factories.
private final ConcurrentMap<Class<?>,FromStringConverter<?>>	fromStrings	The cache of from-strings.
static final StringConvert	INSTANCE	An immutable global instance.
(package private) static final boolean	LOG	Errors in class initialization are hard to debug.
private final ConcurrentMap<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

Modifier and Type	Method	Description
<T> T	convertFromString(Class<T> cls, String str)	Converts the specified object from a String.
String	convertToString(Class<?> cls, Object object)	Converts the specified object to a String.
String	convertToString(Object object)	Converts the specified object to a String.
static StringConvert	create()	Creates a new conversion manager including the extended standard set of converters.
<T> StringConverter<T>	findConverter(Class<T> cls)	Finds a suitable converter for the type.
StringConverter<Object>	findConverterNoGenerics(Class<?> cls)	Finds a suitable converter for the type with open generics.
private <T> TypedStringConverter<T>	findConverterQuiet(Class<T> cls)
private <T> Constructor<T>	findFromStringConstructorByType(Class<T> cls)	Finds the conversion method.
<T> FromStringConverter<T>	findFromStringConverter(Class<T> cls)	Finds a suitable from-string converter for the type.
private Method	findFromStringMethod(Class<?> cls, String methodName)	Finds the conversion method.
private Method	findToStringMethod(Class<?> cls, String methodName)	Finds the conversion method.
<T> TypedStringConverter<T>	findTypedConverter(Class<T> cls)	Finds a suitable converter for the type.
TypedStringConverter<Object>	findTypedConverterNoGenerics(Class<?> cls)	Finds a suitable converter for the type with open generics.
boolean	isConvertible(Class<?> cls)	Checks if a suitable converter exists for the type.
private static Class<?>	loadPrimitiveType(String fullName, ClassNotFoundException ex)
(package private) static Class<?>	loadType(String fullName)
private <T> TypedStringConverter<T>	lookupConverter(Class<T> cls)	Lookup a converter searching registered and annotated.
<T> void	register(Class<T> cls, StringConverter<T> converter)	Registers a converter for a specific type.
<T> void	register(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(Class<T> cls, String toStringMethodName)	Registers a converter for a specific type by method and constructor.
<T> void	registerMethods(Class<T> cls, String toStringMethodName, String fromStringMethodName)	Registers a converter for a specific type by method names.
String	toString()	Returns a simple string representation of the object.
private void	tryRegister(String className, 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	tryRegisterJava8()	Tries to register Java 8 classes.
private void	tryRegisterJava8Optionals()	Tries to register the Java 8 optional classes.
private void	tryRegisterThreeTenBackport()	Tries to register ThreeTen backport classes.
private void	tryRegisterThreeTenOld()	Tries to register ThreeTen ThreeTen/JSR-310 classes v0.6.3 and beyond.
private void	tryRegisterTimeZone()	Tries to register the subclasses of TimeZone.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

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.

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.

factories

private final CopyOnWriteArrayList<StringConverterFactory> factories

The list of factories.

registered

private final ConcurrentMap<Class<?>,TypedStringConverter<?>> registered

The cache of converters.

fromStrings

private final ConcurrentMap<Class<?>,FromStringConverter<?>> fromStrings

The cache of from-strings.

Constructor Details

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 Details

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.

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(String className,
 String fromStringMethodName)
                  throws ClassNotFoundException

Tries to register a class using the standard toString/parse pattern.

Parameters:

className - the class name, not null

Throws:

ClassNotFoundException - if the class does not exist

convertToString

public String convertToString(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:

RuntimeException - (or subclass) if unable to convert

convertToString

public String convertToString(Class<?> cls,
 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:

RuntimeException - (or subclass) if unable to convert

convertFromString

public <T> T convertFromString(Class<T> cls,
 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:

RuntimeException - (or subclass) if unable to convert

isConvertible

public boolean isConvertible(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(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:

RuntimeException - (or subclass) if no converter found

findConverterNoGenerics

public StringConverter<Object> findConverterNoGenerics(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:

RuntimeException - (or subclass) if no converter found

Since:

1.5

findTypedConverter

public <T> TypedStringConverter<T> findTypedConverter(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:

RuntimeException - (or subclass) if no converter found

Since:

1.7

findTypedConverterNoGenerics

public TypedStringConverter<Object> findTypedConverterNoGenerics(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:

RuntimeException - (or subclass) if no converter found

Since:

1.7

findFromStringConverter

public <T> FromStringConverter<T> findFromStringConverter(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:

RuntimeException - (or subclass) if no converter found

findConverterQuiet

private <T> TypedStringConverter<T> findConverterQuiet(Class<T> cls)

lookupConverter

private <T> TypedStringConverter<T> lookupConverter(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:

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:

IllegalStateException - if trying to alter the global singleton

Since:

1.5

register

public <T> void register(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:

IllegalArgumentException - if the class or converter are null

IllegalStateException - if trying to alter the global singleton

register

public <T> void register(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:

IllegalArgumentException - if the class or converter are null

IllegalStateException - if trying to alter the global singleton

Since:

1.3

registerMethods

public <T> void registerMethods(Class<T> cls,
 String toStringMethodName,
 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:

IllegalArgumentException - if the class or method name are null or invalid

IllegalStateException - if trying to alter the global singleton

registerMethodConstructor

public <T> void registerMethodConstructor(Class<T> cls,
 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:

IllegalArgumentException - if the class or method name are null or invalid

IllegalStateException - if trying to alter the global singleton

findToStringMethod

private Method findToStringMethod(Class<?> cls,
 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 Method findFromStringMethod(Class<?> cls,
 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> Constructor<T> findFromStringConstructorByType(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 Class<?> loadType(String fullName)
                  throws ClassNotFoundException

Throws:

ClassNotFoundException

loadPrimitiveType

private static Class<?> loadPrimitiveType(String fullName,
 ClassNotFoundException ex)
                                   throws ClassNotFoundException

Throws:

ClassNotFoundException

toString

public String toString()

Returns a simple string representation of the object.

Overrides:

toString in class Object

Returns:

the string representation, never null