DataType (Diffusion)

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

See Also:

DeltaType

Method Summary

All Methods Instance Methods Abstract Methods
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, offset, length) is equivalent to readValue(bytes, offset, length).
    - Class<? super V> – any super type of the class corresponding to implementation's value type.
      Consequently every datatype is compatible with Class<Object>.
    - Class<Bytes>.
    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> including Class<Object> and Class<CharSequence>.
    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

Interface DataType<V>

Method Summary

Method Detail

getTypeName

writeValue

toBytes

readValue

readValue

readValue

validate

readAs

readAs

readAs

canReadAs

deltaType

deltaType

binaryDeltaType