JELRowReader (Starlink-UK API)

java.lang.Object
- gnu.jel.DVMap
- - uk.ac.starlink.ttools.jel.JELRowReader

Direct Known Subclasses:

ResultSetJELRowReader, StarTableJELRowReader, TablelessJELRowReader
```
public abstract class JELRowReader
extends gnu.jel.DVMap
```
An object which is able to read cell values by column name or number. The values are got using the evaluate(gnu.jel.CompiledExpression) method.
This class currently deals with columns of all the primitive types, objects of type String or Date, and arrays of any of these. Anything else is treated as an Object or Object[]. It could be extended to deal with more if necessary.
Expressions of the following types are understood:

"null":
the null value (this is not provided as part of the JEL engine).
"NULL":
if this expression is evaluated at any point in the expression evaluation, then the result of the whole evaluation will be null. This has the same effect as throwing a NullPointerException during evaluation. The NULL token is syntactically of type byte, which can be promoted implicitly to any numeric value; this means it can be used anywhere a primitive (other than boolean) can be used.
Column $ID identifiers:
The letter '$' followed by the 1-based index of the column refers to the contents of that column in the current row (as a primitive, if applicable).
Column names:
The name of a column (case-insensitive) refers to the contents of that column in the current row (as a primitive, if applicable) - this can only work if the column name is a legal java identifier.
Null queries:
The string "NULL_" followed by a value identifier (column name, column $ID or parameter identifier - see above) returns a boolean value which is true iff the corresponding value (at the current row, if applicable) has a blank value.
Object values:
The string "Object$" followed by a column name or column $ID returns the contents of the identified column in the current row. It is returned as an Object not a primitive (using a wrapper class if necessary). The expression has type Object. This can be useful for passing to functions that need to know whether a null value is present (which cannot be represented in primitive types).

Author:

Mark Taylor (Starlink)

Field Summary

Fields
Modifier and Type	Field and Description
`static char`	`COLUMN_ID_CHAR` Prefix identifying a unique column identifier.
`static String`	`NULL_QUERY_PREFIX` The string which, when prefixed to a column identifier, indicates that the null-ness of the column should be queried.
`static String`	`OBJECT_PREFIX` The string which, when prefixed to a column identifier, indicates that the value is required as an Object not a primitive.

Constructor Summary

Constructors
Constructor and Description

JELRowReader()
Constructor.

Constructors
Constructor and Description
`JELRowReader()` Constructor.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`Object`	`evaluate(gnu.jel.CompiledExpression compEx)` Evaluates a given compiled expression at the current row.
`boolean`	`evaluateBoolean(gnu.jel.CompiledExpression compEx)` Evaluates a given compiled expression at the current row under the assumption that the expression represents a boolean value.
`double`	`evaluateDouble(gnu.jel.CompiledExpression compEx)` Evaluates a given compiled expression at the current row under the assumption that the expression represents a numeric value.
`protected void`	`foundNull()` Must be called by any of the `getObjectColumnValue` methods which wants to return a `null` but has to return a primitive instead.
`boolean[]`	`getBooleanArrayProperty(int id)`
`protected abstract boolean`	`getBooleanColumnValue(int icol)` Returns a boolean value for a cell of the current row.
`boolean`	`getBooleanProperty(int id)`
`boolean`	`getBooleanProperty(long inul)` Indicates whether the cell at the current row in a given column has a blank value.
`boolean`	`getBooleanValue(Boolean value)`
`byte[]`	`getByteArrayProperty(int id)`
`protected abstract byte`	`getByteColumnValue(int icol)` Returns a byte value for a cell of the current row.
`byte`	`getByteProperty(int id)`
`byte`	`getByteValue(Byte value)`
`char[]`	`getCharArrayProperty(int id)`
`protected abstract char`	`getCharColumnValue(int icol)` Returns a char value for a cell of the current row.
`char`	`getCharProperty(int id)`
`char`	`getCharValue(Character value)`
`protected abstract Class<?>`	`getColumnClass(int icol)` Returns the class of values returned by a given column.
`int`	`getColumnIndex(String name)` Returns the column index in the table model which corresponds to a given name.
`protected abstract int`	`getColumnIndexByName(String name)` Returns the column index of a column in the row given its name.
`protected abstract Constant<?>`	`getConstantByName(String name)` Returns a constant value for this reader given its name.
`Date[]`	`getDateArrayProperty(int id)`
`double[]`	`getDoubleArrayProperty(int id)`
`protected abstract double`	`getDoubleColumnValue(int icol)` Returns a double value for a cell of the current row.
`double`	`getDoubleProperty(int id)`
`double`	`getDoubleValue(Double value)`
`float[]`	`getFloatArrayProperty(int id)`
`protected abstract float`	`getFloatColumnValue(int icol)` Returns a float value for a cell of the current row.
`float`	`getFloatProperty(int id)`
`float`	`getFloatValue(Float value)`
`int[]`	`getIntArrayProperty(int id)`
`protected abstract int`	`getIntColumnValue(int icol)` Returns a int value for a cell of the current row.
`int`	`getIntProperty(int id)`
`int`	`getIntValue(Integer value)`
`long[]`	`getLongArrayProperty(int id)`
`protected abstract long`	`getLongColumnValue(int icol)` Returns a long value for a cell of the current row.
`long`	`getLongProperty(int id)`
`long`	`getLongValue(Long value)`
`Number`	`getNumberProperty(int id)`
`Object[]`	`getObjectArrayProperty(int id)`
`protected abstract Object`	`getObjectColumnValue(int icol)` Returns an Object value for a cell of the current row.
`Object`	`getObjectProperty(int id)`
`short[]`	`getShortArrayProperty(int id)`
`protected abstract short`	`getShortColumnValue(int icol)` Returns a short value for a cell of the current row.
`short`	`getShortProperty(int id)`
`short`	`getShortValue(Short value)`
`protected Constant<?>`	`getSpecialByName(String name)` Returns the a special quantity which corresponds to a given name, or null if it isn't a special.
`String[]`	`getStringArrayProperty(int id)`
`String`	`getStringProperty(int id)`
`int[]`	`getTranslatedColumns()` Returns a set (no duplicated elements) of the column indices for which this RowReader has been asked to provide translation values.
`Constant<?>[]`	`getTranslatedConstants()` Returns a list of the constants for which this RowReader has been asked to provide translation values.
`String`	`getTypeName(String name)` Returns the type name of the quantity which is referenced in expressions with a given name.
`protected abstract boolean`	`isBlank(int icol)` Indicates whether the value in a given column is null.
`void`	`setFailOnNull(boolean failOnNull)` Configures the behaviour when a primitive integer or boolean value passed as an argument to a function for evaluation is represented by a null value in the column.
`static String`	`stripPrefix(String name, String prefix)` Takes a token and strips a given prefix from it, returning the remainder.
`Object`	`translate(String name)` Turns a value specification into a constant object which can be used at evaluation time to reference a particular quantity to evaluate.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NULL_QUERY_PREFIX
```
public static final String NULL_QUERY_PREFIX
```
    The string which, when prefixed to a column identifier, indicates that the null-ness of the column should be queried.
    
    See Also:
    
    Constant Field Values
  - OBJECT_PREFIX
```
public static final String OBJECT_PREFIX
```
    The string which, when prefixed to a column identifier, indicates that the value is required as an Object not a primitive.
    
    See Also:
    
    Constant Field Values
  - COLUMN_ID_CHAR
```
public static final char COLUMN_ID_CHAR
```
    Prefix identifying a unique column identifier.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - JELRowReader
```
public JELRowReader()
```
    Constructor.
- Method Detail
  - setFailOnNull
```
public void setFailOnNull(boolean failOnNull)
```
    Configures the behaviour when a primitive integer or boolean value passed as an argument to a function for evaluation is represented by a null value in the column. If failOnNull is set false, then zero values are sent to the function, but the result of the evaluation is just returned as null. If failOnNull is set true, then a NullPointerException is thrown as soon as the substitution is attempted. False is generally much faster, since throwing exceptions is expensive. However, if it is important that the function is not evaluated at all with wrong arguments (zeroes instead of nulls), for instance because of side-effects, you can set it true.
    The default behaviour is false.
    
    Parameters:
    
    failOnNull - failOnNull flag
  - getColumnIndexByName
```
protected abstract int getColumnIndexByName(String name)
```
    Returns the column index of a column in the row given its name. If name does not refer to any known column, return -1.
    
    Parameters:
    
    name - column name
    
    Returns:
    
    column index, or -1
  - getConstantByName
```
protected abstract Constant<?> getConstantByName(String name)
```
    Returns a constant value for this reader given its name.
    
    Parameters:
    
    name - constant name
    
    Returns:
    
    constant, or null
  - isBlank
```
protected abstract boolean isBlank(int icol)
```
    Indicates whether the value in a given column is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    true if value at icol is null
  - getColumnClass
```
protected abstract Class<?> getColumnClass(int icol)
```
    Returns the class of values returned by a given column. If no column with the given index exists, null should be returned.
    
    Parameters:
    
    icol - non-negative column index
    
    Returns:
    
    value class, or null for non-existent column
  - getBooleanColumnValue
```
protected abstract boolean getBooleanColumnValue(int icol)
```
    Returns a boolean value for a cell of the current row. Will only be called if the relevant column is declared boolean. Must call foundNull() (and return any value) if the result is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - getByteColumnValue
```
protected abstract byte getByteColumnValue(int icol)
```
    Returns a byte value for a cell of the current row. Will only be called if the relevant column is declared byte. Must call foundNull() (and return any value) if the result is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - getCharColumnValue
```
protected abstract char getCharColumnValue(int icol)
```
    Returns a char value for a cell of the current row. Will only be called if the relevant column is declared char. Must call foundNull() (and return any value) if the result is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - getShortColumnValue
```
protected abstract short getShortColumnValue(int icol)
```
    Returns a short value for a cell of the current row. Will only be called if the relevant column is declared short. Must call foundNull() (and return any value) if the result is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - getIntColumnValue
```
protected abstract int getIntColumnValue(int icol)
```
    Returns a int value for a cell of the current row. Will only be called if the relevant column is declared int. Must call foundNull() (and return any value) if the result is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - getLongColumnValue
```
protected abstract long getLongColumnValue(int icol)
```
    Returns a long value for a cell of the current row. Will only be called if the relevant column is declared long. Must call foundNull() (and return any value) if the result is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - getFloatColumnValue
```
protected abstract float getFloatColumnValue(int icol)
```
    Returns a float value for a cell of the current row. Will only be called if the relevant column is declared float. Must call foundNull() (and return any value) if the result is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - getDoubleColumnValue
```
protected abstract double getDoubleColumnValue(int icol)
```
    Returns a double value for a cell of the current row. Will only be called if the relevant column is declared double. Must call foundNull() (and return any value) if the result is null.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - getObjectColumnValue
```
protected abstract Object getObjectColumnValue(int icol)
```
    Returns an Object value for a cell of the current row.
    
    Parameters:
    
    icol - column index
    
    Returns:
    
    value
  - foundNull
```
protected void foundNull()
```
    Must be called by any of the getObjectColumnValue methods which wants to return a null but has to return a primitive instead.
  - getSpecialByName
```
protected Constant<?> getSpecialByName(String name)
```
    Returns the a special quantity which corresponds to a given name, or null if it isn't a special. Specials are much like constants but they are checked for earlier.
    The current specials are:
    - "null" returns the null value (this is not built in to the JEL evaluator)
    - "NULL" flags that an attempt has been made to evaluate a primitive with no value, and thus invalidates the rest of the evaluation
    Parameters:
    
    name - special name
    
    Returns:
    
    special, or null
  - evaluate
```
public Object evaluate(gnu.jel.CompiledExpression compEx)
                throws Throwable
```
    Evaluates a given compiled expression at the current row. The returned value is wrapped up as an object if the result of the expression is a primitive.
    
    Parameters:
    
    compEx - compiled expression
    
    Returns:
    
    expression value at current row
    
    Throws:
    
    Throwable
  - evaluateBoolean
```
public boolean evaluateBoolean(gnu.jel.CompiledExpression compEx)
                        throws Throwable
```
    Evaluates a given compiled expression at the current row under the assumption that the expression represents a boolean value. The returned value is a boolean. If a null value was encountered during evaluation, or the expression is not boolean-valued, false is returned.
    
    Parameters:
    
    compEx - numeric-valued compiled expression
    
    Returns:
    
    expression value at current row
    
    Throws:
    
    Throwable
  - evaluateDouble
```
public double evaluateDouble(gnu.jel.CompiledExpression compEx)
                      throws Throwable
```
    Evaluates a given compiled expression at the current row under the assumption that the expression represents a numeric value. The returned value is a double. If a null value was encountered during evaluation, or the expression is not numeric, a NaN is returned.
    
    Parameters:
    
    compEx - numeric-valued compiled expression
    
    Returns:
    
    expression value at current row
    
    Throws:
    
    Throwable
  - getTypeName
```
public String getTypeName(String name)
```
    Returns the type name of the quantity which is referenced in expressions with a given name. The significance of this return value is that it appears in the names of the corresponding getXXXProperty methods in this class.
    
    Specified by:
    
    getTypeName in class gnu.jel.DVMap
    
    Parameters:
    
    name - the variable name
    
    Returns:
    
    the corresponding method name fragment
    
    See Also:
    
    "JEL manual"
  - translate
```
public Object translate(String name)
```
    Turns a value specification into a constant object which can be used at evaluation time to reference a particular quantity to evaluate. Currently this routine returns
    - a non-negative Integer object (the column index) if name appears to reference a known column
    - a negative Integer object (-1-constIndex) if name appears to reference a known constant
    - a Long object if it is a null query on a known column
    - null otherwise
    The different integral types are only used to separate the namespaces, there is no other significance in these types.
    This method is only called at expression compilation time, not evaluation time, so it doesn't need to be particularly fast.
    Overrides:
    
    translate in class gnu.jel.DVMap
    
    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"
  - getTranslatedConstants
```
public Constant<?>[] getTranslatedConstants()
```
    Returns a list of the constants for which this RowReader has been asked to provide translation values. In practice this means there will be an entry for every constant in expressions which this RowReader has been used to compile.
    
    Returns:
    
    list of constants which this row reader has had to reference in compiling JEL expressions
  - getTranslatedColumns
```
public int[] getTranslatedColumns()
```
    Returns a set (no duplicated elements) of the column indices for which this RowReader has been asked to provide translation values. In practice that means the index of every table column which has been directly referenced in a JEL expression which this RowReader has been used to compile.
    
    Returns:
    
    list of distinct column indices which this row reader has had to reference in compiling JEL expressions
  - getColumnIndex
```
public final int getColumnIndex(String name)
```
    Returns the column index in the table model which corresponds to a given name. The current formats are
    - column name (case insensitive, first occurrence used)
    - "$"+(index+1) (so first column would be "$1")
    Note that the name '$0' is reserved for the special index column.
    Note this method is only called during expression compilation, so it doesn't need to be particularly efficient.
    Parameters:
    
    name - column identifier
    
    Returns:
    
    column index, or -1 if the column was not known
  - getBooleanProperty
```
public boolean getBooleanProperty(long inul)
```
    Indicates whether the cell at the current row in a given column has a blank value. This is the case if the value is the java null reference, or if it is a Float or Double with a NaN value.
    
    Parameters:
    
    inul - column index (as a long)
    
    Returns:
    
    whether the cell is null
  - getBooleanProperty
```
public boolean getBooleanProperty(int id)
```
  - getByteProperty
```
public byte getByteProperty(int id)
```
  - getCharProperty
```
public char getCharProperty(int id)
```
  - getShortProperty
```
public short getShortProperty(int id)
```
  - getIntProperty
```
public int getIntProperty(int id)
```
  - getLongProperty
```
public long getLongProperty(int id)
```
  - getFloatProperty
```
public float getFloatProperty(int id)
```
  - getDoubleProperty
```
public double getDoubleProperty(int id)
```
  - getObjectProperty
```
public Object getObjectProperty(int id)
```
  - getNumberProperty
```
public Number getNumberProperty(int id)
```
  - getStringProperty
```
public String getStringProperty(int id)
```
  - getBooleanArrayProperty
```
public boolean[] getBooleanArrayProperty(int id)
```
  - getByteArrayProperty
```
public byte[] getByteArrayProperty(int id)
```
  - getCharArrayProperty
```
public char[] getCharArrayProperty(int id)
```
  - getShortArrayProperty
```
public short[] getShortArrayProperty(int id)
```
  - getIntArrayProperty
```
public int[] getIntArrayProperty(int id)
```
  - getLongArrayProperty
```
public long[] getLongArrayProperty(int id)
```
  - getFloatArrayProperty
```
public float[] getFloatArrayProperty(int id)
```
  - getDoubleArrayProperty
```
public double[] getDoubleArrayProperty(int id)
```
  - getObjectArrayProperty
```
public Object[] getObjectArrayProperty(int id)
```
  - getStringArrayProperty
```
public String[] getStringArrayProperty(int id)
```
  - getDateArrayProperty
```
public Date[] getDateArrayProperty(int id)
```
  - getBooleanValue
```
public boolean getBooleanValue(Boolean value)
```
  - getByteValue
```
public byte getByteValue(Byte value)
```
  - getCharValue
```
public char getCharValue(Character value)
```
  - getShortValue
```
public short getShortValue(Short value)
```
  - getIntValue
```
public int getIntValue(Integer value)
```
  - getLongValue
```
public long getLongValue(Long value)
```
  - getFloatValue
```
public float getFloatValue(Float value)
```
  - getDoubleValue
```
public double getDoubleValue(Double value)
```
  - stripPrefix
```
public static String stripPrefix(String name,
                                 String prefix)
```
    Takes a token and strips a given prefix from it, returning the remainder. If the given name does not begin with prefix (or if it is exactly equal to it), then null is returned.
    
    Parameters:
    
    name - token which may begin with prefix
    
    prefix - maybe matches the start of name
    
    Returns:
    
    name minux prefix, or null
    
    See Also:
    
    NULL_QUERY_PREFIX

Class JELRowReader

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NULL_QUERY_PREFIX

OBJECT_PREFIX

COLUMN_ID_CHAR

Constructor Detail

JELRowReader

Method Detail

setFailOnNull

getColumnIndexByName

getConstantByName

isBlank

getColumnClass

getBooleanColumnValue

getByteColumnValue

getCharColumnValue

getShortColumnValue

getIntColumnValue

getLongColumnValue

getFloatColumnValue

getDoubleColumnValue

getObjectColumnValue

foundNull

getSpecialByName

evaluate

evaluateBoolean

evaluateDouble

getTypeName

translate

getTranslatedConstants

getTranslatedColumns

getColumnIndex

getBooleanProperty

getBooleanProperty

getByteProperty

getCharProperty

getShortProperty

getIntProperty

getLongProperty

getFloatProperty

getDoubleProperty

getObjectProperty

getNumberProperty

getStringProperty

getBooleanArrayProperty

getByteArrayProperty

getCharArrayProperty

getShortArrayProperty

getIntArrayProperty

getLongArrayProperty

getFloatArrayProperty

getDoubleArrayProperty

getObjectArrayProperty

getStringArrayProperty

getDateArrayProperty

getBooleanValue

getByteValue

getCharValue

getShortValue

getIntValue

getLongValue

getFloatValue

getDoubleValue

stripPrefix