com.pushtechnology.diffusion.datatype.recordv2

Interface RecordV2DataType

All Superinterfaces:

DataType<RecordV2>

public interface RecordV2DataType
extends DataType<RecordV2>

Record-based data type.

This provides the ability to handle data in Diffusion proprietary 'record' format. This format allows string data to be organized into 'records' which in turn are made up of 'fields'. Each field is a string but may be handled as either an integer or a decimal field if required.

This format is compatible with legacy RECORD topics (removed in release 6.2) and therefore can be used to migrate client applications from using such topics with minimal change to the application.

The data can either be free format or constrained by a Schema.

In free format mode, no schema is associated with the data and the data will contain zero or more records, each comprising zero or more fields. In this mode the meaning of each field is entirely up to the application and no validation will be performed by Diffusion, either in the client library, or at the server. To write free format records, a RecordV2Builder can be used to create a RecordV2 object. Such a builder may be created using the valueBuilder() method.

When using a Schema then the permitted records and fields are defined by the schema. The schema names the records and the fields within them and provides a mechanism for direct access to the fields. The schema is also used to validate the data to ensure it complies with the schema definition.

In schema mode, data can be created and updated using a MutableRecordModel which allows records and fields to be conveniently set and updated by name. A base model can be created from a schema using the Schema.createMutableModel() method. The model can at any time be used to create a new RecordV2 object. A consumer of a RecordV2 value can read it as a RecordModel by simply using the RecordV2.asModel(Schema) method to produce an immutable representation of the data. When creating the data using a MutableRecordModel then the model ensures that the data is valid and therefore there is no need for the server or the consuming client to validate the data.

Schemas can be parsed from JSON strings or more simply using a SchemaBuilder obtained using the schemaBuilder() method. A schema can be bound to a RecordV2 data type instance using the method withSchema(Schema). This method will return a new RecordV2DataType instance with the schema bound to it for validation.

A RecordV2 object can only be validated within the context of a Schema. For this reason if the validate method is called on a dataType that has no bound schema, it will always succeed.

Since:

6.0

Method Summary

Modifier and Type	Method and Description
DeltaType<RecordV2,BinaryDelta>	binaryDeltaType() Returns support for binary deltas.
Schema	parseSchema(String json) Parse a schema from a JSON string.
RecordV2	readValue(byte[] in) Parse a value from a RecordV2 format byte array.
RecordV2	readValue(byte[] in, int offset, int length) Parse a value from a RecordV2 format byte array.
SchemaBuilder	schemaBuilder() Creates a new schema builder.
RecordV2Builder	valueBuilder() Creates a new RecordV2Builder.
RecordV2DataType	withSchema(Schema schema) Bind a specific schema to a RecordV2DataType instance.

Methods inherited from interface com.pushtechnology.diffusion.datatype.DataType

canReadAs, deltaType, deltaType, getTypeName, readAs, readAs, readAs, readValue, toBytes, validate, writeValue

Method Detail

binaryDeltaType

DeltaType<RecordV2,BinaryDelta> binaryDeltaType()

Returns support for binary deltas.

Equivalent to calling deltaType(BinaryDelta.class).

Specified by:

binaryDeltaType in interface DataType<RecordV2>

Returns:

the delta type, or null if none

readValue

RecordV2 readValue(byte[] in,
                   int offset,
                   int length)
            throws IndexOutOfBoundsException

Parse a value from a RecordV2 format byte array.

RecordV2 instances can only be invalid in the context of a schema so this method does not throw InvalidDataException.

Specified by:

readValue in interface DataType<RecordV2>

Parameters:

in - the binary data. The implementation re-uses the array to avoid copying. The caller must ensure the array is not modified.

offset - the start position of the data to be read within the byte array

length - the length of the data to be read within the byte array

Throws:

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

readValue

RecordV2 readValue(byte[] in)

Parse a value from a RecordV2 format byte array.

Equivalent to readValue(in, 0, in.length).

Specified by:

readValue in interface DataType<RecordV2>

Parameters:

in - the binary data. The implementation re-uses the array to avoid copying. The caller must ensure the array is not modified.

parseSchema

Schema parseSchema(String json)
            throws SchemaParseException

Parse a schema from a JSON string.

Parameters:

json - string containing a schema definition

Returns:

schema

Throws:

SchemaParseException - if a schema parsing error occurs.

valueBuilder

RecordV2Builder valueBuilder()

Creates a new RecordV2Builder.

Such a builder may be used to generate free format RecordV2 format value that is not constrained by a Schema.

Returns:

a new records builder

schemaBuilder

SchemaBuilder schemaBuilder()

Creates a new schema builder.

Returns:

a new schema builder

withSchema

RecordV2DataType withSchema(Schema schema)

Bind a specific schema to a RecordV2DataType instance.

Parameters:

schema - to bind to the data type

Returns:

a new RecordV2DataType instance bound to a specific schema