Package uk.ac.starlink.ttools.jel
Class JELRowReader
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
FieldsModifier and TypeFieldDescriptionstatic final char
Prefix identifying a unique column identifier.static final String
The string which, when prefixed to a column identifier, indicates that the null-ness of the column should be queried.static final String
The string which, when prefixed to a column identifier, indicates that the value is required as an Object not a primitive. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionevaluate
(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
Must be called by any of thegetObjectColumnValue
methods which wants to return anull
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.final 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) getNumberProperty
(int id) Object[]
getObjectArrayProperty
(int id) protected abstract Object
getObjectColumnValue
(int icol) Returns an Object value for a cell of the current row.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) getStringProperty
(int id) int[]
Returns a set (no duplicated elements) of the column indices for which this RowReader has been asked to provide translation values.Constant<?>[]
Returns a list of the constants for which this RowReader has been asked to provide translation values.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.Turns a value specification into a constant object which can be used at evaluation time to reference a particular quantity to evaluate.
-
Field Details
-
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:
-
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:
-
COLUMN_ID_CHAR
public static final char COLUMN_ID_CHARPrefix identifying a unique column identifier.- See Also:
-
-
Constructor Details
-
JELRowReader
public JELRowReader()Constructor.
-
-
Method Details
-
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
Returns the column index of a column in the row given its name. Ifname
does not refer to any known column, return -1.- Parameters:
name
- column name- Returns:
- column index, or -1
-
getConstantByName
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
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 callfoundNull()
(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 callfoundNull()
(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 callfoundNull()
(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 callfoundNull()
(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 callfoundNull()
(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 callfoundNull()
(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 callfoundNull()
(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 callfoundNull()
(and return any value) if the result is null.- Parameters:
icol
- column index- Returns:
- value
-
getObjectColumnValue
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 thegetObjectColumnValue
methods which wants to return anull
but has to return a primitive instead. -
getSpecialByName
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
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
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, false is returned.- Parameters:
compEx
- numeric-valued compiled expression- Returns:
- expression value at current row
- Throws:
Throwable
-
evaluateDouble
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, a NaN is returned.- Parameters:
compEx
- numeric-valued compiled expression- Returns:
- expression value at current row
- Throws:
Throwable
-
getTypeName
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 classgnu.jel.DVMap
- Parameters:
name
- the variable name- Returns:
- the corresponding method name fragment
- See Also:
-
- "JEL manual"
-
translate
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
This method is only called at expression compilation time, not evaluation time, so it doesn't need to be particularly fast.
- Overrides:
translate
in classgnu.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
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
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 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
-
getNumberProperty
-
getStringProperty
-
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
-
getStringArrayProperty
-
getDateArrayProperty
-
getBooleanValue
-
getByteValue
-
getCharValue
-
getShortValue
-
getIntValue
-
getLongValue
-
getFloatValue
-
getDoubleValue
-
stripPrefix
Takes a token and strips a given prefix from it, returning the remainder. If the givenname
does not begin withprefix
(or if it is exactly equal to it), thennull
is returned.- Parameters:
name
- token which may begin withprefix
prefix
- maybe matches the start ofname
- Returns:
name
minuxprefix
, ornull
- See Also:
-