Package org.apache.sis.util
Interface ObjectConverter<S,T>

 Type Parameters:
S
 the type of objects to convert.T
 the type of converted objects.
 All Superinterfaces:
Function<S,T>
public interface ObjectConverter<S,T> extends Function<S,T>
A function which converts instances of source type to instances of target type. The source and target types may be the same, in which case theObjectConverter
actually converts the values rather than the type.The main method of this interface is
apply(Object)
, which receives an object of type S and returns an object of type T. The set of all S values for whichapply(S)
does not throwUnconvertibleObjectException
is called the domain of this function, regardless of whether the T result isnull
or not.Function propertiesSome characteristics about the S to T mapping are given by theproperties()
enumeration, together with thegetSourceClass()
andgetTargetClass()
methods. Some possible function properties are: Injective if no pair of S can produce
the same T value (e.g.: conversions from
Integer
toString
).  Surjective if every values of T can be
created from one or many values of S (e.g.: conversions from
String
toInteger
).  Bijective if there is a onetoone relationship between the S and T values.
 Order preserving if any sequence of
increasing S values (in the sense of
Comparable
) is mapped to a sequence of increasing T values.  Order reversing if any sequence of
increasing S values (in the sense of
Comparable
) is mapped to a sequence of decreasing T values.
Example: The function properties regarding order is important when convertingBelow are some guidelines about the function properties that a converter can declare:Range
objects. For example if the converter reverses the value ordering (e.g. reverses the sign of numerical values), then the minimum and maximum values in eachRange
instance need to be interchanged. If the ordering is not preserved at all (neither directly or reversed), as for example in the conversion fromNumber
toString
, then we can not convert ranges at all. If
apply(S)
returnsnull
for unconvertible objects, then thisObjectConverter
can not be declared injective because more than one S value can produce the same T value (namelynull
).  If
apply(S)
throws an exception for unconvertible objects, then thisObjectConverter
can be declared as an injective function if the other values met the criteria.
 Since:
 0.3
 See Also:
ObjectConverters
Defined in the
sisutility
module


Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description T
apply(S object)
Converts the given object from the source type S to the target type T.Class<S>
getSourceClass()
Returns the type of objects to convert.Class<T>
getTargetClass()
Returns the type of converted objects.ObjectConverter<T,S>
inverse()
Returns a converter capable to convert instances of T back to instances of S.Set<FunctionProperty>
properties()
Returns the manner in which source values (S) are mapped to target values (T).



Method Detail

properties
Set<FunctionProperty> properties()
Returns the manner in which source values (S) are mapped to target values (T). Some possible function properties are: Injective if no pair of S can produce
the same T value (e.g.: conversions from
Integer
toString
).  Surjective if every values of T can be
created from one or many values of S (e.g.: conversions from
String
toInteger
).  Bijective if there is a onetoone relationship between the S and T values.
 Order preserving if any sequence of
increasing S values (in the sense of
Comparable
) is mapped to a sequence of increasing T values.  Order reversing if any sequence of
increasing S values (in the sense of
Comparable
) is mapped to a sequence of decreasing T values.
apply(Object)
method returnsnull
for unconvertible source values, then this properties set can not containFunctionProperty.INJECTIVE
because more than one source value could be converted to the samenull
target value. Returns:
 the manners in which source values are mapped to target values. May be an empty set, but never null.
 Injective if no pair of S can produce
the same T value (e.g.: conversions from

getSourceClass
Class<S> getSourceClass()
Returns the type of objects to convert. Returns:
 the type of objects to convert.

getTargetClass
Class<T> getTargetClass()
Returns the type of converted objects. Returns:
 the type of converted objects.

apply
T apply(S object) throws UnconvertibleObjectException
Converts the given object from the source type S to the target type T. If the given object can not be converted, then this method may either returnsnull
or throws an exception, at implementation choice (except for injective functions, which must throw an exception  see the class Javadoc for more discussion about function properties).Example: in Apache SIS implementation, converters fromString
toNumber
distinguish two kinds of unconvertible objects: Null or empty source string result in a
null
value to be returned.  All other kind of unparsable strings results in an exception to be thrown.
""
value is unconvertible but nevertheless considered as part of the converter domain, and is mapped to "no number". All other unparsable strings are considered outside the converter domain. Specified by:
apply
in interfaceFunction<S,T>
 Parameters:
object
 the object to convert, ornull
. Returns:
 the converted object, or
null
.  Throws:
UnconvertibleObjectException
 if the given object is not an element of the function domain.
 Null or empty source string result in a

inverse
ObjectConverter<T,S> inverse() throws UnsupportedOperationException
Returns a converter capable to convert instances of T back to instances of S. Before to invoke this method, callers can verify if this converter is invertible as below:if (converter.properties().contains(FunctionProperty.INVERTIBLE)) { // Call to converter.inverse() is allowed here. }
 Returns:
 a converter for converting instances of T back to instances of S.
 Throws:
UnsupportedOperationException
 if this converter is not invertible. See Also:
FunctionProperty.INVERTIBLE

