com.pushtechnology.diffusion.datatype

Interface DataType<V>

Type Parameters:

V - value type

All Known Subinterfaces:

BinaryDataType, JSONDataType, RecordV2DataType

public interface DataType<V>

A data type is specified for a particular class (its value class). It provides methods to convert values of the value class to and from binary. Diffusion provides several implementations.

Value types should provide a string representation and define reasonable equality. The value type implementations used by Diffusion-provided data types do so.

A data type can optionally support incremental changes to values, represented by one or more types of delta. For each type of delta it supports, the data type provides an implementation of DeltaType via deltaType(String) and deltaType(Class).

Since:

5.7

Author:

DiffusionData Limited

See Also:

DeltaType

Method Summary

Modifier and Type	Method and Description
DeltaType<V,BinaryDelta>	binaryDeltaType() Returns the binary delta type for this data type, if any.
<T> boolean	canReadAs(Class<T> classOfT) Test whether this data type is compatible with classOfT.
<D> DeltaType<V,D>	deltaType(Class<D> deltaClass) Obtain a DeltaType by class.
DeltaType<V,?>	deltaType(String name) Obtain a DeltaType by name.
String	getTypeName() Returns the external type identifier.
<T> T	readAs(Class<T> classOfT, byte[] bytes) Create a value of a compatible class from binary.
<T> T	readAs(Class<T> classOfT, byte[] bytes, int offset, int length) Create a value of a compatible class from a binary.
<T> T	readAs(Class<T> classOfT, Bytes bytes) Create a value of a compatible class from binary.
V	readValue(byte[] bytes) Create a value from binary.
V	readValue(byte[] bytes, int offset, int length) Create a value from binary.
V	readValue(Bytes bytes) Create a value from binary.
Bytes	toBytes(V value) Returns the serialized form of value as a Bytes.
void	validate(V value) Check whether a value is valid.
void	writeValue(V value, OutputStream out) Serialize a value to binary.

Method Detail

getTypeName

String getTypeName()

Returns the external type identifier.

Returns:

a unique name identifying this data type

writeValue

void writeValue(V value,
                OutputStream out)
         throws IOException,
                IllegalArgumentException

Serialize a value to binary.

Throws:

IOException - if the OutputStream does

IllegalArgumentException - if the implementation does not support the provided value

toBytes

Bytes toBytes(V value)
       throws IllegalArgumentException

Returns the serialized form of value as a Bytes.

Throws:

IllegalArgumentException - if the implementation does not support the provided value

Since:

6.0

readValue

V readValue(byte[] bytes,
            int offset,
            int length)
     throws InvalidDataException,
            IndexOutOfBoundsException

Create a value from binary.

Implementations can choose not to fully validate values when they are read, but instead defer parsing until it is required. See validate(Object).

Parameters:

bytes - The binary data. The implementation may re-use the array to avoid copying so the caller must ensure the array is not modified.

offset - start of the data within bytes

length - length of the data within bytes

Throws:

InvalidDataException - If bytes does not represent a valid V. The implementation may defer validation; see validate(Object).

IndexOutOfBoundsException - if either offset or length is negative, or offset + length > bytes.length

readValue

V readValue(byte[] bytes)
     throws InvalidDataException

Create a value from binary. Equivalent to readValue(in, 0, in.length).

Parameters:

bytes - 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 bytes does not represent a valid V. The implementation may defer validation; see validate(Object).

readValue

V readValue(Bytes bytes)
     throws InvalidDataException

Create a value from binary. Equivalent to readValue(bytes.toByteArray()).

Parameters:

bytes - the binary data

Throws:

InvalidDataException - If bytes does not represent a valid V. The implementation may defer validation; see validate(Object).

validate

void validate(V value)
       throws InvalidDataException

Check whether a value is valid.

A DataType implementation is not required to check the binary data supplied to readValue(byte[], int, int) can be parsed as a value of type V if doing so is unnecessarily costly. Instead a value may simply wrap the binary data, and lazily deserialize as required. This method can be used the check the value at a later time.

Throws:

InvalidDataException - if the value is invalid

readAs

<T> T readAs(Class<T> classOfT,
             byte[] bytes,
             int offset,
             int length)
      throws InvalidDataException,
             IllegalArgumentException,
             IndexOutOfBoundsException

Create a value of a compatible class from a binary.

If valueType is incompatible with this data type, this method will throw an IllegalArgumentException. Compatibility can be tested with canReadAs(Class).

Type Parameters:

T - type of classOfT

Parameters:

classOfT - the type of the result

bytes - The binary data. The implementation may re-use the array to avoid copying so the caller must ensure the array is not modified.

offset - start of the data within bytes

length - length of the data within bytes

Throws:

InvalidDataException - If bytes does not represent a valid V, and by extension cannot be provided as a T. The implementation may defer validation; see validate(Object).

IllegalArgumentException - if classOfT is incompatible with this data type

IndexOutOfBoundsException - if either offset or length is negative, or offset + length > bytes.length

Since:

6.0

readAs

<T> T readAs(Class<T> classOfT,
             byte[] bytes)
      throws InvalidDataException,
             IllegalArgumentException

Create a value of a compatible class from binary. Equivalent to readAs(classOfT, in, 0, in.length).

Type Parameters:

T - type of classOfT

Parameters:

classOfT - the type of the result

bytes - 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 bytes does not represent a valid V, and by extension cannot be provided as a T. The implementation may defer validation; see validate(Object).

IllegalArgumentException - if classOfT is incompatible with this data type

Since:

6.0

readAs

<T> T readAs(Class<T> classOfT,
             Bytes bytes)
      throws InvalidDataException,
             IllegalArgumentException

Create a value of a compatible class from binary. Equivalent to readAs(classOfT, bytes.toByteArray()).

Type Parameters:

T - type of classOfT

Parameters:

classOfT - the type of the result

bytes - the binary data

Throws:

InvalidDataException - If bytes does not represent a valid V, and by extension cannot be provided as a T. The implementation may defer validation; see validate(Object).

IllegalArgumentException - if classOfT is incompatible with this data type

Since:

6.0

canReadAs

<T> boolean canReadAs(Class<T> classOfT)

Test whether this data type is compatible with classOfT. Compatibility with a classOfT means that any valid binary representation of a V can be read as an instance of classOfT.

Every data type should be compatible with the following:

• Class<V> – the class corresponding to implementation's value type. For a data type with a value type of X, readAs(X.class, bytes) is equivalent to readValue(bytes).
• Class<? super V> – any super type of the class corresponding to implementation's value type. Consequently every data type is compatible with Class<Object>.
• Class<Bytes>.

Compatibility is an asymmetric relationship. For example, the string data type is compatible with Class<JSON>, but the JSON data type is incompatible with Class<<String>.

In addition to compatibility with Class<V> and Class<Bytes>, the standard data types implement compatibility according to the type hierarchy shown in the following diagram:

For example, the string data type is compatible with Class<String>, Class<JSON> and Class<Bytes>, as well as super types of Class<String> such as Class<Object> and Class<CharSequence>.

Data type compatibility is used in several places in the Diffusion API:

• Value streams only receive updates from topics with compatible data types, and convert received values appropriately.
• Topics.FetchRequest.withValues(java.lang.Class<? extends T>) constrains a fetch operation to retrieve data from topics with compatible data types, and convert the values appropriately.
• TimeSeries.RangeQuery.as(java.lang.Class<T>) converts the values resulting from time series range query appropriately; the query will fail if the time series topic data type is an incompatible data type.
• Values sent using the Messaging feature will not be delivered if the recipient request stream or request handler is incompatible with the value data type.

Type Parameters:

T - type of classOfT

Parameters:

classOfT - the type to check

Returns:

true if a binary representation created by this data type can read as an instance of classOfT

Since:

6.0

deltaType

DeltaType<V,?> deltaType(String name)

Obtain a DeltaType by name.

Parameters:

name - the name, as returned by DeltaType.getName()

Returns:

the delta type

Throws:

IllegalArgumentException - if this data type does not provide a DeltaType with the name typeName

See Also:

DeltaType

deltaType

<D> DeltaType<V,D> deltaType(Class<D> deltaClass)

Obtain a DeltaType by class.

Parameters:

deltaClass - the class

Returns:

the delta type

Throws:

IllegalArgumentException - if this data type does not provide a DeltaType for deltas of class deltaClass

IllegalArgumentException - if the data type provides more than one DeltaType for deltas of class deltaClass, but none is preferred

See Also:

DeltaType

binaryDeltaType

DeltaType<V,BinaryDelta> binaryDeltaType()

Returns the binary delta type for this data type, if any.

This method behaves similarly to deltaType(BinaryDelta.class) except it returns null if this data type does not support binary deltas rather than throwing IllegalArgumentException.

Returns:

the delta type, or null if none

Since:

6.3