net.sf.mmm.util.value.api

Interface GenericValueConverter<SOURCE>

Type Parameters:

SOURCE - is the generic type of the values to convert.

All Known Subinterfaces:

ComposedValueConverter, StringValueConverter

All Known Implementing Classes:

AbstractComposedValueConverter, AbstractGenericValueConverter, ComposedValueConverterImpl, DefaultComposedValueConverter, StringValueConverterImpl

public interface GenericValueConverter<SOURCE>

This is the interface for generic conversion of values from a specific source-type ( <SOURCE>) to a given target-type ( <TARGET>).
ATTENTION:
An implementation of this interface should be stateless and thread-safe.

Since:

1.0.1

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

ComposedValueConverter, StringValueConverter

Method Summary

Modifier and Type	Method and Description
<TARGET> TARGET	convertValue(SOURCE value, Object valueSource, Class<TARGET> targetClass) This method converts the given value to the given type.
<TARGET> TARGET	convertValue(SOURCE value, Object valueSource, Class<TARGET> targetClass, TARGET defaultValue) This method converts the given value to the given type.
<TARGET> TARGET	convertValue(SOURCE value, Object valueSource, Class<TARGET> targetClass, Type targetType) This method converts the given value to the given type.
<TARGET> TARGET	convertValue(SOURCE value, Object valueSource, Class<TARGET> targetClass, Type targetType, TARGET defaultValue) This method converts the given value to the given type.
<TARGET extends Number> TARGET	convertValue(SOURCE value, Object valueSource, TARGET minimum, TARGET maximum) This method converts the given value to a numeric type and also validates that it is in the given range from minimum to maximum.
<TARGET extends Number> TARGET	convertValue(SOURCE value, Object valueSource, TARGET minimum, TARGET maximum, TARGET defaultValue) This method gets a numeric value and also validates that it is in the given range from minimum to maximum.

Method Detail

convertValue

<TARGET> TARGET convertValue(SOURCE value,
                             Object valueSource,
                             Class<TARGET> targetClass)
                      throws ValueNotSetException,
                             WrongValueTypeException

This method converts the given value to the given type.

Type Parameters:

TARGET - is the type to convert to.

Parameters:

value - is the value to convert. It may be null.

valueSource - describes the source of the value. This may be the filename where the value was read from, an XPath where the value was located in an XML document, etc. It is used in exceptions thrown if something goes wrong. This will help to find the problem easier.

targetClass - is the type the value should be converted to.

Returns:

the value converted to type.

Throws:

ValueNotSetException - if the given value is null.

WrongValueTypeException - if the given value is NOT null but can NOT be converted to the given type (e.g. if value is "12x" and type is Integer.class).

convertValue

<TARGET> TARGET convertValue(SOURCE value,
                             Object valueSource,
                             Class<TARGET> targetClass,
                             Type targetType)
                      throws ValueNotSetException,
                             WrongValueTypeException

This method converts the given value to the given type.

Type Parameters:

TARGET - is the type to convert to.

Parameters:

value - is the value to convert. It may be null.

valueSource - describes the source of the value. This may be the filename where the value was read from, an XPath where the value was located in an XML document, etc. It is used in exceptions thrown if something goes wrong. This will help to find the problem easier.

targetClass - is the type the value should be converted to. It is the raw-type of the given targetType.

targetType - is the type to convert the value to. It is potentially generic and therefore contains more detailed information than targetClass. E.g. the targetClass may be java.util.List while this targetType could be java.util.List<Long>. This could help e.g. if the value is a string like "2, 47, 4252525". The caller may supply the targetClass again here.

Returns:

the value converted to type.

Throws:

ValueNotSetException - if the given value is null.

WrongValueTypeException - if the given value is NOT null but can NOT be converted to the given type (e.g. if value is "12x" and type is Integer.class).

convertValue

<TARGET> TARGET convertValue(SOURCE value,
                             Object valueSource,
                             Class<TARGET> targetClass,
                             TARGET defaultValue)
                      throws WrongValueTypeException

This method converts the given value to the given type.

Type Parameters:

TARGET - is the type to convert to.

Parameters:

value - is the value to convert. It may be null.

valueSource - describes the source of the value. This may be the filename where the value was read from, an XPath where the value was located in an XML document, etc. It is used in exceptions thrown if something goes wrong. This will help to find the problem easier.

targetClass - is the type the value should be converted to.

defaultValue - is returned if the given value is null. It may also be null.

Returns:

the value converted to type or the defaultValue if value was null. It will only return null if both value and defaultValue are null.

Throws:

WrongValueTypeException - if the given value is NOT null but can NOT be converted to the given type (e.g. if value is "12x" and type is Integer.class).

convertValue

<TARGET> TARGET convertValue(SOURCE value,
                             Object valueSource,
                             Class<TARGET> targetClass,
                             Type targetType,
                             TARGET defaultValue)
                      throws WrongValueTypeException

This method converts the given value to the given type.

Type Parameters:

TARGET - is the type to convert to.

Parameters:

value - is the value to convert. It may be null.

valueSource - describes the source of the value. This may be the filename where the value was read from, an XPath where the value was located in an XML document, etc. It is used in exceptions thrown if something goes wrong. This will help to find the problem easier.

targetClass - is the type the value should be converted to. It is the raw-type of the given targetType.

targetType - is the type to convert the value to. It is potentially generic and therefore contains more detailed information than targetClass. E.g. the targetClass may be java.util.List while this targetType could be java.util.List<Long>. This could help e.g. if the value is a string like "2, 47, 4252525". The caller may supply the targetClass again here.

defaultValue - is returned if the given value is null. It may also be null.

Returns:

the value converted to type or the defaultValue if value was null. It will only return null if both value and defaultValue are null.

Throws:

WrongValueTypeException - if the given value is NOT null but can NOT be converted to the given type (e.g. if value is "12x" and type is Integer.class).

convertValue

<TARGET extends Number> TARGET convertValue(SOURCE value,
                                            Object valueSource,
                                            TARGET minimum,
                                            TARGET maximum)
                                     throws ValueNotSetException,
                                            WrongValueTypeException,
                                            ValueOutOfRangeException

This method converts the given value to a numeric type and also validates that it is in the given range from minimum to maximum.

Type Parameters:

TARGET - is the numeric-type to convert to.

Parameters:

value - is the value to convert. It may be null.

valueSource - describes the source of the value. This may be the filename where the value was read from, an XPath where the value was located in an XML document, etc. It is used in exceptions thrown if something goes wrong. This will help to find the problem easier.

minimum - is the minimum number allowed. Use MIN_VALUE (e.g. Double.MIN_VALUE) if unbound.

maximum - is the maximum number allowed. Use MAX_VALUE (e.g. Long.MAX_VALUE) if unbound.

Returns:

the requested value in the given range from minimum and maximum.

Throws:

ValueNotSetException - if the given value is null.

WrongValueTypeException - if the value is NO number.

ValueOutOfRangeException - if the value is NOT in the given range from minimum to maximum.

convertValue

<TARGET extends Number> TARGET convertValue(SOURCE value,
                                            Object valueSource,
                                            TARGET minimum,
                                            TARGET maximum,
                                            TARGET defaultValue)
                                     throws WrongValueTypeException,
                                            ValueOutOfRangeException

This method gets a numeric value and also validates that it is in the given range from minimum to maximum.

Type Parameters:

TARGET - is the numeric-type to convert to.

Parameters:

value - is the value to convert. It may be null.

valueSource - describes the source of the value. This may be the filename where the value was read from, an XPath where the value was located in an XML document, etc. It is used in exceptions thrown if something goes wrong. This will help to find the problem easier.

minimum - is the minimum number allowed. Use MIN_VALUE (e.g. Double.MIN_VALUE) if unbound.

maximum - is the maximum number allowed. Use MAX_VALUE (e.g. Long.MAX_VALUE) if unbound.

defaultValue - is the default returned if value is null. It may be null. Else it must be in the given range from minimum to maximum.

Returns:

the given value converted to <TARGET> in the range from minimum to maximum or the defaultValue if value is null. Will only be null if both value and defaultValue are null.

Throws:

WrongValueTypeException - if the value is NO number.

ValueOutOfRangeException - if the value is NOT in the given range from minimum to maximum.