Package com.northconcepts.datapipeline.core

Class FieldPath

java.lang.Object
com.northconcepts.datapipeline.core.FieldPath
All Implemented Interfaces:
JsonSerializable, RecordSerializable, XmlSerializable, JavaCodeGenerator
public class FieldPath extends Object implements RecordSerializable, XmlSerializable, JavaCodeGenerator
An abstract representation for the location of a field within a record. Instances can be created by parsing an expression with parse(String) or programmatically by adding name (name(String)) and index (index(int)) segments to an instance.

For example, the field path customer.address[0].city can be created in two ways:

  1. FieldPath.parse("customer.address[0].city")
  2. new FieldPath().name("customer").name("address").index(0).name("city")

Other examples of parsed field paths include:

  • Single field names: firstName
  • Nested field names: customer.firstName
  • Array values: customer.address[2].city
  • Positional field access: customer.address[2][0]
  • Positional field access: [1]
  • String arrays (for field names with spaces): customer.address[2]["zip code"]
  • String arrays (using single quotes): customer.address[2]['zip code']
  • Quoted field names (for field names with spaces or symbols): 'Company Flag (Y/N)'
  • Quoted nested field names (for field names with spaces or symbols): customer."Company Flag (Y/N)"
  • Quoted array values (for field names with spaces or symbols): `Company Address`[0]

Identifiers in field expressions may start with letters, underscores (_), at symbols (@), or dollar signs ($) and contain letters, numbers, underscores, at symbols, and dollar signs. You will need to quote field expressions that contain other symbols and spaces if they should be treated as part of the field name. For example, if your field name contains a period, you will need to quote it ("Package Lbs.").

Quoting:When quoting fields, you can use double quotes ("), single quotes ('), or grave accent (`).

A note of caution: FieldPath can also represent the location of values in array fields. For example, city[2] or customer.address[0].city[2] could match the third city in an array field. Some methods and operations expecting a field will throw an exception (or return false) if the supplied FieldPath matches an array value and not a field.

See Also:

  • Constructor Details

    • FieldPath

      public FieldPath()

  • Method Details

    • parse

      public static FieldPath parse(String fieldPathExpression)
      Converts a field path expression into a FieldPath object. Expressions can be:
      • Single field names: firstName
      • Nested field names: customer.firstName
      • Array values: customer.address[2].city
      • Positional field access: customer.address[2][0]
      • Positional field access: [1]
      • String arrays (for field names with spaces): customer.address[2]["zip code"]
      • String arrays (using single quotes): customer.address[2]['zip code']
      • Quoted field names (for field names with spaces or symbols): 'Company Flag (Y/N)'
      • Quoted nested field names (for field names with spaces or symbols): customer."Company Flag (Y/N)"
      • Quoted array values (for field names with spaces or symbols): `Company Address`[0]

      Identifiers in field expressions may start with letters, underscores (_), at symbols (@), or dollar signs ($) and contain letters, numbers, underscores, at symbols, and dollar signs. You will need to quote field expressions that contain other symbols and spaces if they should be treated as part of the field name. For example, if your field name contains a period, you will need to quote it ("Package Lbs.").

      Quoting:When quoting fields, you can use double quotes ("), single quotes ('), or grave accent (`).

    • parse

      public static FieldPath parse(String fieldPathExpression, boolean failOnEmpty)
      Parses the expression as parse(String) does, except that a null or blank expression returns null, or throws if failOnEmpty is true.

    • fromName

      public static FieldPath fromName(String fieldName)
      Converts a single field name into a FieldPath. This method does no parsing and treats all characters as part of the field name.

    • name

      public FieldPath name(String name)
      Appends a new field name segment to this field path.

    • index

      public FieldPath index(int index)
      Appends a 0-based index segment that selects an array element or a record's field by position; negative indexes count back from the end.

    • isTabular

      public boolean isTabular()
      Indicates if this path matches against a flat record (i.e. no nested records or array fields).

    • getField

      public Field getField(Record record, boolean create, boolean throwException)
      Returns the field at this path, creating missing parts if create is true; if the path does not resolve it returns null, or throws when throwException is true.

    • getSingleValue

      public SingleValue getSingleValue(Record record, boolean create, boolean throwException)
      Returns the SingleValue at this path (a field's value or an array element), handling create and throwException like getField(Record, boolean, boolean).

    • getValueNode

      public ValueNode<?> getValueNode(ValueNode<?> recordOrArray, boolean create, boolean throwException)
      Returns the value (record, array or single value) at this path below the given record or array, handling create and throwException like getField(Record, boolean, boolean).

    • setValue

      public ValueNode<?> setValue(ValueNode<?> parentNode, boolean create, boolean throwException, Object value)
      Sets the value of the field or array element at this path, creating missing parts if create is true; returns the new value node or null if the path does not resolve.

    • getValue

      public Object getValue(ValueNode<?> recordOrArray, boolean create, boolean throwException)
      Returns the plain value of the node that getValueNode(ValueNode, boolean, boolean) finds, or null if there is none.

    • getNode

      public Node getNode(Node rootNode, boolean create, boolean throwException)
      Returns the node (field, record, array or single value) this path leads to from rootNode, creating missing parts if create is true.

    • containsField

      public boolean containsField(Record record)
      Returns true if this path leads to a field (not an array element) in the record.

    • containsNonNullField

      public boolean containsNonNullField(Record record)
      Returns true if this path leads to a field in the record whose value is not null.

    • contains

      @Deprecated public boolean contains(Record record)
      Deprecated.
      Use containsValue(Record) instead.

    • containsValue

      public boolean containsValue(Record record)
      Returns true if this path leads to anything in the record (a field or an array element), even if it holds null.

    • containsNonNullValue

      public boolean containsNonNullValue(Record record)
      Returns true if this path leads to a field or array element in the record whose value is not null.

    • getSimpleName

      public String getSimpleName()
      Returns the name (or number/index) of the last segment in this path as a string.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toExpression

      public String toExpression()
      Returns this path as an expression, quoting names that contain characters other than letters and digits (unlike toString()).

    • toRecord

      public Record toRecord()
      Description copied from interface: RecordSerializable
      Converts this object's state to a record that RecordSerializable.fromRecord(Record) can load.
      Specified by:
      toRecord in interface RecordSerializable

    • fromRecord

      public FieldPath fromRecord(Record source)
      Description copied from interface: RecordSerializable
      Loads this instance's state from a record and returns this (for fluid API call chaining). For fluid API call chaining, the overridden method should change the declared return type to its class.
      Specified by:
      fromRecord in interface RecordSerializable
      Parameters:
      source -
      Returns:
      this instance.

    • toXmlElement

      public Element toXmlElement(Document document)
      Description copied from interface: XmlSerializable
      Returns an element, created with document, describing this object; the default implementation throws a DataException.
      Specified by:
      toXmlElement in interface XmlSerializable

    • fromXmlElement

      public FieldPath fromXmlElement(Element element)
      Specified by:
      fromXmlElement in interface XmlSerializable

    • fromXml

      public FieldPath fromXml(InputStream inputStream)
      Description copied from interface: XmlSerializable
      Parses the XML in the stream and loads this object's state from its root element.
      Specified by:
      fromXml in interface XmlSerializable

    • fromXml

      public FieldPath fromXml(String xml)
      Specified by:
      fromXml in interface XmlSerializable

    • fromJson

      public FieldPath fromJson(InputStream inputStream)
      Description copied from interface: JsonSerializable
      Loads this object's state from the UTF-8 encoded JSON in the stream.
      Specified by:
      fromJson in interface JsonSerializable
      Specified by:
      fromJson in interface RecordSerializable

    • fromJson

      public FieldPath fromJson(String json)
      Description copied from interface: JsonSerializable
      Loads this object's state from the given JSON text.
      Specified by:
      fromJson in interface JsonSerializable
      Specified by:
      fromJson in interface RecordSerializable

    • generateJavaCode

      public void generateJavaCode(JavaCodeBuilder javaCodeBuilder)
      Description copied from interface: JavaCodeGenerator
      Appends Java source code representing this object to the given builder.
      Specified by:
      generateJavaCode in interface JavaCodeGenerator