@Public public final class Record extends Object implements Value, CopyableValue<Record>
For efficient data exchange, a record that is read from any source holds its data in
serialized binary form. Fields are deserialized lazily upon first access. Modified fields are
cached and the modifications are incorporated into the binary representation upon the next
serialization or any explicit call to the updateBinaryRepresenation()
method.
IMPORTANT NOTE: Records must be used as mutable objects and be reused across user function calls in order to achieve performance. The record is a heavy-weight object, designed to minimize calls to the individual fields' serialization and deserialization methods. It holds quite a bit of state consumes a comparably large amount of memory (> 200 bytes in a 64 bit JVM) due to several pointers and arrays.
This class is NOT thread-safe!
Constructor and Description |
---|
Record()
Required nullary constructor for instantiation by serialization logic.
|
Record(int numFields)
Creates a new record, containing the given number of fields.
|
Record(Value value)
Creates a new record containing only a single field, which is the given value.
|
Record(Value val1,
Value val2)
Creates a new record containing exactly two fields, which are the given values.
|
Modifier and Type | Method and Description |
---|---|
void |
addField(Value value) |
void |
clear()
Clears the record.
|
void |
concatenate(Record record) |
Record |
copy()
Performs a deep copy of this object into a new instance.
|
void |
copy(DataInputView source,
DataOutputView target)
Copies the next serialized instance from
source to target . |
void |
copyFrom(Record source,
int[] sourcePositions,
int[] targetPositions)
Bin-copies fields from a source record to this record.
|
void |
copyTo(Record target)
Performs a deep copy of this object into the
target instance. |
Record |
createCopy()
Creates an exact copy of this record.
|
void |
deserialize(DataInputView source) |
boolean |
equalsFields(int[] positions,
Value[] searchValues,
Value[] deserializationHolders)
Checks the values of this record and a given list of values at specified positions for
equality.
|
int |
getBinaryLength()
Gets the length of the data type when it is serialized, in bytes.
|
<T extends Value> |
getField(int fieldNum,
Class<T> type)
Gets the field at the given position from the record.
|
<T extends Value> |
getField(int fieldNum,
T target)
Gets the field at the given position.
|
boolean |
getFieldInto(int fieldNum,
Value target)
Gets the field at the given position.
|
boolean |
getFieldsInto(int[] positions,
Value[] targets)
Gets the fields at the given positions into an array.
|
void |
getFieldsIntoCheckingNull(int[] positions,
Value[] targets)
Gets the fields at the given positions into an array.
|
int |
getNumFields()
Gets the number of fields currently in the record.
|
boolean |
isNull(int fieldNum) |
void |
makeSpace(int numFields)
Reserves space for at least the given number of fields in the internal arrays.
|
void |
read(DataInputView in)
Reads the object's internal data from the given data input view.
|
void |
removeField(int fieldNum)
Removes the field at the given position.
|
long |
serialize(DataOutputView target)
Writes this record to the given output view.
|
void |
setField(int fieldNum,
Value value)
Sets the field at the given position to the given value.
|
void |
setNull(int field)
Sets the field at the given position to
null . |
void |
setNull(long mask)
Sets the fields to
null using the given bit mask. |
void |
setNull(long[] mask)
Sets the fields to
null using the given bit mask. |
void |
setNumFields(int numFields)
Sets the number of fields in the record.
|
void |
unionFields(Record other)
Unions the other record's fields with this records fields.
|
void |
updateBinaryRepresenation()
Updates the binary representation of the data, such that it reflects the state of the
currently stored fields.
|
void |
write(DataOutputView out)
Writes the object's internal data to the given data output view.
|
public Record()
public Record(Value value)
value
- The value for the single field of the record.public Record(Value val1, Value val2)
val1
- The value for the first field.val2
- The value for the second field.public Record(int numFields)
numFields
- The number of fields for the record.public int getNumFields()
public void setNumFields(int numFields)
numFields
- The new number of fields.public void makeSpace(int numFields)
numFields
- The number of fields to reserve space for.public <T extends Value> T getField(int fieldNum, Class<T> type)
T
- The type of the field.fieldNum
- The logical position of the field.type
- The type of the field as a class. This class is used to instantiate a value
object, if none had previously been instantiated.IndexOutOfBoundsException
- Thrown, if the field number is negative or larger or equal
to the number of fields in this record.public <T extends Value> T getField(int fieldNum, T target)
In all cases, the returned value contains the correct data (or is correctly null).
fieldNum
- The position of the field.target
- The value to deserialize the field into.public boolean getFieldInto(int fieldNum, Value target)
fieldNum
- The position of the field.target
- The value to deserialize the field into.public boolean getFieldsInto(int[] positions, Value[] targets)
positions
- The positions of the fields to get.targets
- The values into which the content of the fields is put.public void getFieldsIntoCheckingNull(int[] positions, Value[] targets)
positions
- The positions of the fields to get.targets
- The values into which the content of the fields is put.NullKeyFieldException
- in case of a failing field read.public void setField(int fieldNum, Value value)
The value is kept as a reference in the record until the binary representation is synchronized. Until that point, all modifications to the value's object will change the value inside the record.
The binary representation is synchronized the latest when the record is emitted. It may be triggered manually at an earlier point, but it is generally not necessary and advisable. Because the synchronization triggers the serialization on all modified values, it may be an expensive operation.
fieldNum
- The position of the field, starting at zero.value
- The new value.public void addField(Value value)
value
- public void removeField(int fieldNum)
This method should be used carefully. Be aware that as the field is actually removed from the record, the total number of fields is modified, and all fields to the right of the field removed shift one position to the left.
fieldNum
- The position of the field to be removed, starting at zero.IndexOutOfBoundsException
- Thrown, when the position is not between 0 (inclusive) and
the number of fields (exclusive).public final boolean isNull(int fieldNum)
public void setNull(int field)
null
.field
- The field index.IndexOutOfBoundsException
- Thrown, when the position is not between 0 (inclusive) and
the number of fields (exclusive).public void setNull(long mask)
null
using the given bit mask. The bits correspond to the
individual columns: (1 == nullify, 0 == keep)
.mask
- Bit mask, where the i-th least significant bit represents the i-th field in the
record.public void setNull(long[] mask)
null
using the given bit mask. The bits correspond to the
individual columns: (1 == nullify, 0 == keep)
.mask
- Bit mask, where the i-th least significant bit in the n-th bit mask represents
the (n*64) + i
-th field in the record.public void clear()
public void concatenate(Record record)
public void unionFields(Record other)
B
as the parameter, this record A
will contain at field
i
:
i
from record A
, if that field is within record A
's number of fields and is not null.
i
from record B
, if that field is within record B
's number of fields.
A
and
B
have field i
set to null, this record will have
null at that position.other
- The records whose fields to union with this record's fields.public void copyTo(Record target)
CopyableValue
target
instance.copyTo
in interface CopyableValue<Record>
target
- public int getBinaryLength()
CopyableValue
getBinaryLength
in interface CopyableValue<Record>
-1
, if variable length.public Record copy()
CopyableValue
This method is useful for generic user-defined functions to clone a CopyableValue
when storing multiple objects. With object reuse a deep copy must be created and type erasure
prevents calling new.
copy
in interface CopyableValue<Record>
public void copy(DataInputView source, DataOutputView target) throws IOException
CopyableValue
source
to target
.
This method is equivalent to calling IOReadableWritable.read(DataInputView)
followed by IOReadableWritable.write(DataOutputView)
but does not require
intermediate deserialization.
copy
in interface CopyableValue<Record>
source
- Data source for serialized instance.target
- Data target for serialized instance.IOException
IOReadableWritable
public Record createCopy()
public void copyFrom(Record source, int[] sourcePositions, int[] targetPositions)
If the source field is in a modified state, no binary representation will exist yet. In
that case, this method is equivalent to setField(..., source.getField(..., <class>))
.
In particular, if setValue is called on the source field Value instance, that change will
propagate to this record.
If the source field has already been serialized, then the binary representation will be copied. Further modifications to the source field will not be observable via this record, but attempting to read the field from this record will cause it to be deserialized.
Finally, bin-copying a source field requires calling updateBinaryRepresentation on this instance in order to reserve space in the binaryData array. If none of the source fields are actually bin-copied, then updateBinaryRepresentation won't be called.
source
- sourcePositions
- targetPositions
- public final boolean equalsFields(int[] positions, Value[] searchValues, Value[] deserializationHolders)
positions
- The positions of the values to check for equality.searchValues
- The values against which the values of this record are compared.deserializationHolders
- An array to hold the deserialized values of this record.public void updateBinaryRepresenation()
public void write(DataOutputView out) throws IOException
IOReadableWritable
write
in interface IOReadableWritable
out
- the output view to receive the data.IOException
- thrown if any error occurs while writing to the output streampublic void read(DataInputView in) throws IOException
IOReadableWritable
read
in interface IOReadableWritable
in
- the input view to read the data fromIOException
- thrown if any error occurs while reading from the input streampublic long serialize(DataOutputView target) throws IOException
IOReadableWritable.write(org.apache.flink.core.memory.DataOutputView)
,
but it returns the number of bytes written.target
- The view to write the record to.IOException
- Thrown, if an error occurred in the view during writing.public void deserialize(DataInputView source) throws IOException
source
- IOException
Copyright © 2014–2024 The Apache Software Foundation. All rights reserved.