Class SystemConverter<S,T>

java.lang.Object
org.apache.sis.internal.converter.ClassPair<S,T>
org.apache.sis.internal.converter.SystemConverter<S,T>
Type Parameters:
S - the base type of source objects.
T - the base type of converted objects.
All Implemented Interfaces:
Serializable, Function<S,T>, ObjectConverter<S,T>
Direct Known Subclasses:
AngleConverter, AngleConverter.Inverse, ArrayConverter, CharSequenceConverter, CollectionConverter, DateConverter, DateConverter.Inverse, FallbackConverter, FractionConverter, FractionConverter.FromInteger, IdentityConverter, NumberConverter, NumberConverter.Comparable, ObjectToString, PathConverter, StringConverter

abstract class SystemConverter<S,T> extends ClassPair<S,T> implements ObjectConverter<S,T>
Base class of all converters defined in the org.apache.sis.internal package. Those converters are returned by system-wide ConverterRegistry, and cached for reuse.

Immutability and thread safety

This base class is immutable, and thus inherently thread-safe. Subclasses should be immutable and thread-safe too if they are intended to be cached in ConverterRegistry.
Since:
0.3
Version:
1.0
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
  • Constructor Details

    • SystemConverter

      SystemConverter(Class<S> sourceClass, Class<T> targetClass)
      Creates a new converter for the given source and target classes.
      Parameters:
      sourceClass - the source class.
      targetClass - the target class.
  • Method Details

    • getSourceClass

      public final Class<S> getSourceClass()
      Returns the source class given at construction time.
      Specified by:
      getSourceClass in interface ObjectConverter<S,T>
      Returns:
      the type of objects to convert.
    • getTargetClass

      public final Class<T> getTargetClass()
      Returns the target class given at construction time.
      Specified by:
      getTargetClass in interface ObjectConverter<S,T>
      Returns:
      the type of converted objects.
    • bijective

      static Set<FunctionProperty> bijective()
      Convenience method for ObjectConverter.properties() implementation of bijective converters between comparable objects. The converter is presumed invertible and to preserve order.
    • inverse

      Default to non-invertible conversion. Must be overridden by subclasses that support inversions.
      Specified by:
      inverse in interface ObjectConverter<S,T>
      Returns:
      a converter for converting instances of T back to instances of S.
      Throws:
      UnsupportedOperationException - if this converter is not invertible.
      See Also:
    • equals

      public final boolean equals(Object other)
      Performs the comparisons documented in ClassPair.equals(Object) with an additional check: if both objects to compare are SystemConverter, then also requires the two objects to be of the same class. We do that in order to differentiate the "ordinary" converters from the FallbackConverter.

      Implementation note

      This is admittedly a little bit convolved. A cleaner approach would have been to not allow the ConverterRegister hash map to contain anything else than ClassPair keys, but the current strategy of using the same instance for keys and values reduces a little bit the number of objects to create in the JVM. Another cleaner approach would have been to compare ObjectConverters in a separated method, but users invoking equals on our system converters could be surprised.

      Our equals(Object) definition have the following implications regarding the way to use the ConverterRegistry.converters map:

      • When searching for a converter of the same class than the key (as in the ConverterRegistry.findEquals(SystemConverter) method), then there is no restriction on the key that can be given to the Map.get(K) method. The Map is "normal".
      • When searching for a converter for a pair of source and target classes (as in ConverterRegistry.find(Class, Class)), the key shall be an instance of ClassPair instance (not a subclass).
      Overrides:
      equals in class ClassPair<S,T>
      Parameters:
      other - the object to compare with this SystemConverter.
      Returns:
      true if the given object is a ClassPair or a converter of the same class than this, and both have the same source and target classes.
    • unique

      public ObjectConverter<S,T> unique()
      Returns an unique instance of this converter if one exists. If a converter already exists for the same source an target classes, then this converter is returned. Otherwise this converter is returned without being cached.
      Returns:
      the unique instance, or this if no unique instance can be found.
      See Also:
    • readResolve

      protected final Object readResolve() throws ObjectStreamException
      Returns the singleton instance on deserialization, if any. If no instance already exist in the virtual machine, we do not cache the instance (for now) for security reasons.
      Returns:
      the object to use after deserialization.
      Throws:
      ObjectStreamException - if the serialized object defines an unknown data type.
    • formatErrorMessage

      final String formatErrorMessage(S value)
      Formats an error message for a value that cannot be converted.
      Parameters:
      value - the value that cannot be converted.
      Returns:
      the error message.