net.sf.mmm.util.value.api
Interface ValueConverter<SOURCE,TARGET>

Type Parameters:

SOURCE - is the generic source-type.

TARGET - is the generic target-type.

All Superinterfaces:

SimpleValueConverter<SOURCE,TARGET>

All Known Subinterfaces:

ComposedValueConverter

All Known Implementing Classes:

AbstractComposedValueConverter, AbstractConverterToArray, AbstractRecursiveValueConverter, AbstractSimpleValueConverter, AbstractValueConverter, AbstractValueConverterToContainer, ComposedValueConverterImpl, ComposedValueConverterImpl.ComposedTargetTypeConverter, DefaultComposedValueConverter, ValueConverterToArrayOfBoolean, ValueConverterToArrayOfByte, ValueConverterToArrayOfDouble, ValueConverterToArrayOfFloat, ValueConverterToArrayOfInt, ValueConverterToArrayOfLong, ValueConverterToArrayOfObject, ValueConverterToArrayOfShort, ValueConverterToBoolean, ValueConverterToCalendar, ValueConverterToClass, ValueConverterToCollection, ValueConverterToCompatiblePojo, ValueConverterToDate, ValueConverterToEnum, ValueConverterToFile, ValueConverterToMap, ValueConverterToNumber, ValueConverterToString

@ComponentSpecification(plugin=true)
public interface ValueConverter<SOURCE,TARGET>
extends SimpleValueConverter<SOURCE,TARGET>

This is the interface for a converter that converts a value from a source-type to a specific target-type.
ATTENTION:
An implementation of this interface should be stateless and thread-safe.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

TARGET	convert(SOURCE value, Object valueSource, Class<? extends TARGET> targetClass) This method converts the given pojo to the <TARGET>-type.
TARGET	convert(SOURCE value, Object valueSource, GenericType<? extends TARGET> targetType) This method converts the given pojo to the <TARGET>-type.
Class<SOURCE>	getSourceType() This the type of the value accepted by this converter.
Class<TARGET>	getTargetType() Is the guaranteed return-type of the conversion.

Method Detail

getSourceType

Class<SOURCE> getSourceType()

This the type of the value accepted by this converter. Use Object if you want to accept any value. A very common source-type is String.

Returns:

the source-type.

getTargetType

Class<TARGET> getTargetType()

Is the guaranteed return-type of the conversion. This information is used externally to choose the most specific ValueConverter that is appropriate for the conversion.
E.g. a generic converter can have Object as target-type while a specific converter may have Collection as target-type. Now if an object (compliant with the source-type) needs to be converted to a Collection or List, the specific converter is used while for other objects the generic converter is chosen.
Please note that the target-type is often more general than the actual returned result. So a ValueConverter that converts a comma-separated String to an ArrayList will typically declare List as target-type.

Returns:

the target-type.

convert

TARGET convert(SOURCE value,
               Object valueSource,
               Class<? extends TARGET> targetClass)
               throws ValueException

This method converts the given pojo to the <TARGET>-type.

Specified by:

convert in interface SimpleValueConverter<SOURCE,TARGET>

Parameters:

value - is the value to convert.

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 to convert the value to.

Returns:

the converted value or null if the conversion is NOT possible. The returned value has to be an instance of the given targetType.

Throws:

ValueException - if the conversion failed (e.g. the given value is illegal for the given targetClass).

See Also:

convert(Object, Object, GenericType)

convert

TARGET convert(SOURCE value,
               Object valueSource,
               GenericType<? extends TARGET> targetType)
               throws ValueException

This method converts the given pojo to the <TARGET>-type.

Parameters:

value - is the value to convert.

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.

targetType - is the GenericType to convert the value to. It is potentially generic and therefore contains more detailed information than a Class. E.g. the targetType could be java.util.List<Long>. This could help e.g. if the value is a string like "2, 47, 4252525".

Returns:

the converted value or null if the conversion is NOT possible. The returned value has to be an instance of the given targetType.

Throws:

ValueException - if the conversion failed (e.g. the given value is illegal for the given targetClass).