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

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

JELRowReader()
Constructor.

Method Summary

Object	evaluate(gnu.jel.CompiledExpression compEx) Evaluates a given compiled expression at the current row.
double	evaluateDouble(gnu.jel.CompiledExpression compEx) Evaluates a given compiled expression at the given 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)
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.

Parameters:

icol - column index

Returns:

value class

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

evaluateDouble

public double evaluateDouble(gnu.jel.CompiledExpression compEx)
                      throws Throwable

Evaluates a given compiled expression at the given 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

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"

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