Package com.pushtechnology.diffusion.datatype

Interface DeltaType<V,D>

Type Parameters:
V - value class
D - delta class
public interface DeltaType<V,D>
Optional extension provided by DataType implementations that support incremental changes to values.

A data type can optionally support incremental changes to values, represented by one or more types of delta. A delta is the difference between two values. For large or composite values that change in small steps, it is more efficient to transmit an initial value followed by a delta for each change than to transmit a complete value for each change.

Each implementation specifies a value type and a delta type. Two values, oldValue and newValue, can be compared using diff(Object, Object) to produce a delta. The delta can be later applied to oldValue to re-create newValue using apply(Object, Object).

Delta types should provide a string representation. Equality is optional for delta types. The delta type implementations used by Diffusion-provided data types implement both.

Deferred parsing

Implementations can choose not to fully validate values and deltas when they are read, but instead defer parsing until it is required. Consequently, all methods that accept values and deltas can throw InvalidDataException.

Since:
5.7

  • Method Summary

    Modifier and Type
    Method
    Description
    V
    apply(V oldValue, D delta)
    Apply a delta to a value.
    D
    diff(V oldValue, V newValue)
    Create a delta from two values.
    String
    getName()
    Returns the external identifier for this delta type.
    boolean
    isValueCheaper(V value, D delta)
    Calculate if value is cheaper than delta.
    D
    noChange()
    Constant returned by diff(Object, Object) to indicate oldValue and newValue are equivalent.
    D
    readDelta(byte[] in)
    Create a delta from binary.
    D
    readDelta(byte[] in, int offset, int length)
    Create a delta from binary.
    D
    readDelta(Bytes in)
    Create a delta from binary.
    Bytes
    toBytes(D delta)
    Returns the serialized form of delta as a Bytes.
    void
    writeDelta(D delta, OutputStream out)
    Serialize a delta to binary.

  • Method Details

    • getName

      String getName()
      Returns the external identifier for this delta type.
      Returns:
      a unique name within the scope of the data type that provided this delta type
      See Also:

    • writeDelta

      void writeDelta(D delta, OutputStream out) throws IOException
      Serialize a delta to binary.
      Throws:
      IOException

    • toBytes

      Bytes toBytes(D delta)
      Returns the serialized form of delta as a Bytes.
      Since:
      6.0

    • readDelta

      D readDelta(byte[] in, int offset, int length) throws InvalidDataException, IndexOutOfBoundsException
      Create a delta from binary.

      Implementations can choose not to fully validate deltas when they are read, but instead defer parsing until it is required.

      Parameters:
      in - the binary data. The implementation may re-use the array to avoid copying so the caller must ensure the array is not modified.
      Throws:
      InvalidDataException - if in does not represent a valid delta
      IndexOutOfBoundsException - if either offset or length is negative, or offset + length > bytes.length

    • readDelta

      D readDelta(byte[] in) throws InvalidDataException
      Create a delta from binary. Equivalent to readDelta(in, 0, in.length).
      Throws:
      InvalidDataException

    • readDelta

      D readDelta(Bytes in) throws InvalidDataException
      Create a delta from binary. Equivalent to readValue(bytes.toByteArray()).
      Parameters:
      in - the binary data
      Throws:
      InvalidDataException - if in does not represent a valid delta
      Since:
      6.0

    • diff

      D diff(V oldValue, V newValue) throws InvalidDataException
      Create a delta from two values.

      If there are many differences between oldValue and newValue, the result might require more bytes to transmit than the new value, or be computationally expensive to apply. In this case, it is better to discard oldValue and publish newValue in its place. This can be checked using isValueCheaper(Object, Object).

      The implementation can return the special constant noChange() to indicate the oldValue and newValue are equivalent and there is no change to publish.

      Returns:
      a delta representing the difference between oldValue and newValue
      Throws:
      InvalidDataException - if oldValue or newValue is invalid

    • apply

      V apply(V oldValue, D delta) throws InvalidDataException
      Apply a delta to a value.
      Returns:
      the new value. oldValue will be returned if delta has no effect.
      Throws:
      InvalidDataException - if oldValue or delta is invalid

    • isValueCheaper

      boolean isValueCheaper(V value, D delta) throws InvalidDataException
      Calculate if value is cheaper than delta. The result is typically determined by the length of the serialized form but can also consider the complexity of the delta.
      Returns:
      true if value is considered cheaper than delta
      Throws:
      InvalidDataException - if value or delta is invalid

    • noChange

      D noChange()
      Constant returned by diff(Object, Object) to indicate oldValue and newValue are equivalent. The result is guaranteed to be equal only to itself.