org.microbean.settings

Class Converters

java.lang.Object

org.microbean.settings.Converters

All Implemented Interfaces:

ConverterProvider

public final class Converters
extends Object
implements ConverterProvider

A hub for the centralized conversion of Values.

Converters instances compute Converters on demand in many cases and are normally used in standalone environments.

Author:

Laird Nelson

Constructor Summary

Constructors

Constructor and Description
Converters() Creates a new Converters instance.
Converters(Collection<? extends Converter<?>> converters) Creates a new Converters instance.

Method Summary

Modifier and Type	Method and Description
<T> T	convert(Value value, Class<T> type) Converts the supplied Value to an object of the proper type and returns the result of the conversion using a Converter previously installed under a Type equal to the supplied Class.
<T> T	convert(Value value, TypeLiteral<T> type) Converts the supplied Value to an object of the proper type and returns the result of the conversion using a Converter previously installed under a Type equal to the supplied TypeLiteral's Type.
<T> Converter<? extends T>	getConverter(Class<T> type) Returns a Converter capable of converting Values into objects of the supplied type.
Converter<?>	getConverter(Type type) Returns a Converter capable of converting Values into objects of the supplied type.
<T> Converter<? extends T>	getConverter(TypeLiteral<T> type) Returns a Converter capable of converting Values into objects of the supplied type.
<T> Converter<? extends T>	putConverter(Class<T> type, Converter<? extends T> converter) Installs the supplied Converter under the supplied Class and returns any Converter previously installed under a Type equal to that Class.
<T> Converter<? extends T>	putConverter(TypeLiteral<T> type, Converter<? extends T> converter) Installs the supplied Converter under the supplied TypeLiteral's Type and returns any Converter previously installed under a Type equal to that Type.
<T> Converter<? extends T>	removeConverter(Class<T> key) Uninstalls and returns any Converter stored under a key equal to the supplied key.
<T> Converter<? extends T>	removeConverter(TypeLiteral<T> key) Uninstalls and returns any Converter stored under a key equal to the supplied key.

Methods inherited from class java.lang.Object

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

Constructor Detail

Converters

public Converters()

Creates a new Converters instance.

Converters

public Converters(Collection<? extends Converter<?>> converters)

Creates a new Converters instance.

Parameters:

converters - a Collection of Converters that will be installed into this Converters instance; may be null

Throws:

ConcurrentModificationException - if some other thread modifies the supplied Collection while iteration is in progress

Method Detail

getConverter

public final <T> Converter<? extends T> getConverter(TypeLiteral<T> type)

Returns a Converter capable of converting Values into objects of the supplied type.

Specified by:

getConverter in interface ConverterProvider

Type Parameters:

T - the conversion type

Parameters:

type - a TypeLiteral describing the conversion type; must not be null

Returns:

a non-null Converter capable of converting Values into objects of the proper type

Throws:

NullPointerException - if type is null

IllegalArgumentException - if no Converter is available for the supplied type

See Also:

ConverterProvider.getConverter(Type)

Idempotency:

Because Converters can be added to this Converters instance, this method may return different Converter instances over time given the same type.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

getConverter

public final <T> Converter<? extends T> getConverter(Class<T> type)

Returns a Converter capable of converting Values into objects of the supplied type.

Specified by:

getConverter in interface ConverterProvider

Type Parameters:

T - the conversion type

Parameters:

type - a Class describing the conversion type; must not be null

Returns:

a non-null Converter capable of converting Values into objects of the proper type

Throws:

NullPointerException - if type is null

IllegalArgumentException - if no Converter is available for the supplied type

See Also:

ConverterProvider.getConverter(Type)

Idempotency:

Because Converters can be added to this Converters instance, this method may return different Converter instances over time given the same type.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

getConverter

public final Converter<?> getConverter(Type type)

Returns a Converter capable of converting Values into objects of the supplied type.

Specified by:

getConverter in interface ConverterProvider

Parameters:

type - a Type describing the conversion type; must not be null

Returns:

a non-null Converter capable of converting Values into objects of the proper type

Throws:

NullPointerException - if type is null

IllegalArgumentException - if no Converter is available for the supplied type

Idempotency:

Because Converters can be added to this Converters instance, this method may return different Converter instances over time given the same type.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

putConverter

public final <T> Converter<? extends T> putConverter(Class<T> type,
                                                     Converter<? extends T> converter)

Installs the supplied Converter under the supplied Class and returns any Converter previously installed under a Type equal to that Class.

Type Parameters:

T - the conversion type

Parameters:

type - the Class describing the conversion type of the supplied Converter; must not be null

converter - the Converter to install; must not be null

Returns:

the Converter previously installed under a Type equal to the supplied Class, or null

Throws:

NullPointerException - if type or converter is null

See Also:

getConverter(Class)

Idempotency:

This method is not idempotent.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

putConverter

public final <T> Converter<? extends T> putConverter(TypeLiteral<T> type,
                                                     Converter<? extends T> converter)

Installs the supplied Converter under the supplied TypeLiteral's Type and returns any Converter previously installed under a Type equal to that Type.

Type Parameters:

T - the conversion type

Parameters:

type - the TypeLiteral describing the conversion type of the supplied Converter; must not be null

converter - the Converter to install; must not be null

Returns:

the Converter previously installed under a Type equal to the supplied TypeLiteral's Type, or null

Throws:

NullPointerException - if type or converter is null

See Also:

getConverter(TypeLiteral)

Idempotency:

This method is not idempotent.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

removeConverter

public final <T> Converter<? extends T> removeConverter(Class<T> key)

Uninstalls and returns any Converter stored under a key equal to the supplied key.

Type Parameters:

T - the conversion type

Parameters:

key - the key designating the Converter to remove; must not be null

Returns:

the Converter that was uninstalled, or null

Throws:

NullPointerException - if key is null

Idempotency:

This method will uninstall and return any Converter stored under a key equal to the supplied key, and, if then invoked with the same key, will return null thereafter.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

removeConverter

public final <T> Converter<? extends T> removeConverter(TypeLiteral<T> key)

Uninstalls and returns any Converter stored under a key equal to the supplied key.

Type Parameters:

T - the conversion type

Parameters:

key - the key designating the Converter to remove; must not be null

Returns:

the Converter that was uninstalled, or null

Throws:

NullPointerException - if key is null

Idempotency:

This method will uninstall and return any Converter stored under a key equal to the supplied key, and, if then invoked with the same key, will return null thereafter.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

convert

public final <T> T convert(Value value,
                           Class<T> type)

Converts the supplied Value to an object of the proper type and returns the result of the conversion using a Converter previously installed under a Type equal to the supplied Class.

Type Parameters:

T - the conversion type

Parameters:

value - the Value to convert; may be null

type - the Class designating the Converter to use; must not be null

Returns:

the result of the conversion, which may be null

Throws:

NullPointerException - if type is null

IllegalArgumentException - if conversion fails because of a problem with the supplied Value

ConversionException - if conversion fails for any other reason

Idempotency:

This method may return different results when supplied with the same parameter values over repeated invocations.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

convert

public final <T> T convert(Value value,
                           TypeLiteral<T> type)

Converts the supplied Value to an object of the proper type and returns the result of the conversion using a Converter previously installed under a Type equal to the supplied TypeLiteral's Type.

Type Parameters:

T - the conversion type

Parameters:

value - the Value to convert; may be null

type - the TypeLiteral designating the Converter to use; must not be null

Returns:

the result of the conversion, which may be null

Throws:

NullPointerException - if type is null

IllegalArgumentException - if conversion fails because of a problem with the supplied Value

ConversionException - if conversion fails for any other reason

Idempotency:

This method may return different results when supplied with the same parameter values over repeated invocations.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.