Package io.permazen.encoding

Class NullSafeEncoding<T>

java.lang.Object
io.permazen.encoding.AbstractEncoding<T>
io.permazen.encoding.NullSafeEncoding<T>
Type Parameters:
T - The associated Java type
All Implemented Interfaces:
Encoding<T>, NaturalSortAware, Serializable, Comparator<T>
Direct Known Subclasses:
EnumValueEncoding, PrimitiveWrapperEncoding, ReferenceEncoding
public class NullSafeEncoding<T> extends AbstractEncoding<T>
An Encoding that wraps any other Encoding not supporting null values and adds support for null values.

This class pre-pends a 0x01 to the binary encoding of non-null values, and uses a single 0xff byte to represent null values. Therefore, null values sort last. Also, the default value is null.

This class will automatically "inline" the 0xff for null values and omit the 0x01 for non-null values if the wrapped Encoding's Encoding.hasPrefix0xff() method returns false.

See Also:

  • Field Details

    • NOT_NULL_SENTINEL

      public static final int NOT_NULL_SENTINEL
      Not null sentinel byte value. Used only when inlining is not in effect.
      See Also:

    • NULL_SENTINEL

      public static final int NULL_SENTINEL
      Null sentinel byte value.
      See Also:

    • inner

      protected final Encoding<T> inner
      The inner Encoding that this instance wraps.

  • Constructor Details

    • NullSafeEncoding

      public NullSafeEncoding(EncodingId encodingId, Encoding<T> inner)
      Constructor.
      Parameters:
      encodingId - encoding ID for this encoding, or null to be anonymous
      inner - inner type that is not null safe

  • Method Details

    • getInnerEncoding

      public Encoding<T> getInnerEncoding()
      Get the inner Encoding that this instance wraps.
      Returns:
      inner type that is not null safe

    • 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 value)
      Description copied from interface: Encoding
      Write a value to the given output.
      Parameters:
      writer - byte output
      value - 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

    • 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

    • toString

      public String toString(T value)
      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:
      value - actual value, never null
      Returns:
      string encoding of value acceptable to fromString()
      See Also:

    • convert

      public <S> T convert(Encoding<S> type, S value)
      Description copied from interface: Encoding
      Attempt to convert a value from the given Encoding into a value of this Encoding.

      For a non-null value, the implementation in Encoding first checks whether the value is already a valid value for this encoding; if so, the value is returned. Otherwise, it invokes encoding.toString(value) to convert value into a String, and then attempts to parse that string via this.fromString(); if the parse fails, an IllegalArgumentException is thrown. Note this means that any value will convert successfully to a String, as long as it doesn't contain an invalid escape sequence (see StringEncoding.toString(java.lang.String)).

      If value is null, the implementation in Encoding returns null, unless this encoding does not support null values, in which case an IllegalArgumentException is thrown.

      Permazen's built-in encodings include the following conversions:

      • Non-boolean Primitive types:
        • Convert from other non-boolean primitive types as if by the corresponding Java cast
        • Convert from boolean by converting to zero (if false) or one (if true)
      • Boolean: converts from other primitive types as if by value != 0
      • A char[] array and a String are convertible to each other
      • A char and a String of length one are convertible to each other (other Strings are not)
      • Arrays: converted by converting each array element individually (if possible)
      Type Parameters:
      S - source encoding
      Parameters:
      type - the Encoding of value
      value - the value to convert
      Returns:
      value converted to this instance's type

    • compare

      public int compare(T value1, T value2)
      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.

    • 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 boolean supportsNull()
      Always returns true.
      Returns:
      true

    • hasPrefix0xff

      public boolean hasPrefix0xff()
      Always returns true.
      Returns:
      true

    • 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

    • getFixedWidth

      public 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

    • 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>