Package uk.ac.starlink.topcat

## Class TopcatJELRowReader

- java.lang.Object
- - gnu.jel.DVMap
  - - uk.ac.starlink.ttools.jel.JELRowReader
    - - uk.ac.starlink.ttools.jel.StarTableJELRowReader
      - - uk.ac.starlink.ttools.jel.RandomJELRowReader
        - - uk.ac.starlink.topcat.TopcatJELRowReader

-     public abstract class TopcatJELRowReader
      extends uk.ac.starlink.ttools.jel.RandomJELRowReader

  Random JELRowReader with which recognises some expressions in addition to those of the superclass.
  Row Subset _ID identifiers:
    The character '_' followed by the 1-based index of a defined row subset returns true iff the current row is part of the subset.
  Row Subset names:
    The name of a subset (case-insensitive) returns true iff the current row is part of the named subset.
  Apparent table index:
    The tokens "`$index0`" or "`$00`" (case insensitive) are evaluated as the index of the current row in the apparent table; this differs from `$index`/`$0` if a non-default sort order or current subset is in force.
  Apparent table row count:
    The token "`$nrow0`" is the number of rows in the apparent table; this differs from `$nrow` if a non-default current subset is in force.
  Apparent table column count:
    The token "`$ncol0` is the number of columns in the apparent table; this differs from `$ncol` if some columns are hidden.
  Since:
    8 Feb 2005
  Author:
    Mark Taylor (Starlink)

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static char` | `SUBSET_ID_CHAR` | Prefix identifying a unique subset identifier.

    - ### Fields inherited from class uk.ac.starlink.ttools.jel.StarTableJELRowReader

      `PARAM_PREFIX, UCD_PREFIX, UTYPE_PREFIX`

    - ### Fields inherited from class uk.ac.starlink.ttools.jel.JELRowReader

      `COLUMN_ID_CHAR, NULL_QUERY_PREFIX, OBJECT_PREFIX`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `TopcatJELRowReader​(TopcatModel tcModel)` | Constructs a new row reader for a TopcatModel.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static TopcatJELRowReader` | `createAccessReader​(TopcatModel tcModel)` | Returns a reader that uses a RowAccess object from the TopcatModel's data model.
    `static TopcatJELRowReader` | `createConcurrentReader​(TopcatModel tcModel)` | Returns a reader that uses the threadsafe random access methods of the TopcatModel's data model.
    `protected uk.ac.starlink.ttools.jel.Constant<?>` | `createDescribedValueConstant​(uk.ac.starlink.table.DescribedValue dval)` | Returns a constant which is evaluated at runtime.
    `static TopcatJELRowReader` | `createDummyReader​(TopcatModel tcModel)` | Returns a reader that doesn't do any actual data access.
    `abstract boolean` | `evaluateBooleanAtRow​(gnu.jel.CompiledExpression compEx, long lrow)` | Evaluates a given compiled expression of boolean return type at a given row.
    `boolean` | `getBooleanProperty​(short isub)` | Returns the actual subset value for the current row and a given column.
    `protected uk.ac.starlink.ttools.jel.Constant<?>` | `getSpecialByName​(java.lang.String name)` |
    `TopcatModel` | `getTopcatModel()` | Returns the topcat model on which this row reader is based.
    `int[]` | `getTranslatedSubsetIds()` | Returns a set (no duplicated elements) of the subset IDs for which this RowReader has been asked to provide translation values.
    `java.lang.String` | `getTypeName​(java.lang.String name)` | Overrides superclass implementation to recognise row subsets by name or _ID.
    `java.lang.Object` | `translate​(java.lang.String name)` | Overrides superclass implementation to recognise subsets as well as the other special objects.

    - ### Methods inherited from class uk.ac.starlink.ttools.jel.RandomJELRowReader

      `createAccessReader, createAccessReader, createConcurrentReader, evaluateAtRow`

    - ### Methods inherited from class uk.ac.starlink.ttools.jel.StarTableJELRowReader

      `getBooleanColumnValue, getByteColumnValue, getCell, getCharColumnValue, getColumnClass, getColumnIndexByName, getConstantByName, getCurrentRow, getDoubleColumnValue, getFloatColumnValue, getIntColumnValue, getLongColumnValue, getObjectColumnValue, getShortColumnValue, getTable, getUcdRegex, getUtypeRegex, isBlank, requiresRowIndex`

    - ### Methods inherited from class uk.ac.starlink.ttools.jel.JELRowReader

      `evaluate, evaluateBoolean, evaluateDouble, foundNull, getBooleanArrayProperty, getBooleanProperty, getBooleanProperty, getBooleanValue, getByteArrayProperty, getByteProperty, getByteValue, getCharArrayProperty, getCharProperty, getCharValue, getColumnIndex, getDateArrayProperty, getDoubleArrayProperty, getDoubleProperty, getDoubleValue, getFloatArrayProperty, getFloatProperty, getFloatValue, getIntArrayProperty, getIntProperty, getIntValue, getLongArrayProperty, getLongProperty, getLongValue, getNumberProperty, getObjectArrayProperty, getObjectProperty, getShortArrayProperty, getShortProperty, getShortValue, getStringArrayProperty, getStringProperty, getTranslatedColumns, getTranslatedConstants, setFailOnNull, stripPrefix`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SUBSET_ID_CHAR

          public static final char SUBSET_ID_CHAR

      Prefix identifying a unique subset identifier.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TopcatJELRowReader

          protected TopcatJELRowReader​(TopcatModel tcModel)

      Constructs a new row reader for a TopcatModel.
      Parameters:
        `tcModel` - topcat model

  - ### Method Detail

    - #### getTopcatModel

          public TopcatModel getTopcatModel()

      Returns the topcat model on which this row reader is based.
      Returns:
        topcat model

    - #### evaluateBooleanAtRow

          public abstract boolean evaluateBooleanAtRow​(gnu.jel.CompiledExpression compEx,
                                                       long lrow)
                                                throws java.lang.Throwable

      Evaluates a given compiled expression of boolean return type at a given row.
      Parameters:
        `compEx` - compiled boolean expression
        `lrow` - row at which to evaluate
      Returns:
        expression value
      Throws:
        `java.lang.Throwable`

    - #### getTypeName

          public java.lang.String getTypeName​(java.lang.String name)

      Overrides superclass implementation to recognise row subsets by name or _ID.
      Overrides:
        `getTypeName` in class `uk.ac.starlink.ttools.jel.JELRowReader`
      Parameters:
        `name` - the variable name
      Returns:
        corresponding method name fragment
      See Also:
        "JEL manual"

    - #### translate

          public java.lang.Object translate​(java.lang.String name)

      Overrides superclass implementation to recognise subsets as well as the other special objects. The additional return type is:
      - a `Short` (the subset index) if the column specification appears to reference a known row subset
      Overrides:
        `translate` in class `uk.ac.starlink.ttools.jel.JELRowReader`
      Parameters:
        `name` - the name of the variable-like object to evaluate
      Returns:
        a numeric object corresponding to an object which we know how to evaluate
      See Also:
        "JEL manual"

    - #### getTranslatedSubsetIds

          public int[] getTranslatedSubsetIds()

      Returns a set (no duplicated elements) of the subset IDs for which this RowReader has been asked to provide translation values. In practice that means the ID (in the sense of the `OptionsListModel` returned by `TopcatModel.getSubsets`) of every RowSubset which has been directly referenced in a JEL expression which this RowReader has been used to compile.
      Returns:
        list of distinct subset IDs which this row reader has had to reference in compiling JEL expressions

    - #### getBooleanProperty

          public boolean getBooleanProperty​(short isub)

      Returns the actual subset value for the current row and a given column.
      Parameters:
        `isub` - index of the subset to evaluate at the current row
      Returns:
        result of the `isIncluded` method of the `RowSubset` indicated at the current row

    - #### getSpecialByName

          protected uk.ac.starlink.ttools.jel.Constant<?> getSpecialByName​(java.lang.String name)

      Overrides:
        `getSpecialByName` in class `uk.ac.starlink.ttools.jel.StarTableJELRowReader`

    - #### createDescribedValueConstant

          protected uk.ac.starlink.ttools.jel.Constant<?> createDescribedValueConstant​(uk.ac.starlink.table.DescribedValue dval)

      Returns a constant which is evaluated at runtime. This is more appropriate than the inherited (evaluate at call time) behaviour, since within TOPCAT the constant's value may change as a result of user intervention during the lifetime of the returned object.
      Overrides:
        `createDescribedValueConstant` in class `uk.ac.starlink.ttools.jel.StarTableJELRowReader`

    - #### createConcurrentReader

          public static TopcatJELRowReader createConcurrentReader​(TopcatModel tcModel)

      Returns a reader that uses the threadsafe random access methods of the TopcatModel's data model.
      Parameters:
        `tcModel` - topcat model
      Returns:
        threadsafe row reader

    - #### createAccessReader

          public static TopcatJELRowReader createAccessReader​(TopcatModel tcModel)

      Returns a reader that uses a RowAccess object from the TopcatModel's data model.
      Parameters:
        `tcModel` - topcat model
      Returns:
        row reader suitable for use only within a single thread

    - #### createDummyReader

          public static TopcatJELRowReader createDummyReader​(TopcatModel tcModel)

      Returns a reader that doesn't do any actual data access. Suitable for testing compilation success etc.
      Parameters:
        `tcModel` - topcat model
      Returns:
        row reader that throws UnsupportedOperationException for data access methods