Interface IDeltaType

The optional extension provided by IDataType implementations that support incremental changes to values.

Namespace: PushTechnology.ClientInterface.Data

Assembly: Diffusion.Client.dll

Syntax

public interface IDeltaType

Remarks

Each implementation specifies a value type and a delta type. Two values, oldValue and newValue, can be compared to produce a delta using Diff(Object, Object). The delta can be separately applied to oldValue to create newValue using Apply(Object, Object).

Delta types should provide a System.Object.ToString(). System.Object.Equals(System.Object) is optional for delta types.

Deferred parsing

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

Since 5.8

Properties

Name

Returns the external identifier for this delta type.

Declaration

string Name { get; }

Property Value

Type	Description
System.String	The external identifier for this delta type.

NoChange

Returns a constant that indicates no changes between values.

Declaration

object NoChange { get; }

Property Value

Type	Description
System.Object	A constant that indicates no changes between values.

Remarks

This constant is returned by Diff(Object, Object) to indicate oldValue and newValue are equivalent. The result is guaranteed to be equal only to itself.

Methods

Apply(Object, Object)

Applies a delta to a value.

Declaration

object Apply(object oldValue, object delta)

Parameters

Type	Name	Description
System.Object	oldValue	The old value object.
System.Object	delta	The delta object to apply to the old value object.

Returns

Type	Description
System.Object	The new value object. The old value object will be returned if the delta had no effect.

Diff(Object, Object)

Creates a delta from two values.

Declaration

object Diff(object oldValue, object newValue)

Parameters

Type	Name	Description
System.Object	oldValue	The old value object.
System.Object	newValue	The new value object.

Returns

Type	Description
System.Object	The delta representing the difference between oldValue and newValue.

Remarks

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.

IsValueCheaper(Object, Object)

Calculates 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.

Declaration

bool IsValueCheaper(object value, object delta)

Parameters

Type	Name	Description
System.Object	value	The value object.
System.Object	delta	The delta object.

Returns

Type	Description
System.Boolean	True if value is considered cheaper than delta. Otherwise false.

ReadDelta(IBytes)

Creates a delta from IBytes.

Declaration

object ReadDelta(IBytes input)

Parameters

Type	Name	Description
IBytes	input	The binary data.

Returns

Type	Description
System.Object	The delta object.

Remarks

This is equivalent to calling ReadDelta(Byte[]) with the result of ToByteArray() as argument.

Since 6.0.

ReadDelta(Byte[])

Creates a delta from a binary segment.

Declaration

object ReadDelta(byte[] input)

Parameters

Type	Name	Description
System.Byte[]	input	The binary data. The implementation may re-use the array to avoid copying. The caller must ensure the array is not modified.

Returns

Type	Description
System.Object	The delta object.

Remarks

This is equivalent to ReadDelta(input,0,input.Length).

ReadDelta(Byte[], Int32, Int32)

Creates a delta from a binary segment.

Declaration

object ReadDelta(byte[] input, int offset, int length)

Parameters

Type	Name	Description
System.Byte[]	input	The binary data. The implementation may re-use the array to avoid copying. The caller must ensure the array is not modified.
System.Int32	offset	The starting index of the segment.
System.Int32	length	The length of the segment.

Returns

Type	Description
System.Object	The delta object.

ToBytes(Object)

Returns the serialized form of the given delta as IBytes.

Declaration

IBytes ToBytes(object delta)

Parameters

Type	Name	Description
System.Object	delta	The delta object.

Returns

Type	Description
IBytes	The delta as IBytes.

Remarks

Since 6.0.

WriteDelta(Object, Stream)

Serializes a delta to binary.

Declaration

void WriteDelta(object delta, Stream outputStream)

Parameters

Type	Name	Description
System.Object	delta	The delta object.
System.IO.Stream	outputStream	The output stream.