hm.binkley.util

Class Converter

java.lang.Object

hm.binkley.util.Converter

public final class Converter
extends Object

Converter is the opposite of toString(). It turns strings into objects. Useful, for example, when obtaining Java value types from XML.

Supports registered types explicitly with default registered conversions:

• Class
• InetAddress
• InetSocketAddress
• Path
• Pattern
• Resource
• List of Resources
• ResourceBundle
• TimeZone
• URI

Supports other types implicitly by looking for a single-argument string factory method or constructor in this order:

1. Factory method parse(String)
2. Factory method valueOf(String)
3. Factory method of(String)
4. Constructor T(String)
5. Constructor T(CharSequence)

Author:

B. K. Oxley (binkley)

See Also:

register(Class, Conversion), register(TypeToken, Conversion)

Pending:

Remove duplication with xprop, Discuss concurrency safety, Do factory methods need to consider CharSequence?

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Converter.Conversion<T,E extends Exception> Converts a string property value into a typed object.
static class	Converter.DuplicateConversion
static class	Converter.UnsupportedConversion

Constructor Summary

Constructors

Constructor and Description
Converter()

Method Summary

Modifier and Type	Method and Description
<T> T	convert(Class<T> type, String value) Converts the given value into an instance of type.
<T> T	convert(com.google.common.reflect.TypeToken<T> type, String value) Converts the given value into an instance of type.
<T> void	register(Class<T> type, Converter.Conversion<T,?> factory) Registers an object conversion.
<T> void	register(com.google.common.reflect.TypeToken<T> type, Converter.Conversion<T,?> factory) Registers an object conversion.
void	registerDate(String pattern) Registers a date format pattern for legacy java.util.Date.
Set<com.google.common.reflect.TypeToken<?>>	registered() Get an unmodifiable view of registered conversions.

Methods inherited from class java.lang.Object

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

Constructor Detail

Converter

public Converter()

Method Detail

register

public <T> void register(@Nonnull
                         Class<T> type,
                         @Nonnull
                         Converter.Conversion<T,?> factory)
                  throws Converter.DuplicateConversion

Registers an object conversion. Use this for plain types without consideration of generics.

Type Parameters:

T - the conversion type

Parameters:

type - the class token, never missing

factory - the converter, never missing

Throws:

Converter.DuplicateConversion - if the conversion is already registered

register

public <T> void register(@Nonnull
                         com.google.common.reflect.TypeToken<T> type,
                         @Nonnull
                         Converter.Conversion<T,?> factory)
                  throws Converter.DuplicateConversion

Registers an object conversion. Use this for types with generics, for example, collections.

Type Parameters:

T - the conversion type

Parameters:

type - the Guava type token, never missing

factory - the converter, never missing

Throws:

Converter.DuplicateConversion - if the conversion is already registered

registerDate

public void registerDate(@Nonnull
                         String pattern)

Registers a date format pattern for legacy java.util.Date. By default Converter uses the deprecated Date.Date(String) constructor.

This method is a convenience and a caution for surprising legacy date parsing. Better is to use java.time classes.

Parameters:

pattern - the date format pattern, never missing

convert

@Nonnull
public <T> T convert(@Nonnull
                               Class<T> type,
                               @Nonnull
                               String value)
                        throws Exception

Converts the given value into an instance of type. Use this for plain types without consideraton of generics.

Type Parameters:

T - the conversion type

Parameters:

type - the target type, never missing

value - the string to convert, never missing

Returns:

the converted instance of type, never missing

Throws:

Exception - if conversion fails

convert

@Nonnull
public <T> T convert(@Nonnull
                               com.google.common.reflect.TypeToken<T> type,
                               @Nonnull
                               String value)
                        throws Exception

Converts the given value into an instance of type. Use this for types with generis, for example, collections.

Type Parameters:

T - the conversion type

Parameters:

type - the target type, never missing

value - the string to convert, never missing

Returns:

the converted instance of type, never missing

Throws:

Exception - if conversion fails

registered

@Nonnull
public Set<com.google.common.reflect.TypeToken<?>> registered()

Get an unmodifiable view of registered conversions. Supported conversions are those implicit and those registered; registered takes precedence.

Returns:

the set of registered conversion types, never missing

Pending:

What is the best way to expose conversions for inspection/management?