V
- value typepublic interface DataType<V>
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)
.
DeltaType
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.
|
DeltaType<Bytes,BinaryDelta> |
serializedBinaryDeltaType()
Return the binary delta type that for serialized data of this data type,
if any.
|
Bytes |
toBytes(V value)
Returns the serialized form of
value as a Bytes . |
void |
validate(Bytes bytes)
Variant of
validate(Object) that takes the serialized form of
the value. |
void |
validate(V value)
Check whether a value is valid.
|
void |
writeValue(V value,
OutputStream out)
Serialize a value to binary.
|
String getTypeName()
void writeValue(V value, OutputStream out) throws IOException, IllegalArgumentException
IOException
- if the OutputStream doesIllegalArgumentException
- if the implementation does not support
the provided valueBytes toBytes(V value) throws IllegalArgumentException
value
as a Bytes
.IllegalArgumentException
- if the implementation does not support
the provided valueV readValue(byte[] bytes, int offset, int length) throws InvalidDataException, IndexOutOfBoundsException
Implementations can choose not to fully validate values when they are
read, but instead defer parsing until it is required. See
validate(Object)
.
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 byteslength
- length of the data within bytesInvalidDataException
- 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
V readValue(byte[] bytes) throws InvalidDataException
readValue(in, 0, in.length)
.bytes
- The binary data. The implementation may re-use the array to
avoid copying so the caller must ensure the array is not modified.InvalidDataException
- If bytes
does not represent a valid
V
. The implementation may defer validation; see
validate(Object)
.V readValue(Bytes bytes) throws InvalidDataException
readValue(bytes.toByteArray())
.bytes
- the binary dataInvalidDataException
- If bytes
does not represent a valid
V
. The implementation may defer validation; see
validate(Object)
.void validate(V value) throws InvalidDataException
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.
InvalidDataException
- if the value is invalidvoid validate(Bytes bytes) throws InvalidDataException
validate(Object)
that takes the serialized form of
the value.InvalidDataException
- if the bytes cannot be deserialized to a
valid value<T> T readAs(Class<T> classOfT, byte[] bytes, int offset, int length) throws InvalidDataException, IllegalArgumentException, IndexOutOfBoundsException
If valueType
is incompatible with this data type, this method
will throw an IllegalArgumentException. Compatibility can be tested with
canReadAs(Class)
.
T
- type of classOfT
classOfT
- the type of the resultbytes
- 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 byteslength
- length of the data within bytesInvalidDataException
- 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 typeIndexOutOfBoundsException
- if either offset
or
length
is negative, or
offset + length > bytes.length
<T> T readAs(Class<T> classOfT, byte[] bytes) throws InvalidDataException, IllegalArgumentException
readAs(classOfT, in, 0,
in.length)
.T
- type of classOfT
classOfT
- the type of the resultbytes
- The binary data. The implementation may re-use the array to
avoid copying so the caller must ensure the array is not modified.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<T> T readAs(Class<T> classOfT, Bytes bytes) throws InvalidDataException, IllegalArgumentException
readAs(classOfT, bytes.toByteArray())
.T
- type of classOfT
classOfT
- the type of the resultbytes
- the binary dataInvalidDataException
- 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<T> boolean canReadAs(Class<T> classOfT)
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.
Messaging
feature will not be delivered
if the recipient request stream
or
request handler
is incompatible with the value
data type.
T
- type of classOfT
classOfT
- the type to checkDeltaType<V,?> deltaType(String name)
DeltaType
by name.name
- the name, as returned by DeltaType.getName()
IllegalArgumentException
- if this data type does not provide a
DeltaType
with the name typeName
DeltaType
<D> DeltaType<V,D> deltaType(Class<D> deltaClass)
DeltaType
by class.deltaClass
- the classIllegalArgumentException
- 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 preferredDeltaType
DeltaType<V,BinaryDelta> binaryDeltaType()
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
.
DeltaType<Bytes,BinaryDelta> serializedBinaryDeltaType()
Copyright © 2024 DiffusionData Ltd. All Rights Reserved.