# Class TopcatJELEvaluator

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

All Implemented Interfaces:
  `Closeable, AutoCloseable`

public abstract class TopcatJELEvaluator extends Object implements 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

Modifier and Type
Method
Description
`static TopcatJELEvaluator`
`createEvaluator(TopcatModel tcModel, String expr, boolean activation, 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 Object`
`evaluateObject(long lrow)`
Returns the value of the expression at a given table row as an Object.
`abstract String`
`getExpression()`
Returns the text of the expression that this evaluator can evaluate.
`abstract Class<?>`
`getResultType()`
Returns the actual result type that JEL has determined the compiled expression to have.

### Methods inherited from class Object

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

### Methods inherited from interface Closeable

`close`

## Constructor Details

### TopcatJELEvaluator

public TopcatJELEvaluator()

## Method Details

### getExpression

public abstract String getExpression()
Returns the text of the expression that this evaluator can evaluate.

Returns:
  expression

### getResultType

public abstract 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 Object evaluateObject(long lrow) throws 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:
  `IOException`

### evaluateDouble

public abstract double evaluateDouble(long lrow) throws 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:
  `IOException`

### evaluateBoolean

public abstract boolean evaluateBoolean(long lrow) throws 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:
  `IOException`

### createEvaluator

public static TopcatJELEvaluator createEvaluator(TopcatModel tcModel, String expr, boolean activation, 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