Package com.northconcepts.datapipeline.core

Class Record

java.lang.Object
com.northconcepts.datapipeline.core.Node
com.northconcepts.datapipeline.core.ValueNode<Record>
com.northconcepts.datapipeline.core.Record
All Implemented Interfaces:
RecordContainer, Session, Serializable, Cloneable, Comparable<ValueNode<Record>>, Iterable<Field>
public final class Record extends ValueNode<Record> implements RecordContainer, Cloneable, Serializable, Iterable<Field>
Record holds persistent data in key-value fields as it flows through the pipeline. Values in a field can be:
  • Single values (boolean, date, string, etc. -- see FieldType)
  • Records
  • Array of single values, records, and arrays
See Also:

  • Constructor Details

    • Record

      public Record(Record record)
      Creates a new record by copying the fields from another.
      Parameters:
      record - the record to copy from.

    • Record

      public Record()
      Creates a new empty record with no fields.

    • Record

      public Record(String... fieldNames)
      Creates a new record with the specified field names.
      Parameters:
      fieldNames -

    • Record

      public Record(FieldList fieldNames)
      Creates a new record with the specified field names.
      Parameters:
      fieldNames -

  • Method Details

    • getRecord

      public Record getRecord()
      Returns the Record associated with this container.
      Specified by:
      getRecord in interface RecordContainer
      Returns:
      this record

    • iterator

      public Iterator<Field> iterator()
      Returns an iterator over the fields in this record.
      Specified by:
      iterator in interface Iterable<Field>

    • getType

      public FieldType getType()
      Returns the FieldType of this value node. For SingleValue, this is the type of the contained value. For ArrayValue, the type is derived from its elements or its default type. For Record, the type is always FieldType.RECORD.
      Specified by:
      getType in class ValueNode<Record>
      Returns:
      FieldType.RECORD

    • getNodeType

      public Node.NodeType getNodeType()
      Returns the concrete Node.NodeType of this node.
      Specified by:
      getNodeType in class Node
      Returns:
      Node.NodeType.RECORD

    • hasChildNodes

      public boolean hasChildNodes()
      Returns true if this node contains any sub nodes.
      Specified by:
      hasChildNodes in class Node

    • hasChildRecords

      public boolean hasChildRecords()
      Returns true if this node contains any descendant, record nodes.
      Specified by:
      hasChildRecords in class Node

    • removeChildNode

      protected void removeChildNode(Node child)
      Description copied from class: Node
      Detaches the given child (matched by identity) from this node; called when the child is moved to another parent.
      Specified by:
      removeChildNode in class Node

    • isRecord

      public boolean isRecord()
      Returns true if this value node is a Record.

      Always returns true.

      Overrides:
      isRecord in class ValueNode<Record>
      Returns:
      true if this is a record, false otherwise
      See Also:

    • hasArrayFields

      public boolean hasArrayFields()
      Returns true if any field in this record contains an ArrayValue.
      Returns:
      true if at least one field is an array

    • getValue

      public Record getValue()
      Returns the underlying value held by this node. For SingleValue, this is the wrapped object. For ArrayValue, this returns the array itself. For Record, this returns the record itself.

      Returns this Record instance (records are self-referencing values).

      Specified by:
      getValue in class ValueNode<Record>
      Returns:
      the value, or null if this node holds a null value

    • getValueAsString

      public String getValueAsString()
      Returns a string representation of the value held by this node.
      Specified by:
      getValueAsString in class ValueNode<Record>
      Returns:
      the value as a string, or "null" if the value is null

    • copyFrom

      public Record copyFrom(Record sourceRecord, Node.DuplicateNodeAction fieldExistsAction)
      Copy all the fields and child fields from the specified record into this one.
      Parameters:
      sourceRecord - the record to copy from.
      fieldExistsAction - the action to take if a field with the same name already exists in this record.
      Returns:
      this record.

    • copyFrom

      public Record copyFrom(Record record, boolean overwriteFields)
      Copy all the fields and child fields from the specified record into this one.
      Parameters:
      record - the record to copy from.
      overwriteFields - indicates if existing target fields should be replaced (Node.DuplicateNodeAction.OVERWRITE) or a new unique field created (Node.DuplicateNodeAction.APPEND).
      Returns:
      this record.

    • copyFrom

      public Record copyFrom(Record record)
      Copy all the fields and child fields from the specified record into this one, creating new unique fields when target fields with the same name already exists (Node.DuplicateNodeAction.APPEND).
      Parameters:
      record - the record to copy from.
      Returns:
      this record.

    • clone

      public Record clone()
      Description copied from class: ValueNode
      Returns a deep copy of this value node.
      Specified by:
      clone in class ValueNode<Record>
      Returns:
      a clone of this value node

    • getState

      public Record.State getState()
      Returns the current lifecycle state of this record.
      Returns:
      the record state, never null

    • isDeleted

      public boolean isDeleted()
      Returns true if this record has been marked for deletion.
      Returns:
      true if the state is Record.State.DELETED

    • setAlive

      public void setAlive()
      Resets this record's state to Record.State.ALIVE.

    • delete

      public void delete()
      Marks this record as Record.State.DELETED. Deleted records are typically filtered out by the pipeline and not written to the output.

    • getCreatedOn

      public long getCreatedOn()
      Returns the time in milliseconds when this record was created.

    • getField

      public Field getField(int index)
      Returns the field at the specified index (for zero or positive indexes) or from the end of the list (for negative indexes by adding index to the size of the list).

    • getField

      public Field getField(int index, boolean createField)
      Returns the field at the specified index, creating new fields as needed if createField is true.
      Parameters:
      index - the field index
      createField - if true, empty fields are appended until the index is valid
      Returns:
      the field at the specified index

    • getField

      public Field getField(String fieldName)
      Returns the first field with the given name or throws an exception if none are found. Special characters are not parsed and instead treated as part of the field name.

    • getFieldOrNull

      public Field getFieldOrNull(String fieldName)
      Returns the first field with the given name or null if none are found. Special characters are not parsed and instead treated as part of the field name.

    • getField

      public Field getField(String fieldName, boolean createField)
      Returns the first field with the given name. If createField is true and no matching field exists, a new field with the specified name is created and returned.
      Parameters:
      fieldName - the field name to look up
      createField - if true, create the field when not found
      Returns:
      the matching or newly created field
      Throws:
      DataException - if createField is false and no matching field exists

    • getField

      public Field getField(FieldPath path)
      Returns the field at the specified FieldPath.
      Parameters:
      path - the path expression identifying the field
      Returns:
      the field
      Throws:
      DataException - if the path does not resolve to a field

    • getField

      public Field getField(FieldPath path, boolean createField)
      Returns the field at the specified FieldPath, optionally creating intermediate fields.
      Parameters:
      path - the path expression identifying the field
      createField - if true, intermediate fields and records are created as needed
      Returns:
      the field
      Throws:
      DataException - if the path does not resolve and createField is false

    • getField

      public Field getField(FieldPath path, boolean createField, boolean throwException)
      Returns the field at the specified FieldPath, optionally creating intermediate fields.
      Parameters:
      path - the path expression identifying the field
      createField - if true, intermediate fields and records are created as needed
      throwException - if true, an exception is thrown when the path does not resolve
      Returns:
      the field, or null if not found and throwException is false

    • getValue

      public ValueNode<?> getValue(FieldPath path)
      Returns the value node at the specified FieldPath.
      Parameters:
      path - the path expression
      Returns:
      the value node
      Throws:
      DataException - if the path does not resolve

    • getValue

      public ValueNode<?> getValue(FieldPath path, boolean createField)
      Returns the value node at the specified FieldPath, optionally creating intermediate fields.
      Parameters:
      path - the path expression
      createField - if true, intermediate fields and records are created as needed
      Returns:
      the value node
      Throws:
      DataException - if the path does not resolve and creation is not requested

    • getValue

      public ValueNode<?> getValue(FieldPath path, boolean createField, boolean throwException)
      Returns the value node at the specified FieldPath, optionally creating intermediate fields.
      Parameters:
      path - the path expression identifying the field
      createField - if true, intermediate fields and records are created as needed
      throwException - if true, an exception is thrown when the path does not resolve
      Returns:
      the value node, or null if not found and throwException is false

    • getSingleValue

      public SingleValue getSingleValue(FieldPath path, boolean createField, boolean throwException)
      Returns the SingleValue at the specified FieldPath, optionally creating intermediate fields.
      Parameters:
      path - the path expression
      createField - if true, intermediate fields and records are created as needed
      throwException - if true, an exception is thrown when the path does not resolve
      Returns:
      the single value, or null if not found and throwException is false

    • getField

      public Field getField(FieldList fieldNamePath, boolean createField)
      Retrieves a nested child field. If createField is true, all missing intermediate records will be created, otherwise an exception will be thrown. This method will fail if an intermediate field has a non-record, non-null value.

    • setField

      public Record setField(String fieldName, Object value)
      Sets the value of the field with the given name, creating the field if necessary.
      Parameters:
      fieldName - the field name
      value - the value to set
      Returns:
      this record for method chaining

    • setField

      public Record setField(FieldPath fieldPath, boolean createField, boolean throwException, Object value)
      Sets the value at the specified FieldPath.
      Parameters:
      fieldPath - the path expression
      createField - if true, intermediate fields and records are created as needed
      throwException - if true, an exception is thrown when the path does not resolve
      value - the value to set
      Returns:
      this record for method chaining

    • setField

      public Record setField(FieldPath fieldPath, Object value)
      Sets the value at the specified FieldPath, creating intermediate fields as needed.
      Parameters:
      fieldPath - the path expression
      value - the value to set
      Returns:
      this record for method chaining

    • setFieldNull

      public Record setFieldNull(String fieldName, FieldType type)
      Sets the field with the given name to a typed null value, creating the field if necessary.
      Parameters:
      fieldName - the field name
      type - the field type of the null value
      Returns:
      this record for method chaining

    • setFieldNull

      public Record setFieldNull(FieldPath fieldPath, FieldType type)
      Sets the field at the specified FieldPath to a typed null value, creating intermediate fields as needed.
      Parameters:
      fieldPath - the path expression
      type - the field type of the null value
      Returns:
      this record for method chaining

    • addField

      public Field addField(String fieldName, Object value, boolean arrayField)
      Adds a new field with the specified value to this record. If a field with this name already exists, arrayField determines if the existing field should be promoted to an array and the new value added to it, otherwise, a unique name is created for the new value by appending a number to the name starting with 1 until an unused name is found.

    • addField

      public Field addField(String fieldName, Object value)
      Adds a new field with the specified value to this record. If a field with this name already exists, this method searches for an unused name by appending an numeric offset starting with 1.

    • getFieldCount

      public int getFieldCount()
      Returns the number of fields in this record.
      Returns:
      the field count

    • addField

      public Field addField()
      Adds a new, unnamed field to this record and returns it for further configuration.
      Returns:
      the newly created field

    • getFields

      public ArrayList<Field> getFields()
      Returns a new collection of the fields in this record. The collection is not connected to this record and can be freely modified, however, the fields are the same instances in this record.

    • forEach

      public void forEach(Consumer<? super Field> consumer)
      Performs the given action for each field in this list.
      Specified by:
      forEach in interface Iterable<Field>

    • stream

      public Stream<Field> stream()
      Returns a sequential Stream of the fields in this record.

    • parallelStream

      public Stream<Field> parallelStream()
      Returns a parallel Stream of the fields in this record.

    • getFieldNames

      public List<String> getFieldNames()
      Returns a list of the field names in this record in order.
      Returns:
      the field names

    • getFieldNameList

      public FieldList getFieldNameList()
      Returns a FieldList containing the names of all fields in this record.
      Returns:
      the field name list

    • getFieldTypes

      public List<FieldType> getFieldTypes(FieldList fieldList)
      Returns the field types for the fields matching the given FieldList, or all fields if the list is null or empty.
      Parameters:
      fieldList - the fields to include, or null for all
      Returns:
      the list of field types

    • getFieldTypes

      public List<FieldType> getFieldTypes()
      Returns the field types for all fields in this record.
      Returns:
      the list of field types

    • getValues

      public List<?> getValues(FieldList fieldList)
      Returns the field values in this record as a List for the fields matching the supplied FieldList. This method does not traverse nested records and nested arrays.

    • getValues

      public List<?> getValues()
      Returns all the field values in this record as a List. This method does not traverse nested records and nested arrays.

    • getValuesAsArray

      public ArrayValue getValuesAsArray()
      Returns all the field values in this record as an ArrayValue. This method does not traverse nested records and nested arrays.

    • setParentNode

      protected Record setParentNode(Node parentNode)
      Description copied from class: ValueNode
      Sets the parent node of this value node. If a parent was previously assigned and differs from the new parent, this node is first removed from the old parent. Circular references are detected and will cause a DataException.
      Overrides:
      setParentNode in class ValueNode<Record>
      Parameters:
      parentNode - the new parent node, or null to detach from the current parent
      Returns:
      this value node

    • compareTo

      public int compareTo(ValueNode<Record> o)
      Compares this record to another value node by delegating to compareTo(Record).
      Specified by:
      compareTo in interface Comparable<ValueNode<Record>>
      Parameters:
      o - the other value node
      Returns:
      a negative integer, zero, or a positive integer

    • compareTo

      public int compareTo(Record o)
      Compares this record to another using the default RecordComparator.
      Parameters:
      o - the other record
      Returns:
      a negative integer, zero, or a positive integer

    • compareTo

      public int compareTo(Record o, RecordComparator comparator)
      Compares this record to another using the specified RecordComparator, or the default if null.
      Parameters:
      o - the other record
      comparator - the comparator to use, or null for the default
      Returns:
      a negative integer, zero, or a positive integer

    • equals

      public boolean equals(Object o)
      Indicates whether the given object is a Record with equal fields.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare with
      Returns:
      true if the objects are equal

    • equals

      public boolean equals(Record o, RecordComparator comparator)
      Indicates whether this record is equal to another using the specified RecordComparator.
      Parameters:
      o - the other record
      comparator - the comparator to use, or null for the default
      Returns:
      true if the records are equal

    • hashCode

      public int hashCode()
      Returns a hash code based on all fields in this record.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code

    • hashCode

      public int hashCode(FieldList fieldList)
      Returns a hash code based on the fields matching the given FieldList, or all fields if null.
      Parameters:
      fieldList - the fields to include in the hash, or null for all
      Returns:
      the hash code

    • indexOfField

      protected int indexOfField(Field field)
      Returns the 0-based index of this exact field instance (compared by identity) or -1 if it is not in this record.

    • indexOfField

      public int indexOfField(String fieldName, boolean throwExceptionOnFailure)
      Returns the index of the first field with the given name, or -1 if not found.
      Parameters:
      fieldName - the field name to search for
      throwExceptionOnFailure - if true, throws a DataException when the field is not found
      Returns:
      the field index, or -1 if not found and throwExceptionOnFailure is false
      Throws:
      DataException - if the field is not found and throwExceptionOnFailure is true

    • containsField

      public boolean containsField(String fieldName)
      Returns true if this record contains a field with the given name.
      Parameters:
      fieldName - the field name to check
      Returns:
      true if the field exists

    • containsField

      public boolean containsField(FieldPath path)
      Indicates if this record contains a matching field for the specified path. This method will return false if the path matches an array value (for example city[2] or customer.address[0].city[2]) instead of a field.

    • containsNonNullField

      public boolean containsNonNullField(FieldPath path)
      Indicates if this record contains a field at the specified path that is not null.

    • containsNonNullField

      public boolean containsNonNullField(String fieldPathExpression)
      Indicates if this record contains a field at the specified path with a non-null value. See FieldPath for supported field name expressions.

    • containsField

      public boolean containsField(FieldList fieldNamePath)
      Returns true if all fields and sub fields in a nested path exists.

    • contains

      @Deprecated public boolean contains(FieldPath path)
      Deprecated.
      Indicates if this record contains a matching field or value for the specified path. Use containsValue(FieldPath) instead.

    • containsNonNull

      @Deprecated public boolean containsNonNull(FieldPath path)
      Deprecated.
      Indicates if this record contains a field or value at the specified path where the value is not null. Use containsNonNullValue(FieldPath) instead.

    • containsValue

      public boolean containsValue(FieldPath path)
      Indicates if this record contains a matching field or value for the specified path.

    • containsNonNullValue

      public boolean containsNonNullValue(FieldPath path)
      Indicates if this record contains a field or value at the specified path where the value is not null.

    • removeField

      protected boolean removeField(Field field)
      Removes this exact field instance (compared by identity); returns false if it is not in this record.

    • removeField

      public Field removeField(int index)
      Removes and returns the field at the specified index.
      Parameters:
      index - the index of the field to remove
      Returns:
      the removed field
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • removeField

      public Field removeField(String columnName)
      Removes and returns the field with the specified name.
      Parameters:
      columnName - the name of the field to remove
      Returns:
      the removed field
      Throws:
      DataException - if no field with the given name exists

    • removeField

      public Field removeField(FieldList fieldNamePath)
      Removes a sub-field matching the specified path.

    • removeField

      public Field removeField(FieldPath fieldPath)
      Deletes the field at the specified path or throws an exception if it doesn't exist.
      Parameters:
      fieldPath -
      Returns:
      the removed field

    • moveField

      public void moveField(int oldIndex, int newIndex)
      Moves a field from one position to another within this record.
      Parameters:
      oldIndex - the current index of the field
      newIndex - the desired new index

    • moveField

      public void moveField(String fieldName, int newIndex)
      Moves the field with the specified name to a new position within this record.
      Parameters:
      fieldName - the name of the field to move
      newIndex - the desired new index

    • moveFieldBefore

      public void moveFieldBefore(String fieldName, String beforeFieldName)
      Moves the named field to the position immediately before another named field.
      Parameters:
      fieldName - the name of the field to move
      beforeFieldName - the name of the field to move before

    • moveFieldAfter

      public void moveFieldAfter(String fieldName, String afterFieldName)
      Moves the named field to the position immediately after another named field.
      Parameters:
      fieldName - the name of the field to move
      afterFieldName - the name of the field to move after

    • moveFieldBefore

      public void moveFieldBefore(FieldPath fieldPath, FieldPath beforeFieldPath)
      Moves the field at the specified path to the position immediately before another field path.
      Parameters:
      fieldPath - the path of the field to move
      beforeFieldPath - the path of the field to move before

    • moveFieldAfter

      public void moveFieldAfter(FieldPath fieldPath, FieldPath afterFieldPath)
      Moves the field at the specified path to the position immediately after another field path.
      Parameters:
      fieldPath - the path of the field to move
      afterFieldPath - the path of the field to move after

    • selectFields

      public Record selectFields(FieldList fields)
      Retains only the fields specified in the given list, removing all others and reordering to match the list's order. Equivalent to calling selectFields(fields, false).
      Parameters:
      fields - the fields to retain
      Returns:
      this record for method chaining

    • selectFields

      public Record selectFields(FieldList fields, boolean lenient)
      Retains only the fields specified in the given list, removing all others. If lenient is true, missing fields are silently ignored; otherwise an exception is thrown.
      Parameters:
      fields - the fields to retain
      lenient - if true, silently skip fields not found in this record
      Returns:
      this record for method chaining

    • excludeFields

      public Record excludeFields(FieldList fields)
      Removes all fields whose names appear in the given list.
      Parameters:
      fields - the field names to remove
      Returns:
      this record for method chaining

    • excludeFields

      public Record excludeFields(Set<String> fields)
      Removes all fields whose names appear in the given set.
      Parameters:
      fields - the field names to remove
      Returns:
      this record for method chaining

    • excludeFields

      public Record excludeFields(Iterable<FieldPath> fieldPaths)
      Removes all fields matching the given FieldPath iterable that exist in this record.
      Parameters:
      fieldPaths - the field paths to remove
      Returns:
      this record for method chaining

    • removeFields

      public Record removeFields(Collection<FieldPath> fieldPaths)
      Removes all fields matching the given collection of FieldPath expressions.
      Parameters:
      fieldPaths - the field paths to remove
      Returns:
      this record for method chaining
      Throws:
      DataException - if a path does not resolve

    • getSizeInBytesOfFieldNames

      public long getSizeInBytesOfFieldNames()
      Returns the estimated total size of all field names in bytes, including object overhead.
      Returns:
      the size in bytes

    • getSizeInBytes

      public long getSizeInBytes()
      Returns the estimated size of this value node in bytes, including object overhead.
      Specified by:
      getSizeInBytes in class ValueNode<Record>
      Returns:
      the size in bytes

    • toString

      public String toString()
      Returns a human-readable string representation of this node and its contents.
      Specified by:
      toString in class Node
      Returns:
      a string representation of this node

    • evaluate

      public <T> T evaluate(String expressionString)
      Evaluates the given expression string against this record and returns the result.
      Type Parameters:
      T - the expected result type
      Parameters:
      expressionString - the expression to evaluate
      Returns:
      the result of the expression

    • toJson

      public String toJson()
      Serializes this record to a JSON string.
      Specified by:
      toJson in class ValueNode<Record>
      Returns:
      the JSON representation

    • toJson

      public static String toJson(ValueNode<?> recordOrArray)
      Serializes the given record or array to a JSON string.
      Parameters:
      recordOrArray - the value node to serialize
      Returns:
      the JSON representation

    • toJson

      public static void toJson(ValueNode<?> recordOrArray, Writer writer)
      Serializes the given record or array as JSON to the specified writer.
      Parameters:
      recordOrArray - the value node to serialize
      writer - the target writer

    • toJson

      public String toJson(boolean pretty)
      Serializes this record to a JSON string, optionally pretty-printed.
      Parameters:
      pretty - if true, the output is indented for readability
      Returns:
      the JSON representation

    • toJson

      public static String toJson(ValueNode<?> recordOrArray, boolean pretty)
      Serializes the given record or array to a JSON string, optionally pretty-printed.
      Parameters:
      recordOrArray - the value node to serialize
      pretty - if true, the output is indented for readability
      Returns:
      the JSON representation

    • toJson

      public static void toJson(ValueNode<?> recordOrArray, Writer writer, boolean pretty)
      Serializes the given record or array as JSON to the specified writer, optionally pretty-printed.
      Parameters:
      recordOrArray - the value node to serialize
      writer - the target writer
      pretty - if true, the output is indented for readability

    • fromJson

      public static <T extends ValueNode<?>> T fromJson(String json)
      Deserializes a record or array from a JSON string.
      Type Parameters:
      T - the expected return type (Record or ArrayValue)
      Parameters:
      json - the JSON string
      Returns:
      the deserialized value node
      Throws:
      DataException - if the JSON cannot be parsed

    • fromJson

      public static <T extends ValueNode<?>> T fromJson(Reader reader)
      Deserializes a record or array from a JSON reader.
      Type Parameters:
      T - the expected return type (Record or ArrayValue)
      Parameters:
      reader - the JSON source
      Returns:
      the deserialized value node

    • toXml

      public String toXml()
      Serializes this record to an XML string.
      Specified by:
      toXml in class ValueNode<Record>
      Returns:
      the XML representation

    • toXml

      public static String toXml(ValueNode<?> recordOrArray)
      Serializes the given record or array to an XML string.
      Parameters:
      recordOrArray - the value node to serialize
      Returns:
      the XML representation

    • toXml

      public static void toXml(ValueNode<?> recordOrArray, Writer writer)
      Writes the record or array as unindented XML inside a <document> root element; the writer is flushed but left open.

    • toXml

      public String toXml(boolean writeRootDocument, boolean pretty)
      Serializes this record to an XML string with control over the root document and formatting.
      Parameters:
      writeRootDocument - if true, includes the XML declaration
      pretty - if true, the output is indented for readability
      Returns:
      the XML representation

    • toXml

      public static String toXml(ValueNode<?> recordOrArray, boolean writeRootDocument, boolean pretty)
      Serializes the given record or array to an XML string with control over the root document and formatting.
      Parameters:
      recordOrArray - the value node to serialize
      writeRootDocument - if true, includes the XML declaration
      pretty - if true, the output is indented for readability
      Returns:
      the XML representation

    • toXml

      public static void toXml(ValueNode<?> recordOrArray, Writer writer, boolean writeRootDocument, boolean pretty)
      Writes the record or array as XML, inside a <document> root element if writeRootDocument and indented if pretty; the writer is flushed but left open.

    • fromXml

      public static <T extends ValueNode<?>> T fromXml(String xml)
      Deserializes a record or array from an XML string.
      Type Parameters:
      T - the expected return type (Record or ArrayValue)
      Parameters:
      xml - the XML string
      Returns:
      the deserialized value node
      Throws:
      DataException - if the XML cannot be parsed

    • fromXml

      public static <T extends ValueNode<?>> T fromXml(Reader reader)
      Deserializes a record or array from an XML reader.
      Type Parameters:
      T - the expected return type (Record or ArrayValue)
      Parameters:
      reader - the XML source
      Returns:
      the deserialized value node

    • toBinary

      public byte[] toBinary()
      Serializes this record to a binary byte array.
      Returns:
      the binary representation

    • toBinary

      public static byte[] toBinary(ValueNode<?> recordOrArray)
      Serializes the given record or array to a binary byte array.
      Parameters:
      recordOrArray - the value node to serialize
      Returns:
      the binary representation

    • toBinary

      public static void toBinary(ValueNode<?> recordOrArray, OutputStream outputStream)
      Serializes the given record or array as binary data to the specified output stream.
      Parameters:
      recordOrArray - the value node to serialize
      outputStream - the target output stream

    • toBinary

      public static void toBinary(ValueNode<?> recordOrArray, DataOutput output)
      Serializes the given record or array as binary data to the specified data output.
      Parameters:
      recordOrArray - the value node to serialize
      output - the target data output

    • fromBinary

      public static <T extends ValueNode<?>> T fromBinary(byte[] bytes)
      Deserializes a record or array from a binary byte array.
      Type Parameters:
      T - the expected return type (Record or ArrayValue)
      Parameters:
      bytes - the binary data
      Returns:
      the deserialized value node, or null if the data is empty
      Throws:
      DataException - if the binary data cannot be parsed

    • fromBinary

      public static <T extends ValueNode<?>> T fromBinary(InputStream inputStream)
      Deserializes a record or array from a binary input stream.
      Type Parameters:
      T - the expected return type (Record or ArrayValue)
      Parameters:
      inputStream - the binary source
      Returns:
      the deserialized value node

    • fromBinary

      public static <T extends ValueNode<?>> T fromBinary(DataInput input)
      Deserializes a record or array from a binary data input.
      Type Parameters:
      T - the expected return type (Record or ArrayValue)
      Parameters:
      input - the binary source
      Returns:
      the deserialized value node, or null if no records were read
      Throws:
      DataException - if the binary data cannot be parsed

    • isEmpty

      public boolean isEmpty()
      Returns true if this record has no fields or all field values are null.

    • isNotEmpty

      public boolean isNotEmpty()
      Returns true if this record has at least one non-null field value.

    • getFieldValueAsString

      public String getFieldValueAsString(String fieldPath, String defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsDatetime

      public Date getFieldValueAsDatetime(String fieldPath, Date defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsDate

      public Date getFieldValueAsDate(String fieldPath, Date defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsTime

      public Time getFieldValueAsTime(String fieldPath, Time defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsInteger

      public Integer getFieldValueAsInteger(String fieldPath, Integer defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsLong

      public Long getFieldValueAsLong(String fieldPath, Long defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsShort

      public Short getFieldValueAsShort(String fieldPath, Short defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsByte

      public Byte getFieldValueAsByte(String fieldPath, Byte defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsBytes

      public byte[] getFieldValueAsBytes(String fieldPath, byte[] defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsBoolean

      public Boolean getFieldValueAsBoolean(String fieldPath, Boolean defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsChar

      public Character getFieldValueAsChar(String fieldPath, Character defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsDouble

      public Double getFieldValueAsDouble(String fieldPath, Double defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsFloat

      public Float getFieldValueAsFloat(String fieldPath, Float defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsBigDecimal

      public BigDecimal getFieldValueAsBigDecimal(String fieldPath, BigDecimal defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsBigInteger

      public BigInteger getFieldValueAsBigInteger(String fieldPath, BigInteger defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsRecord

      public Record getFieldValueAsRecord(String fieldPath, Record defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsArray

      public ArrayValue getFieldValueAsArray(String fieldPath, ArrayValue defaultValue)
      Returns the field's value as array if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsList

      public <T> List<T> getFieldValueAsList(String fieldPath, List<T> defaultValue, Class<T> elementType)
      Returns the field's value as a List if the field exists and its value is not null, otherwise, it returns the default value (even if the list contains no values). See FieldPath for supported fieldPath expressions.

    • getFieldValueAsInstant

      public Instant getFieldValueAsInstant(String fieldPath, Instant defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsLocalDatetime

      public LocalDateTime getFieldValueAsLocalDatetime(String fieldPath, LocalDateTime defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsLocalDate

      public LocalDate getFieldValueAsLocalDate(String fieldPath, LocalDate defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsLocalTime

      public LocalTime getFieldValueAsLocalTime(String fieldPath, LocalTime defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValueAsUUID

      public UUID getFieldValueAsUUID(String fieldPath, UUID defaultValue)
      Returns the field's value if the field exists and its value is not null, otherwise, it returns the default value. See FieldPath for supported fieldPath expressions.

    • getFieldValue

      public <T> T getFieldValue(String fieldPath, T defaultValue)
      Returns the unconverted value at the given FieldPath expression or the default value if it is missing or null.

    • getFieldValue

      public <T> T getFieldValue(FieldPath fieldPath, T defaultValue)
      Gets the value at the specified field path, returning a default value if the field is null or not found. This method provides a type-safe way to retrieve field values with a fallback.
      Type Parameters:
      T - the expected type of the value
      Parameters:
      fieldPath - the path to the field
      defaultValue - the value to return if the field is null or not found
      Returns:
      the field value, or defaultValue if the field is null or not found

    • ensureFields

      public void ensureFields(String... fieldNames)
      Ensures that all specified field names exist in this record, creating any missing ones.
      Parameters:
      fieldNames - the field names to ensure exist

    • ensureFields

      public void ensureFields(Collection<String> fieldNames)
      Ensures that all specified field names exist in this record, creating any missing ones.
      Parameters:
      fieldNames - the collection of field names to ensure exist

    • sortFieldsByName

      public Record sortFieldsByName()
      Sorts the fields in this record alphabetically by name.
      Returns:
      this record for method chaining