Package com.northconcepts.datapipeline.core

Class Field

java.lang.Object
com.northconcepts.datapipeline.core.Node
com.northconcepts.datapipeline.core.Field
All Implemented Interfaces:
Session, ValueNodeContainer, Serializable, Comparable<Field>
public final class Field extends Node implements ValueNodeContainer, Comparable<Field>, Serializable
Field holds persistent key-value data as part of a record. Values in a field can be:
  • Single values (boolean, date, string, etc. -- see )
  • Records
  • Array of single values, records, and arrays
    See Also:

    • Field Details

    • Constructor Details

      • Field

        protected Field(Record record)

    • Method Details

      • getNodeType

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

      • hasChildNodes

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

        Returns true if this field has a non-null value that itself contains child nodes.

        Specified by:
        hasChildNodes in class Node

      • hasChildRecords

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

        Returns true if this field's value is a Record or contains descendant 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

      • copyFrom

        public Field copyFrom(Field field)
        Copies all properties (name, value, and session properties) from the specified field into this one.
        Parameters:
        field - the source field to copy from
        Returns:
        this field for method chaining

      • copyFrom

        public Field copyFrom(Field field, boolean copyName)
        Copies properties from the specified field into this one. If copyName is true, the name is also copied; otherwise only the value and session properties are copied.
        Parameters:
        field - the source field to copy from
        copyName - true to copy the field name as well
        Returns:
        this field for method chaining

      • toString

        public String toString()
        Returns a human-readable string representation of this field, including its name, type, and value.
        Specified by:
        toString in class Node
        Returns:
        a string representation of this field

      • remove

        public boolean remove()
        Removes this field from its parent record.
        Returns:
        true if the record contained this field (i.e. the field hadn't already been removed).

      • getIndex

        public int getIndex()
        Returns the position of this field within its record.

      • getName

        public String getName()
        Returns this field's name. If the name has not been explicitly set, a default name is generated based on the field's position within its record.
        Returns:
        the field name, never null

      • getName

        public String getName(boolean nullToDefaultName)
        Returns this field's name. If nullToDefaultName is true and the name has not been explicitly set, a default name is generated based on the field's position. If false, null may be returned when no name has been set.
        Parameters:
        nullToDefaultName - whether to generate a default name when none has been set
        Returns:
        the field name, or null if no name is set and nullToDefaultName is false

      • setName

        public Field setName(String name)
        Sets the name of this field.
        Parameters:
        name - the new field name
        Returns:
        this field for method chaining

      • getType

        public FieldType getType()
        Returns the FieldType of this field's value. If no value has been set, returns FieldType.STRING as the default.
        Returns:
        the field type

      • isArray

        public boolean isArray()
        Returns true if this field's value is an ArrayValue.
        Returns:
        true if the value is an array

      • isNotArray

        public boolean isNotArray()
        Returns true if this field's value is not an ArrayValue.
        Returns:
        true if the value is not an array

      • isRecord

        public boolean isRecord()
        Returns true if this field's value is a Record.
        Returns:
        true if the value is a record

      • isSingleValue

        public boolean isSingleValue()
        Returns true if this field's value is a SingleValue.
        Returns:
        true if the value is a single value

      • isNotSingleValue

        public boolean isNotSingleValue()
        Returns true if this field's value is not a SingleValue.
        Returns:
        true if the value is not a single value

      • isNotRecord

        public boolean isNotRecord()
        Returns true if this field's value is not a Record.
        Returns:
        true if the value is not a record

      • forceValueAsArray

        public Field forceValueAsArray()
        Converts this field's value to an array if it's not already one, otherwise no change is made.

      • isValueSet

        public boolean isValueSet()
        Returns true if this field has had a value assigned (including a null value). A field that has never been assigned returns false.
        Returns:
        true if a value has been set

      • isValueNotSet

        public boolean isValueNotSet()
        Returns true if this field has never had a value assigned.
        Returns:
        true if no value has been set

      • hasValue

        public boolean hasValue()
        Returns true if this field has been set to a value, including null. Otherwise, it returns false. This method is an alias for isValueSet().
        Specified by:
        hasValue in interface ValueNodeContainer

      • isNull

        public boolean isNull()
        Description copied from class: Node
        Returns true if this node contains a null value. In concrete terms, only Field and SingleValue can contain nulls while not being null themselves. Both Record and ArrayValue will return false even if they have no values or null only values.
        Specified by:
        isNull in class Node

      • isNotNull

        public boolean isNotNull()
        Description copied from class: Node
        Returns true if this node does not contain a null value. In concrete terms, only Field and SingleValue can contain nulls while not being null themselves. Both Record and ArrayValue will return true even if they have no values or null only values.
        Specified by:
        isNotNull in class Node

      • addValue

        public Field addValue(FieldType type, Object value)
        Adds a value to this field, converting the value to the appropriate type if necessary.
        Specified by:
        addValue in interface ValueNodeContainer
        Parameters:
        type - the expected type of the value
        value - the value to add
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(Object value)
        Sets this field's value, inferring the FieldType from the value's class.
        Parameters:
        value - the value to set, may be null
        Returns:
        this field for method chaining

      • addValue

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

      • setNull

        public Field setNull(FieldType type)
        Sets this field's value to null with the given type; a null type keeps the type of the value it replaces.

      • addNull

        public Field addNull(FieldType type)
        Description copied from interface: ValueNodeContainer
        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

      • compareTo

        public int compareTo(Field field)
        Compares this field to another by their values using natural ordering.
        Specified by:
        compareTo in interface Comparable<Field>
        Parameters:
        field - the other field to compare to
        Returns:
        a negative integer, zero, or a positive integer as this field's value is less than, equal to, or greater than the other's

      • compareTo

        public int compareTo(Field field, Collator collator)
        Compares this field to another by their values, optionally using the specified Collator for string comparisons.
        Parameters:
        field - the other field to compare to
        collator - the collator for string comparisons, or null for natural ordering
        Returns:
        a negative integer, zero, or a positive integer as this field's value is less than, equal to, or greater than the other's

      • equals

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

      • equals

        public boolean equals(Object o, Collator collator)
        Indicates whether the given object is a Field with an equal value, using the specified Collator for string comparisons.
        Parameters:
        o - the object to compare with
        collator - the collator for string comparisons, or null for natural ordering
        Returns:
        true if the objects are equal

      • hashCode

        public int hashCode()
        Returns a hash code based on this field's value.
        Overrides:
        hashCode in class Object
        Returns:
        the hash code

      • getSizeOfNameInBytes

        public long getSizeOfNameInBytes()
        Returns the estimated size of this field's name in bytes, including object overhead.
        Returns:
        the name size in bytes

      • getSizeInBytes

        public long getSizeInBytes()
        Returns the estimated size of this field in bytes, including object overhead and value size.
        Returns:
        the size in bytes

      • getRecord

        public Record getRecord()
        Returns the record this field belongs to.

      • getParentRecord

        public Record getParentRecord()
        Description copied from class: Node
        Returns the closest parent record that this node is the child of, otherwise null if one does not exist.
        Overrides:
        getParentRecord in class Node
        See Also:

      • getParentNode

        public Node getParentNode()
        Description copied from class: Node
        Returns the parent node that this node belongs to, or null if this is a root node.
        Specified by:
        getParentNode in class Node
        Returns:
        the parent node, or null

      • getValue

        public Object getValue()
        Returns the raw value held by this field, or null if the field has no value or is null.
        Returns:
        the field's value, or null

      • getValueNode

        public ValueNode<?> getValueNode()
        Returns the ValueNode backing this field's value, or null if no value has been set.
        Returns:
        the value node, or null

      • getValueAsArray

        public ArrayValue getValueAsArray()
        Retrieve the field's value as an ArrayValue.

      • getValueAsArray

        public ArrayValue getValueAsArray(boolean force)
        Retrieve the field's value as an ArrayValue. An exception will be thrown when typecasting if the value is not an ArrayValue.

      • getValueAsList

        public <T> List<T> getValueAsList(boolean force, Class<T> elementType)
        Retrieve the field's value as a List.
        Type Parameters:
        T - The list's parameterized element type
        Parameters:
        force - indicates if a field containing a single value should be forced to become an ArrayValue of one element, otherwise, an exception will be thrown when the typecast to ArrayValue fails.
        elementType - the target Class of the list's elements. This is used internally to coerce the actual value into this desired type.

      • getValueAsRecord

        public Record getValueAsRecord()
        Returns this field's value cast to a Record.
        Returns:
        the record value
        Throws:
        ClassCastException - if the value is not a Record

      • getValueAsSingleValue

        public SingleValue getValueAsSingleValue()
        Returns this field's value cast to a SingleValue.
        Returns:
        the single value
        Throws:
        ClassCastException - if the value is not a SingleValue

      • getValueAsString

        public String getValueAsString()
        Returns this field's value as a String.
        Returns:
        the string representation of the value, or null if the value is null

      • getValueAsDatetime

        public Date getValueAsDatetime()
        Returns this field's value as a Date (datetime).
        Returns:
        the datetime value, or null if the value is null

      • getValueAsDate

        public Date getValueAsDate()
        Returns this field's value as a Date.
        Returns:
        the date value, or null if the value is null

      • getValueAsTime

        public Time getValueAsTime()
        Returns this field's value as a Time.
        Returns:
        the time value, or null if the value is null

      • getValueAsInteger

        public int getValueAsInteger()
        Returns this field's value as an int.
        Returns:
        the integer value
        Throws:
        NullPointerException - if the value is null

      • getValueAsLong

        public long getValueAsLong()
        Returns this field's value as a long.
        Returns:
        the long value
        Throws:
        NullPointerException - if the value is null

      • getValueAsShort

        public short getValueAsShort()
        Returns this field's value as a short.
        Returns:
        the short value
        Throws:
        NullPointerException - if the value is null

      • getValueAsByte

        public byte getValueAsByte()
        Returns this field's value as a byte.
        Returns:
        the byte value
        Throws:
        NullPointerException - if the value is null

      • getValueAsBoolean

        public boolean getValueAsBoolean()
        Returns this field's value as a boolean.
        Returns:
        the boolean value
        Throws:
        NullPointerException - if the value is null

      • getValueAsChar

        public char getValueAsChar()
        Returns this field's value as a char.
        Returns:
        the character value
        Throws:
        NullPointerException - if the value is null

      • getValueAsDouble

        public double getValueAsDouble()
        Returns this field's value as a double.
        Returns:
        the double value
        Throws:
        NullPointerException - if the value is null

      • getValueAsFloat

        public float getValueAsFloat()
        Returns this field's value as a float.
        Returns:
        the float value
        Throws:
        NullPointerException - if the value is null

      • getValueAsBytes

        public byte[] getValueAsBytes()
        Returns this field's value as a byte[].
        Returns:
        the byte array value, or null if the value is null

      • getValueAsBigDecimal

        public BigDecimal getValueAsBigDecimal()
        Returns this field's value as a BigDecimal.
        Returns:
        the big decimal value, or null if the value is null

      • getValueAsBigInteger

        public BigInteger getValueAsBigInteger()
        Returns this field's value as a BigInteger.
        Returns:
        the big integer value, or null if the value is null

      • getValueAsInstant

        public Instant getValueAsInstant()
        Returns this field's value as an Instant.
        Returns:
        the instant value, or null if the value is null

      • getValueAsLocalDateTime

        public LocalDateTime getValueAsLocalDateTime()
        Returns this field's value as a LocalDateTime.
        Returns:
        the local date-time value, or null if the value is null

      • getValueAsLocalDate

        public LocalDate getValueAsLocalDate()
        Returns this field's value as a LocalDate.
        Returns:
        the local date value, or null if the value is null

      • getValueAsLocalTime

        public LocalTime getValueAsLocalTime()
        Returns this field's value as a LocalTime.
        Returns:
        the local time value, or null if the value is null

      • getValueAsUuid

        public UUID getValueAsUuid()
        Returns this field's value as a UUID.
        Returns:
        the UUID value, or null if the value is null

      • setValue

        public Field setValue(String value)
        Sets this field's value to the specified string.
        Parameters:
        value - the string value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(Date value)
        Sets this field's value to the specified datetime.
        Parameters:
        value - the datetime value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(Date value)
        Sets this field's value to the specified date.
        Parameters:
        value - the date value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(Time value)
        Sets this field's value to the specified time.
        Parameters:
        value - the time value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(int value)
        Sets this field's value to the specified integer.
        Parameters:
        value - the integer value
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(long value)
        Sets this field's value to the specified long.
        Parameters:
        value - the long value
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(short value)
        Sets this field's value to the specified short.
        Parameters:
        value - the short value
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(byte value)
        Sets this field's value to the specified byte.
        Parameters:
        value - the byte value
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(boolean value)
        Sets this field's value to the specified boolean.
        Parameters:
        value - the boolean value
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(char value)
        Sets this field's value to the specified character.
        Parameters:
        value - the character value
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(double value)
        Sets this field's value to the specified double.
        Parameters:
        value - the double value
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(float value)
        Sets this field's value to the specified float.
        Parameters:
        value - the float value
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(byte[] value)
        Sets this field's value to the specified byte array (blob).
        Parameters:
        value - the byte array value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(BigDecimal value)
        Sets this field's value to the specified BigDecimal.
        Parameters:
        value - the big decimal value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(BigInteger value)
        Sets this field's value to the specified BigInteger.
        Parameters:
        value - the big integer value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(Record value)
        Sets this field's value to the specified Record.
        Parameters:
        value - the record value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(Instant value)
        Sets this field's value to the specified Instant, converting it to a Date internally.
        Parameters:
        value - the instant value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(LocalDateTime value)
        Sets this field's value to the specified LocalDateTime, converting it to a Date using the system default time zone.
        Parameters:
        value - the local date-time value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(LocalDate value)
        Sets this field's value to the specified LocalDate, converting it to a Date.
        Parameters:
        value - the local date value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(LocalTime value)
        Sets this field's value to the specified LocalTime, converting it to a Time.
        Parameters:
        value - the local time value, may be null
        Returns:
        this field for method chaining

      • setValue

        public Field setValue(UUID value)
        Sets this field's value to the specified UUID.
        Parameters:
        value - the UUID value, may be null
        Returns:
        this field for method chaining