Interface ObjectConverter<S,T>

Type Parameters:
S - the type of objects to convert.
T - the type of converted objects.
All Superinterfaces:
Function<S,T>
All Known Implementing Classes:
AngleConverter, AngleConverter.Inverse, ArrayConverter, CharSequenceConverter, CollectionConverter, CollectionConverter.List, CollectionConverter.Set, ConversionKeys, DateConverter, DateConverter.Inverse, DateConverter.Long, DateConverter.SQL, DateConverter.Timestamp, DefaultMetadata.FromLocale, DefaultMetadata.ToLocale, DerivedMap, DerivedMap.Invertible, DerivedMap.InvertibleKey, DerivedMap.InvertibleValue, FallbackConverter, FormattedCharacterIterator.Filter, FormattedCharacterIterator.Selector, FractionConverter, FractionConverter.FromInteger, GeometryParser, IdentityConverter, NumberConverter, NumberConverter.Comparable, ObjectToString, ObjectToString.CodeList, ObjectToString.Enum, PathConverter, PathConverter.FilePath, PathConverter.FileURI, PathConverter.FileURL, PathConverter.PathFile, PathConverter.PathURI, PathConverter.PathURL, PathConverter.URI_URL, PathConverter.URIFile, PathConverter.URIPath, PathConverter.URL_URI, PathConverter.URLFile, PathConverter.URLPath, PropertiesConverter, StringConverter, StringConverter.Angle, StringConverter.BigDecimal, StringConverter.BigInteger, StringConverter.Boolean, StringConverter.Byte, StringConverter.Charset, StringConverter.CodeList, StringConverter.Double, StringConverter.Enum, StringConverter.File, StringConverter.Float, StringConverter.Integer, StringConverter.InternationalString, StringConverter.Locale, StringConverter.Long, StringConverter.Number, StringConverter.Path, StringConverter.Short, StringConverter.Unit, StringConverter.URI, StringConverter.URL, StringJoinOperation.ForFeature, SurjectiveConverter, SystemConverter, SystemUnit.DimToUnit, TimeEncoding

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 the ObjectConverter 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 which apply(S) does not throw UnconvertibleObjectException is called the domain of this function, regardless of whether the T result is null or not.

Function properties

Some characteristics about the S to T mapping are given by the properties() enumeration, together with the getSourceClass() and getTargetClass() methods. Some possible function properties are:
  • Injective if no pair of S can produce the same T value (e.g.: conversions from Integer to String).
  • Surjective if every values of T can be created from one or many values of S (e.g.: conversions from String to Integer).
  • Bijective if there is a one-to-one 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 converting 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 each Range instance need to be interchanged. If the ordering is not preserved at all (neither directly or reversed), as for example in the conversion from Number to String, then we cannot convert ranges at all.
Below are some guidelines about the function properties that a converter can declare:
  • If apply(S) returns null for unconvertible objects, then this ObjectConverter cannot be declared injective because more than one S value can produce the same T value (namely null).
  • If apply(S) throws an exception for unconvertible objects, then this ObjectConverter can be declared as an injective function if the other values met the criteria.
Since:
0.3
Version:
0.3
See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    apply(S object)
    Converts the given object from the source type S to the target type T.
    Returns the type of objects to convert.
    Returns the type of converted objects.
    Returns a converter capable to convert instances of T back to instances of S.
    Returns the manner in which source values (S) are mapped to target values (T).

    Methods inherited from interface java.util.function.Function

    andThen, compose
  • Method Details

    • 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 to String).
      • Surjective if every values of T can be created from one or many values of S (e.g.: conversions from String to Integer).
      • Bijective if there is a one-to-one 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.
      Note that if the apply(Object) method returns null for unconvertible source values, then this properties set cannot contain FunctionProperty.INJECTIVE because more than one source value could be converted to the same null target value.
      Returns:
      the manners in which source values are mapped to target values. May be an empty set, but never null.
    • 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 cannot be converted, then this method may either returns null 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 from String to Number 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.
      In other words, the "" 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 interface Function<S,T>
      Parameters:
      object - the object to convert, or null.
      Returns:
      the converted object, or null.
      Throws:
      UnconvertibleObjectException - if the given object is not an element of the function domain.
    • inverse

      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:
      Returns:
      a converter for converting instances of T back to instances of S.
      Throws:
      UnsupportedOperationException - if this converter is not invertible.
      See Also: