com.im.df.api.support
Interface DFDataConvertor

All Known Subinterfaces:

DFDataAcceptor, DFDataComparator

public interface DFDataConvertor

This class is supposed to handle conversion to a certain data type from multiple formats. The Convertor can be parametrized using the Options bean, which can be obtained from the createOptions(). If createOptions returns null, no options are supported at all. In such case, the convert(java.lang.Object, java.lang.Object) method may ignore whatever options are passed. It is an error to pass an options instance to the checkDataAcceptance(java.lang.Object, java.lang.Object) or convert(java.lang.Object, java.lang.Object), which was not created using createOptions(). The methods will throw an IllegalArgumentException in such case. The convert(java.lang.Object, java.lang.Object) method may return null for neutral values of the input data. The convert(java.lang.Object, java.lang.Object) may throw an IllegalArgumentException to indicate the input data is not valid.

Method Summary

boolean	checkDataAcceptance(Object value, Object options) Acknowledges that the Converter can work with the passed data.
Object	convert(Object value, Object options) Converts the value.
Object	convert(Object value, Object options, List<String> messages) Converts the value.
Object	createOptions() Returns an option bean for the conversion.

Method Detail

checkDataAcceptance

boolean checkDataAcceptance(Object value,
                            Object options)

Acknowledges that the Converter can work with the passed data. The value null can be always accepted, but is converted to null, but it depends on each convertor implementation - this is not guaranteed.

Parameters:

value - The value to be converted

options - Optional options object. Can be null for the default conversion

Returns:

True if the value is correct, otherwise false. If true is returned then it's safe to use convert(java.lang.Object, java.lang.Object) method.

convert

Object convert(Object value,
               Object options)

Converts the value. Same as the 3 argument form except that feedback cannot be give to the user

Parameters:

value - The value to convert. Can be null (if checkDataAcceptance(java.lang.Object, java.lang.Object) returned true, but then null is typically returned. It also depends on convertor implementation.

options - The conversion options, or null for the default behaviour

Returns:

The converted value. Can return null.

Throws:

IllegalArgumentException - when value is not valid.

convert

Object convert(Object value,
               Object options,
               List<String> messages)

Converts the value. Conversion options can be specified (the bean can be obtained by the createOptions(). The method will throw an IllegalArgumentException, if the passed value is of unsupported type (first check using checkDataAcceptance(java.lang.Object, java.lang.Object), or the value is invalid.

Parameters:

value - The value to convert. Can be null (if checkDataAcceptance(java.lang.Object, java.lang.Object) returned true, but then null is typically returned. It also depends on convertor implementation.

options - The conversion options, or null for the default behaviour

messages - Allows messages to be reported to user by being added to this list. Can be null.

Returns:

The converted value. Can return null.

Throws:

IllegalArgumentException - when value is not valid.

createOptions

Object createOptions()

Returns an option bean for the conversion. If the method returns null, the converter does not support any options at all.