Package io.permazen.encoding

Class ConvertedEncoding<T,S>

java.lang.Object
io.permazen.encoding.AbstractEncoding<T>
io.permazen.encoding.ConvertedEncoding<T,S>
Type Parameters:
T - This encoder's value type
S - The delegate encoder's value type
All Implemented Interfaces:
Encoding<T>, NaturalSortAware, Serializable, Comparator<T>
Direct Known Subclasses:
Concat2Encoding, Concat3Encoding, Concat4Encoding, Concat5Encoding, StringConvertedEncoding
public class ConvertedEncoding<T,S> extends AbstractEncoding<T>
An Encoding that relies on some other Encoding, converting values to/from the other Encoding's Java type.

This class provides a convenient way to implement custom Encodings when the target values can be converted into some other form for which another Encoding (the "delegate") already exists. A Guava Converter converts values between the type supported by this encoding and the type supported by the delegate encoding. It's convert() method must throw IllegalArgumentException if an unsupported value is encountered. The Converter should be non-lossy when supported values are round-tripped.

This encoding will sort values in the same order as the delegate sorts the corresponding converted values. Null values are supported by this encoding when the delegate supports them; if so, null always converts to/from null.

This encoding has a default value when the delegate has one, namely, the conversion of the delegate's default value.

By default, the String form of a value is just the String form of its conversion. Subclasses may therefore want to override toString() and fromString().

The Converter must be Serializable in order for an instance of this class to also be Serializable.

See Also:

  • Field Details

    • delegate

      protected final Encoding<S> delegate

    • converter

      protected final Converter<T,S> converter

  • Constructor Details

    • ConvertedEncoding

      public ConvertedEncoding(EncodingId encodingId, TypeToken<T> typeToken, Encoding<S> delegate, Converter<T,S> converter, boolean sortsNaturally)
      Primary constructor.
      Parameters:
      encodingId - encoding ID for this encoding, or null to be anonymous
      typeToken - represented Java type
      delegate - delegate encoder
      converter - value converter
      sortsNaturally - true if this encoding sorts naturally, otherwise false
      Throws:
      IllegalArgumentException - if any parameter other than defaultValueSupplier is null

    • ConvertedEncoding

      public ConvertedEncoding(EncodingId encodingId, Class<T> type, Encoding<S> delegate, Converter<T,S> converter, boolean sortsNaturally)
      Convenience constructor taking Class instead of TypeToken.
      Parameters:
      encodingId - encoding ID for this encoding, or null to be anonymous
      type - represented Java type
      delegate - delegate encoder
      converter - converts between native form and String form; should be Serializable
      sortsNaturally - true if this encoding sorts naturally, otherwise false
      Throws:
      IllegalArgumentException - if any parameter other than defaultValueSupplier is null

    • ConvertedEncoding

      public ConvertedEncoding(EncodingId encodingId, Class<T> type, Encoding<S> delegate, Converter<T,S> converter)
      Convenience constructor for when the new ConvertedEncoding does not sort naturally.
      Parameters:
      encodingId - encoding ID for this encoding, or null to be anonymous
      type - represented Java type
      delegate - delegate encoder
      converter - value converter
      Throws:
      IllegalArgumentException - if any parameter is null

  • Method Details

    • read

      public T read(ByteReader reader)
      Description copied from interface: Encoding
      Read a value from the given input.
      Parameters:
      reader - byte input
      Returns:
      decoded value (possibly null)

    • write

      public void write(ByteWriter writer, T obj)
      Description copied from interface: Encoding
      Write a value to the given output.
      Parameters:
      writer - byte output
      obj - value to write (possibly null)

    • skip

      public void skip(ByteReader reader)
      Description copied from interface: Encoding
      Read and discard a byte[] encoded value from the given input.

      If the value skipped over is invalid, this method may, but is not required to, throw IllegalArgumentException.

      If the value skipped over is truncated, this method must throw IndexOutOfBoundsException.

      Parameters:
      reader - byte input

    • toString

      public String toString(T obj)
      Description copied from interface: Encoding
      Encode a non-null value as a String for later decoding by fromString().

      Each of the characters in the returned String, when decoded as 32-bit Unicode codepoints, must contain only valid XML characters (see XMLUtil.isValidChar(int)).

      Parameters:
      obj - actual value, never null
      Returns:
      string encoding of value acceptable to fromString()
      See Also:

    • fromString

      public T fromString(String string)
      Description copied from interface: Encoding
      Parse a non-null value previously encoded by toString(T).
      Parameters:
      string - non-null value previously encoded as a String by toString(T)
      Returns:
      actual value

    • sortsNaturally

      public boolean sortsNaturally()
      Description copied from interface: NaturalSortAware
      Determine if this instance sorts Java instances naturally.

      This method should return true only if all of the following are true:

      • This class also implements Comparator for some Java type T.
      • Type T has a natural ordering (i.e., T itself implements Comparable).
      • The ordering implied by this class's compare() method is identical to T's natural ordering.
      Returns:
      true if this instance orders Java values in their natural order

    • supportsNull

      public final boolean supportsNull()
      Description copied from interface: Encoding
      Determine whether this encoding supports null values.
      Returns:
      true if null is a valid value, otherwise false

    • getFixedWidth

      public final OptionalInt getFixedWidth()
      Description copied from interface: Encoding
      Get the fixed width of this encoding, if any.

      Some encodings encode every value into the same number of bytes. For such encodings, this method returns that number. For variable width encodings, this method must return empty.

      Returns:
      the number of bytes of every encoded value, or empty if the encoding length varies

    • validate

      public T validate(Object obj)
      Description copied from interface: Encoding
      Verify the given object is a valid instance of this Encoding's Java type and cast it to that type.

      Note that this method must throw IllegalArgumentException, not ClassCastException or NullPointerException, if obj does not have the correct type, or is an unsupported value - including null if null is not supported.

      This method is allowed to perform widening conversions of the object that lose no information, e.g., from Integer to Long.

      The implementation in Encoding first verifies the value is not null if this instance does not allow null values, and then attempts to cast the value using this instance's raw Java type. Subclasses should override this method to implement any other restrictions.

      Parameters:
      obj - object to validate
      Returns:
      obj cast to this encoding's type

    • compare

      public int compare(T obj1, T obj2)
      Description copied from interface: Encoding
      Order two values.

      This method must provide a total ordering of all supported Java values that is consistent with the database ordering, i.e., the unsigned lexicographical ordering of the corresponding byte[] encoded values.

      If null is a supported Java value, then the this method must accept null parameters without throwing an exception (note, this is a stronger requirement than the Comparator interface normally requires).

      Note: by convention, null values usually sort last.

    • hasPrefix0x00

      public boolean hasPrefix0x00()
      Description copied from interface: Encoding
      Determine whether any of this encoding's encoded values start with a 0x00 byte. Certain optimizations are possible when this is not the case. It is safe for this method to always return true.

      Note: changing the result of this method may result in an incompatible encoding if this encoding is wrapped in another class.

      Returns:
      true if an encoded value starting with 0x00 exists

    • hasPrefix0xff

      public boolean hasPrefix0xff()
      Description copied from interface: Encoding
      Determine whether any of this encoding's encoded values start with a 0xff byte. Certain optimizations are possible when this is not the case. It is safe for this method to always return true.

      Note: changing the result of this method may result in an incompatible encoding if this encoding is wrapped in another class.

      Returns:
      true if an encoded value starting with 0xff exists

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class AbstractEncoding<T>

    • equals

      public boolean equals(Object obj)
      Specified by:
      equals in interface Comparator<T>
      Overrides:
      equals in class AbstractEncoding<T>