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

static StringConvert

INSTANCE An immutable global instance.

Constructor Summary

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

StringConvert(boolean includeJdkConverters)
Creates a new conversion manager.

Method Summary

<T> T	convertFromString(Class<T> cls, String str) Converts the specified object from a String.
<T> String	convertToString(Class<T> cls, T object) Converts the specified object to a String.
<T> String	convertToString(T object) Converts the specified object to a String.
<T> StringConverter<T>	findConverter(Class<T> cls) Finds a suitable converter for the type.
<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.
<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.

Methods inherited from class java.lang.Object

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

Field Detail

INSTANCE

public static final StringConvert INSTANCE

An immutable global instance.

This instance cannot be added to using register(java.lang.Class, org.joda.convert.StringConverter), however annotated classes are picked up. To register your own converters, simply create an instance of this class.

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)

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.

Parameters:

includeJdkConverters - true to include the JDK converters

Method Detail

convertToString

public <T> String convertToString(T object)

Converts the specified object to a String.

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

Type Parameters:

T - the type to convert from

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 <T> String convertToString(Class<T> cls,
                                  T object)

Converts the specified object to a String.

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

Type Parameters:

T - the type to convert from

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 findConverter(java.lang.Class) 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

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 could be useful in other frameworks.

The search algorithm first searches the registered converters. It then searches for ToString and FromString annotations on the specified class. Both searches consider superclasses, but not interfaces.

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

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

toString

public String toString()

Returns a simple string representation of the object.

Overrides:

toString in class Object

Returns:

the string representation, never null