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 and 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 Detail

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:

DataType.deltaType(String)

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.