Module org.postgresql.pljava
Package org.postgresql.pljava

Interface TargetList.Cursor

All Superinterfaces:
Iterable<TargetList.Cursor>, Iterator<Attribute>
Enclosing interface:
TargetList
public static interface TargetList.Cursor extends Iterator<Attribute>, Iterable<TargetList.Cursor>
A TargetList that has been bound to a source of tuples and can execute code with the wanted attribute values available.

Being derived from a TargetList, a Cursor serves directly as an Iterator<Attribute>, supplying the attributes in the TargetList order.

Being bound to a source of tuples, a Cursor also implements Iterable, and can supply an iterator over the bound tuples in order. The Cursor is mutated during the iteration, having a current row that becomes each tuple in turn. The object returned by that iterator is the Cursor itself, so the caller has no need for the iteration variable, and can use the "unnamed variable" _ for it, in Java versions including that feature (which appears in Java 21 but only with --enable-preview). In older Java versions it can be given some other obviously throwaway name.

When a Cursor has a current row, its apply methods can be used to execute a lambda body with its parameters mapped to the row's values, in TargetList order, or to a prefix of those, should a lambda with fewer parameters be supplied.

Each overload of apply takes some number of Adapter instances, each of which must be suited to the PostgreSQL type at its corresponding position, followed by a lambda body with the same number of parameters, each of which will receive the value from the corresponding Adapter, and have an inferred type matching what that Adapter produces.

Within a lambda body with fewer parameters than the length of the TargetList, the Cursor's attribute iterator has been advanced by the number of columns consumed. It can be used again to apply an inner lambda body to remaining columns. This "curried" style can be useful when the number or types of values to be processed will not directly fit any available apply signature. 

  overall_result = targetlist.applyOver(tuples, c ->
  {
      var resultCollector = ...;
      for ( Cursor _ : c )
      {
          var oneResult = c.apply(
              adap0, adap1,
             ( val0,  val1 ) -> c.apply(
                  adap2, adap3,
                 ( val2,  val3 ) -> process(val0, val1, val2, val3)));
          resultCollector.collect(oneResult);
      }
      return resultCollector;
  });

As the apply overloads for reference-typed values and those for primitive values are separate, currying must be used when processing a mix of reference and primitive types.

The Cursor's attribute iterator is reset each time the tuple iterator moves to a new tuple. It is also reset on return (normal or exceptional) from an outermost apply, in case another function should then be applied to the row.

The attribute iterator is not reset on return from an inner (curried) apply. Therefore, it is possible to process a tuple having repeating groups of attributes with matching types, reusing an inner lambda and its matching adapters for each occurrence of the group.

If the tuple is nothing but repeating groups, the effect can still be achieved by using the zero-parameter apply overload as the outermost.