Package com.northconcepts.datapipeline.core

Class ArrayValue

java.lang.Object
com.northconcepts.datapipeline.core.Node
com.northconcepts.datapipeline.core.ValueNode<ArrayValue>
com.northconcepts.datapipeline.core.ArrayValue
All Implemented Interfaces:
Session, ValueNodeContainer, Serializable, Cloneable, Comparable<ValueNode<ArrayValue>>, Iterable<ValueNode<?>>
public final class ArrayValue extends ValueNode<ArrayValue> implements ValueNodeContainer, Iterable<ValueNode<?>>
ArrayValue holds an ordered collection (also known as a sequence) of persistent data. Data elements can be single values, records, sub arrays, or any combination. If ArrayValue has elements, its getType() method will return a FieldType matching all elements or FieldType.UNDEFINED if elements contain different types. If ArrayValue has no elements, its defaultType will be returned.
See Also:

  • Constructor Details

    • ArrayValue

      public ArrayValue()
      Creates a new empty array with an FieldType.UNDEFINED default type.

    • ArrayValue

      public ArrayValue(FieldType defaultType)
      Creates a new empty array.
      Parameters:
      defaultType - the value returned by getType() if there are no elements.

    • ArrayValue

      public ArrayValue(Object... collection)
      Creates a new array populated with the given objects. ValueNode instances are added directly; Iterable instances have their elements added individually; all other objects are wrapped via ValueNode.from(Object).
      Parameters:
      collection - the objects to add, may be null

  • Method Details

    • ensureCapacity

      public ArrayValue ensureCapacity(int minCapacity)
      Increases the capacity of this array's internal list, if necessary, to ensure it can hold at least the specified number of elements without reallocating.
      Parameters:
      minCapacity - the desired minimum capacity
      Returns:
      this ArrayValue for method chaining

    • iterator

      public Iterator<ValueNode<?>> iterator()
      Specified by:
      iterator in interface Iterable<ValueNode<?>>

    • addValue

      public ArrayValue addValue(FieldType type, Object element)
      Adds a value with the specified FieldType to this container.
      Specified by:
      addValue in interface ValueNodeContainer
      Parameters:
      type - the field type of the value to add, or null to infer the type
      element - the value to add, may be null
      Returns:
      this container for method chaining

    • addValue

      public ArrayValue addValue(Object element)
      Adds a value to this container, inferring the FieldType from the value's class.
      Specified by:
      addValue in interface ValueNodeContainer
      Parameters:
      element - the value to add, may be null
      Returns:
      this container for method chaining

    • addAll

      public ArrayValue addAll(ArrayValue array)
      Appends cloned copies of all elements from the specified array to this array.
      Parameters:
      array - the source array whose elements are to be added
      Returns:
      this ArrayValue for method chaining

    • addAll

      public ArrayValue addAll(Collection<?> collection)
      Adds all elements from the specified collection to this array. Each element is converted to a ValueNode before being added.
      Parameters:
      collection - the collection of elements to add, may be null
      Returns:
      this ArrayValue instance for method chaining

    • addValue

      public ArrayValue addValue(int index, FieldType type, Object element)
      Inserts a value with the specified FieldType at the given index, shifting subsequent elements to the right.
      Parameters:
      index - the position at which to insert the value
      type - the field type of the value, or null to infer the type
      element - the value to insert, may be null
      Returns:
      this ArrayValue for method chaining

    • addValue

      public ArrayValue addValue(int index, Object element)
      Inserts a value at the given index, inferring the FieldType from the value's class.
      Parameters:
      index - the position at which to insert the value
      element - the value to insert, may be null
      Returns:
      this ArrayValue for method chaining

    • setValue

      public ArrayValue setValue(int index, FieldType type, Object element)
      Replaces the element at the specified index with a new value of the given type. If both type and element are null, the type of the existing element is preserved.
      Parameters:
      index - the position of the element to replace
      type - the field type of the new value, or null to infer
      element - the new value, may be null
      Returns:
      this ArrayValue for method chaining

    • setValue

      public ArrayValue setValue(int index, Object element)
      Replaces the element at the specified index with a new value, inferring the FieldType.
      Parameters:
      index - the position of the element to replace
      element - the new value, may be null
      Returns:
      this ArrayValue for method chaining

    • addNull

      public ArrayValue addNull(FieldType type)
      Adds a typed null value to this container.
      Specified by:
      addNull in interface ValueNodeContainer
      Parameters:
      type - the field type of the null value to add
      Returns:
      this container for method chaining

    • addNull

      public ArrayValue addNull(int index, FieldType type)
      Inserts a typed null value at the given index.
      Parameters:
      index - the position at which to insert
      type - the field type for the null value
      Returns:
      this ArrayValue for method chaining

    • setNull

      public ArrayValue setNull(int index, FieldType type)
      Replaces the element at the specified index with a typed null value.
      Parameters:
      index - the position of the element to replace
      type - the field type for the null value
      Returns:
      this ArrayValue for method chaining

    • removeValue

      public Object removeValue(int index)
      Removes and returns the underlying value of the element at the specified index.
      Parameters:
      index - the index of the element to remove
      Returns:
      the value of the removed element
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • removeValue

      public boolean removeValue(Object value)
      Removes all elements whose underlying value equals the specified value.
      Parameters:
      value - the value to match for removal
      Returns:
      true if at least one element was removed

    • getDefaultType

      public FieldType getDefaultType()
      Returns the default FieldType used when this array is empty.
      Returns:
      the default field type, never null

    • setDefaultType

      public ArrayValue setDefaultType(FieldType defaultType)
      Sets the default FieldType used when this array is empty. A null value is normalized to FieldType.UNDEFINED.
      Parameters:
      defaultType - the default field type
      Returns:
      this ArrayValue for method chaining

    • getType

      public FieldType getType()
      Returns defaultType if there are no elements, the FieldType matching all elements if they are the same or FieldType.UNDEFINED if elements contain multiple types.
      Specified by:
      getType in class ValueNode<ArrayValue>
      Returns:
      the field type of this value node, never null

    • getNodeType

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

    • hasChildNodes

      public boolean hasChildNodes()
      Returns true if this node contains any sub nodes.

      Returns true if this array contains at least one element.

      Specified by:
      hasChildNodes in class Node

    • hasChildRecords

      public boolean hasChildRecords()
      Returns true if this node contains any descendant, record nodes.

      Returns true if any element in this array is a Record or itself contains child records.

      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

    • indexOfNode

      public int indexOfNode(Node child)
      Returns the index of the specified node in this array using identity comparison, or -1 if not found.
      Parameters:
      child - the node to search for
      Returns:
      the index of the node, or -1

    • indexOfValue

      public int indexOfValue(Object value)
      Returns the index of the first element whose underlying value equals the specified value, or -1 if not found.
      Parameters:
      value - the value to search for
      Returns:
      the index of the matching element, or -1

    • getNodeDepth

      public int getNodeDepth()
      Returns this node's distance from its root node. It returns 0 if it is the root node (i.e. it has no parents), 1 if it is the direct child of the root node, 2 if it is the grandchild of the root, and so on.

      Adjusts the depth by subtracting one since arrays are logically transparent in the record hierarchy.

      Overrides:
      getNodeDepth in class Node

    • isArray

      public boolean isArray()
      Returns true if this value node is an ArrayValue.

      Always returns true.

      Overrides:
      isArray in class ValueNode<ArrayValue>
      Returns:
      true if this is an array, false otherwise
      See Also:

    • size

      public int size()
      Returns the number of elements in this array.
      Returns:
      the element count

    • isEmpty

      public boolean isEmpty()
      Returns true if this array contains no elements -- equivalent to size() == 0.

    • isNotEmpty

      public boolean isNotEmpty()
      Returns true if this array contains elements -- equivalent to size() > 0.

    • hasValue

      public boolean hasValue()
      Returns true if this container has had any value added, including null. Otherwise, it returns false.

      Returns true if this array is not empty.

      Specified by:
      hasValue in interface ValueNodeContainer

    • getValue

      public Object getValue(int index)
      Returns the value 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).

    • getValues

      public List<Object> getValues()
      Returns a list of values.

    • getValues

      public <T> List<T> getValues(Class<T> elementType)
      Returns a list of values with each element coerced to the supplied type.

    • getValueStream

      public Stream<Object> getValueStream()
      Returns a stream of values.

    • getValueStream

      public <T> Stream<T> getValueStream(Class<T> elementType)
      Returns a stream of values with each element coerced to the supplied type.

    • getValueNode

      public ValueNode<?> getValueNode(int index)
      Returns the value node 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).

    • forEach

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

    • forEachRecord

      public void forEachRecord(Consumer<Record> action)
      Performs the given action for each Record element in this array. Non-record elements are filtered out.
      Parameters:
      action - the action to perform on each Record element

    • forEachArrayValue

      public void forEachArrayValue(Consumer<ArrayValue> action)
      Performs the given action for each ArrayValue element in this array. Non-array elements are filtered out.
      Parameters:
      action - the action to perform on each ArrayValue element

    • forEachSingleValue

      public void forEachSingleValue(Consumer<SingleValue> action)
      Performs the given action for each SingleValue element in this array. Non-single-value elements are filtered out.
      Parameters:
      action - the action to perform on each SingleValue element

    • stream

      public Stream<ValueNode<?>> stream()
      Returns a sequential Stream of the elements in this array.

    • parallelStream

      public Stream<ValueNode<?>> parallelStream()
      Returns a parallel Stream of the elements in this array.

    • findFirst

      public int findFirst(Predicate<ValueNode<?>> predicate, int fromIndex)
      Returns the index of the first element in this array that matches the given predicate, starting at the specified index, or -1 if no element matches.
      Parameters:
      predicate - the predicate to test elements against
      fromIndex - the index to start searching from (negative values are treated as 0)
      Returns:
      the index of the first matching element, or -1 if not found

    • findLast

      public int findLast(Predicate<ValueNode<?>> predicate, int fromIndex)
      Returns the index of the last element in this array that matches the given predicate, searching backward from the specified index, or -1 if no element matches.
      Parameters:
      predicate - the predicate to test elements against
      fromIndex - the index to start searching backward from (-1 or values >= size start from the end)
      Returns:
      the index of the last matching element, or -1 if not found

    • findAll

      public ArrayValue findAll(Predicate<ValueNode<?>> predicate)
      Returns a new ArrayValue containing all elements that match the given predicate. The returned array contains clones of the matching elements.
      Parameters:
      predicate - the predicate to test elements against
      Returns:
      a new ArrayValue with all matching elements

    • count

      public int count(Predicate<ValueNode<?>> predicate)
      Returns the number of elements in this array that match the given predicate.
      Parameters:
      predicate - the predicate to test elements against
      Returns:
      the count of matching elements

    • getValueAsArray

      public ArrayValue getValueAsArray(int index)
      Returns the element at the specified index cast to an ArrayValue.
      Parameters:
      index - the index of the element
      Returns:
      the element as an ArrayValue
      Throws:
      ClassCastException - if the element is not an ArrayValue

    • getValueAsList

      public <T> List<T> getValueAsList(int index, Class<T> elementType)
      Returns the array element value at the specified index as a List with each element coerced to the specified type. See FieldPath for supported fieldPath expressions.

    • getValueAsRecord

      public Record getValueAsRecord(int index)
      Returns the element at the specified index cast to a Record.
      Parameters:
      index - the index of the element
      Returns:
      the element as a Record
      Throws:
      ClassCastException - if the element is not a Record

    • getValueAsSingleValue

      public SingleValue getValueAsSingleValue(int index)
      Returns the element at the specified index cast to a SingleValue.
      Parameters:
      index - the index of the element
      Returns:
      the element as a SingleValue
      Throws:
      ClassCastException - if the element is not a SingleValue

    • getValueAsString

      public String getValueAsString(int index)
      Returns the string representation of the element at the specified index.
      Parameters:
      index - the index of the element
      Returns:
      the element's string representation

    • getValueAsDatetime

      public Date getValueAsDatetime(int index)
      Returns the element at the specified index as a Date (datetime).
      Parameters:
      index - the index of the element
      Returns:
      the datetime value

    • getValueAsDate

      public Date getValueAsDate(int index)
      Returns the element at the specified index as a Date.
      Parameters:
      index - the index of the element
      Returns:
      the date value

    • getValueAsTime

      public Time getValueAsTime(int index)
      Returns the element at the specified index as a Time.
      Parameters:
      index - the index of the element
      Returns:
      the time value

    • getValueAsInteger

      public int getValueAsInteger(int index)
      Returns the element at the specified index as an int.
      Parameters:
      index - the index of the element
      Returns:
      the integer value

    • getValueAsLong

      public long getValueAsLong(int index)
      Returns the element at the specified index as a long.
      Parameters:
      index - the index of the element
      Returns:
      the long value

    • getValueAsShort

      public short getValueAsShort(int index)
      Returns the element at the specified index as a short.
      Parameters:
      index - the index of the element
      Returns:
      the short value

    • getValueAsByte

      public byte getValueAsByte(int index)
      Returns the element at the specified index as a byte.
      Parameters:
      index - the index of the element
      Returns:
      the byte value

    • getValueAsBoolean

      public boolean getValueAsBoolean(int index)
      Returns the element at the specified index as a boolean.
      Parameters:
      index - the index of the element
      Returns:
      the boolean value

    • getValueAsChar

      public char getValueAsChar(int index)
      Returns the element at the specified index as a char.
      Parameters:
      index - the index of the element
      Returns:
      the character value

    • getValueAsDouble

      public double getValueAsDouble(int index)
      Returns the element at the specified index as a double.
      Parameters:
      index - the index of the element
      Returns:
      the double value

    • getValueAsFloat

      public float getValueAsFloat(int index)
      Returns the element at the specified index as a float.
      Parameters:
      index - the index of the element
      Returns:
      the float value

    • getValueAsBytes

      public byte[] getValueAsBytes(int index)
      Returns the element at the specified index as a byte[].
      Parameters:
      index - the index of the element
      Returns:
      the byte array value

    • getValueAsBigDecimal

      public BigDecimal getValueAsBigDecimal(int index)
      Returns the element at the specified index as a BigDecimal.
      Parameters:
      index - the index of the element
      Returns:
      the big decimal value

    • getValueAsBigInteger

      public BigInteger getValueAsBigInteger(int index)
      Returns the element at the specified index as a BigInteger.
      Parameters:
      index - the index of the element
      Returns:
      the big integer value

    • getValueAsInstant

      public Instant getValueAsInstant(int index)
      Returns the element at the specified index as an Instant.
      Parameters:
      index - the index of the element
      Returns:
      the instant value

    • getValueAsLocalDateTime

      public LocalDateTime getValueAsLocalDateTime(int index)
      Returns the element at the specified index as a LocalDateTime.
      Parameters:
      index - the index of the element
      Returns:
      the local date-time value

    • getValueAsLocalDate

      public LocalDate getValueAsLocalDate(int index)
      Returns the element at the specified index as a LocalDate.
      Parameters:
      index - the index of the element
      Returns:
      the local date value

    • getValueAsLocalTime

      public LocalTime getValueAsLocalTime(int index)
      Returns the element at the specified index as a LocalTime.
      Parameters:
      index - the index of the element
      Returns:
      the local time value

    • getValueAsUuid

      public UUID getValueAsUuid(int index)
      Returns the element at the specified index as a UUID.
      Parameters:
      index - the index of the element
      Returns:
      the UUID value

    • getValue

      public ArrayValue 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 ArrayValue instance (arrays are self-referencing values).

      Specified by:
      getValue in class ValueNode<ArrayValue>
      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<ArrayValue>
      Returns:
      the value as a string, or "null" if the value is null

    • getSizeInBytes

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

    • sort

      public ArrayValue sort()
      Sorts this array using the default ValueNodeComparator. The sort is performed in-place, modifying this array.
      Returns:
      this ArrayValue instance for method chaining
      See Also:

    • sort

      public ArrayValue sort(Comparator<ValueNode<?>> comparator)
      Sorts this array using the specified comparator. The sort is performed in-place, modifying this array.
      Parameters:
      comparator - the comparator to use for sorting
      Returns:
      this ArrayValue instance for method chaining

    • compareTo

      public int compareTo(ValueNode<ArrayValue> o)
      Compares this array to another by length first, then element-by-element.
      Specified by:
      compareTo in interface Comparable<ValueNode<ArrayValue>>
      Parameters:
      o - the other value node to compare to
      Returns:
      a negative integer, zero, or a positive integer as this array is less than, equal to, or greater than the other

    • equals

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

    • hashCode

      public int hashCode()
      Returns a hash code based on the internal element list.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code

    • clone

      public ArrayValue clone()
      Returns a deep copy of this array, cloning every element.
      Specified by:
      clone in class ValueNode<ArrayValue>
      Returns:
      a new ArrayValue with cloned elements and the same default type

    • toString

      public String toString()
      Returns a string representation of this array in the form [element1, element2, ...].
      Specified by:
      toString in class Node
      Returns:
      a string representation of the array contents

    • toJson

      public String toJson()
      Serializes this array to a JSON string.
      Specified by:
      toJson in class ValueNode<ArrayValue>
      Returns:
      the JSON representation
      See Also:

    • toXml

      public String toXml()
      Serializes this array to an XML string.
      Specified by:
      toXml in class ValueNode<ArrayValue>
      Returns:
      the XML representation
      See Also:

    • toBinary

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

    • fromArray

      protected static ArrayValue fromArray(Object array)
      Converts a Java array (primitive or object) to an ArrayValue, typing its elements by the component type when that maps to a FieldType; null yields an empty array.