Package uk.ac.starlink.topcat

## Class TopcatJELEvaluator

- java.lang.Object
- - uk.ac.starlink.topcat.TopcatJELEvaluator

- All Implemented Interfaces:
    `java.io.Closeable`, `java.lang.AutoCloseable`

      public abstract class TopcatJELEvaluator
      extends java.lang.Object
      implements java.io.Closeable

  Random-access evaluator for a JEL expression evaluated against a TopcatModel.

  Note this is more or less a copy of `RandomJELEvaluator`. It's very difficult to make that code reusable here because this class needs to use a TopcatJELRowReader rather than a StarTableRowReader (enhanced expression parsing, e.g. RowSubsets) and the differing functionality is implemented using inheritance rather than composition. The right thing would probably be to rework the JEL usage to use composition, but it's not straightforward. Live with duplicated code instead.

  Since:
    11 Dec 2020
  Author:
    Mark Taylor

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TopcatJELEvaluator()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static TopcatJELEvaluator` | `createEvaluator​(TopcatModel tcModel, java.lang.String expr, boolean activation, java.lang.Class<?> reqType)` | Returns a TopcatJELEvaluator instance for a given table and expression.
    `abstract boolean` | `evaluateBoolean​(long lrow)` | Returns the value of the expression at a given table row as a boolean.
    `abstract double` | `evaluateDouble​(long lrow)` | Returns the value of the expression at a given table row as a double.
    `abstract java.lang.Object` | `evaluateObject​(long lrow)` | Returns the value of the expression at a given table row as an Object.
    `abstract java.lang.String` | `getExpression()` | Returns the text of the expression that this evaluator can evaluate.
    `abstract java.lang.Class<?>` | `getResultType()` | Returns the actual result type that JEL has determined the compiled expression to have.

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

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

    - ### Methods inherited from interface java.io.Closeable

      `close`

- - ### Constructor Detail

    - #### TopcatJELEvaluator

          public TopcatJELEvaluator()

  - ### Method Detail

    - #### getExpression

          public abstract java.lang.String getExpression()

      Returns the text of the expression that this evaluator can evaluate.
      Returns:
        expression

    - #### getResultType

          public abstract java.lang.Class<?> getResultType()

      Returns the actual result type that JEL has determined the compiled expression to have. This will be (at least compatible with) the return type of the evaluations. It will return wrapper types, not primitive types.
      Returns:
        non-primitive result type

    - #### evaluateObject

          public abstract java.lang.Object evaluateObject​(long lrow)
                                                   throws java.io.IOException

      Returns the value of the expression at a given table row as an Object.
      Parameters:
        `lrow` - evaluation row index
      Returns:
        object value at given row
      Throws:
        `java.io.IOException`

    - #### evaluateDouble

          public abstract double evaluateDouble​(long lrow)
                                         throws java.io.IOException

      Returns the value of the expression at a given table row as a double. Behaviour is undefined if the expression is not numeric.
      Parameters:
        `lrow` - evaluation row index
      Returns:
        numeric value at given row
      Throws:
        `java.io.IOException`

    - #### evaluateBoolean

          public abstract boolean evaluateBoolean​(long lrow)
                                           throws java.io.IOException

      Returns the value of the expression at a given table row as a boolean. Behaviour is undefined if the expression is not boolean-typed.
      Parameters:
        `lrow` - evaluation row index
      Returns:
        boolean value at given row
      Throws:
        `java.io.IOException`

    - #### createEvaluator

          public static TopcatJELEvaluator createEvaluator​(TopcatModel tcModel,
                                                           java.lang.String expr,
                                                           boolean activation,
                                                           java.lang.Class<?> reqType)
                                                    throws gnu.jel.CompilationException

      Returns a TopcatJELEvaluator instance for a given table and expression. The returned implementation is suitable for use from multiple threads concurrently.
      Parameters:
        `tcModel` - context for expression evaluation
        `expr` - JEL expression
        `activation` - true to include activation functions
        `reqType` - required result type, or null to accept any
      Returns:
        evaluator safe for concurrent use
      Throws:
        `gnu.jel.CompilationException` - if the expression doesn't compile or doesn't have the (non-null) required type