uk.ac.starlink.ttools.jel

Class StarTableJELRowReader

java.lang.Object

gnu.jel.DVMap

uk.ac.starlink.ttools.jel.JELRowReader

uk.ac.starlink.ttools.jel.StarTableJELRowReader

Direct Known Subclasses:

DummyJELRowReader, RandomJELRowReader, SequentialJELRowReader

public abstract class StarTableJELRowReader
extends JELRowReader

JELRowReader subclass for access to StarTables.

In addition to the syntax provided by the superclass, the following symbols are understood:

"$0" or "$index" or (deprecated) "index" (case insensitive):

the 1-based index of the current row.

"$ncol"

Number of columns in the table.

"$nrow"

Number of rows in the table. If this is not known, a null value is returned.

Parameter names:

The string "param$" followed by the name of a table parameter (case-insensitive) is a constant for the table (as a primitive, if applicable). This can only work if the parameter name is a legal java identifier.

UCD specifiers:

The string "ucd$" followed by the text of a UCD giving the required value. Any punctuation (such as ".", ";", "-") in the UCD should be replaced with a "_" (since these symbols cannot appear in identifiers). If the identifier has a trailing "_", then any UCD which starts as specified is considered to match. The first matching column, or if there is none the first matching parameter value is returned. UCD matching is case-insensitive.

Utype specifiers:

The string "utype$" followed by the text of a Utype identifying the required value. Any punctuation (such as ".", ":", "-") in the Utype should be replaced with a "_" (since these symbols cannot appear in identifiers). The first matching column, or if there is none the first matching parameter value is returned. UType matching is case-insensitive.

"$random" (case insensitive) or (deprecated) "RANDOM":

The special token "$random" evaluates to a double-precision random number 0<=x<1 which is constant for a given row within this reader. The quality of the random numbers may not be particularly good.

"value*()" functions:

The methods valueDouble, valueInt, valueLong, valueString and valueObject are provided. Each takes as an argument an exact column name, and provides the typed value of the column at the current row. These methods are not the generally recommended way to access column values; they are slower and less tidy than simply using column names or $IDs in expressions, and do not admit of static analysis, so their use can not be reflected in the results of getTranslatedColumns. However, it does allow access by column name to columns with names that are not legal java identifiers.

Since:

7 Dec 2007

Author:

Mark Taylor

Field Summary

Fields

Modifier and Type	Field and Description
static String	PARAM_PREFIX The string which should be prefixed to a table parameter (constant) name to result in substituting its value.
static String	UCD_PREFIX A string to prefix to a UCD string to indicate the column/parameter with that UCD.
static String	UTYPE_PREFIX A string to prefix to a Utype string to indicate the column/parameter with that Utype.

Fields inherited from class uk.ac.starlink.ttools.jel.JELRowReader

COLUMN_ID_CHAR, NULL_QUERY_PREFIX, OBJECT_PREFIX

Constructor Summary

Constructors

Constructor and Description
StarTableJELRowReader(StarTable table) Constructs a new row reader for a given StarTable.

Method Summary

Modifier and Type	Method and Description
protected Constant<?>	createDescribedValueConstant(DescribedValue dval) Returns a Constant object based on a DescribedValue.
protected boolean	getBooleanColumnValue(int icol) Returns a boolean value for a cell of the current row.
protected byte	getByteColumnValue(int icol) Returns a byte value for a cell of the current row.
protected abstract Object	getCell(int icol) Returns the value for a given column in this reader's table at the current row.
protected char	getCharColumnValue(int icol) Returns a char value for a cell of the current row.
protected Class<?>	getColumnClass(int icol) Returns the class of values returned by a given column.
protected int	getColumnIndexByName(String name) Returns the column index of a column in the row given its name.
protected Constant<?>	getConstantByName(String name) Understands table parameters identified case-insensitively by name (using the PARAM_PREFIX prefix) or by UCD (using the UCD_PREFIX prefix) or by Utype (using the UTYPE_PREFIX prefix).
abstract long	getCurrentRow() Returns the index of the row on which evaluations are currently taking place.
DescribedValue	getDescribedValueByName(String name) Returns a table parameter that can be identified by the given designation.
protected double	getDoubleColumnValue(int icol) Returns a double value for a cell of the current row.
protected float	getFloatColumnValue(int icol) Returns a float value for a cell of the current row.
protected int	getIntColumnValue(int icol) Returns a int value for a cell of the current row.
protected long	getLongColumnValue(int icol) Returns a long value for a cell of the current row.
protected Object	getObjectColumnValue(int icol) Returns an Object value for a cell of the current row.
protected short	getShortColumnValue(int icol) Returns a short value for a cell of the current row.
protected Constant<?>	getSpecialByName(String name) Adds to the superclass implementation the following: "$0", "index" or "$index" gives the (1-based) row number "$ncol" gives the number of columns in the table "$nrow" gives the number of rows in the table (null if unknown) "$random" or "RANDOM" returns a double random number, always the same for a given row
StarTable	getTable() Returns the table associated with this reader.
static Pattern	getUcdRegex(String ucd) Takes a (non-prefixed) UCD specification and returns a Pattern actual UCDs should match if they represent the same thing.
static Pattern	getUtypeRegex(String utype) Takes a (non-prefixed) Utype specification and returns a Pattern actual Utypes should match if they represent the same thing.
protected boolean	isBlank(int icol) Indicates whether the value in a given column is null.
boolean	requiresRowIndex() Indicates whether this RowReader has been asked to reference any constants for which the row index is required.
double	valueDouble(String colName) Returns the value of a named column in this reader's table at the current row as a double.
int	valueInt(String colName) Returns the value of a named column in this reader's table at the current row as an int.
long	valueLong(String colName) Returns the value of a named column in this reader's table at the current row as a long int.
Object	valueObject(String colName) Returns the value of a named column in this reader's table at the current row as an Object; This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.
String	valueString(String colName) Returns the value of a named column in this reader's table at the current row as a String.

Methods inherited from class uk.ac.starlink.ttools.jel.JELRowReader

evaluate, evaluateBoolean, evaluateDouble, foundNull, getBooleanArrayProperty, getBooleanProperty, getBooleanProperty, getBooleanValue, getByteArrayProperty, getByteProperty, getByteValue, getCharArrayProperty, getCharProperty, getCharValue, getColumnIndex, getDateArrayProperty, getDoubleArrayProperty, getDoubleProperty, getDoubleValue, getFloatArrayProperty, getFloatProperty, getFloatValue, getIntArrayProperty, getIntProperty, getIntValue, getLongArrayProperty, getLongProperty, getLongValue, getNumberProperty, getObjectArrayProperty, getObjectProperty, getShortArrayProperty, getShortProperty, getShortValue, getStringArrayProperty, getStringProperty, getTranslatedColumns, getTranslatedConstants, getTypeName, setFailOnNull, stripPrefix, translate

Methods inherited from class java.lang.Object

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

Field Detail

PARAM_PREFIX

public static final String PARAM_PREFIX

The string which should be prefixed to a table parameter (constant) name to result in substituting its value.

See Also:

Constant Field Values

UCD_PREFIX

public static final String UCD_PREFIX

A string to prefix to a UCD string to indicate the column/parameter with that UCD. The first matching column, else the first matching parameter, is used. Punctuation in the UCD name is all mapped to "_". A trailing "_" corresponds to a wildcard.

See Also:

Constant Field Values

UTYPE_PREFIX

public static final String UTYPE_PREFIX

A string to prefix to a Utype string to indicate the column/parameter with that Utype. The first matching column, else the first matching parameter, is used. Punctuation in the Utype name is all mapped to "_".

See Also:

Constant Field Values

Constructor Detail

StarTableJELRowReader

public StarTableJELRowReader(StarTable table)

Constructs a new row reader for a given StarTable. Note that this reader cannot become aware of changes to the columns of the table; in the event of such changes this object should be dicarded and and a new one used for any new expressions.

Parameters:

table - the StarTable this reader will read from

Method Detail

getTable

public StarTable getTable()

Returns the table associated with this reader.

Returns:

table

getCell

protected abstract Object getCell(int icol)
                           throws IOException

Returns the value for a given column in this reader's table at the current row.

Parameters:

icol - column index

Returns:

contents of column icol at the current row

Throws:

IOException

getCurrentRow

public abstract long getCurrentRow()

Returns the index of the row on which evaluations are currently taking place.

Returns:

row index (first row is 0)

requiresRowIndex

public boolean requiresRowIndex()

Indicates whether this RowReader has been asked to reference any constants for which the row index is required. In practice this means it will return true if any of the JEL expressions which this RowReader has been asked to compile may need to call the getCurrentRow() method. Since not all row reader implementations are able to return a value for that method, this is useful information.

Returns:

true if the current row index may be required during evaluation

valueDouble

public double valueDouble(String colName)

Returns the value of a named column in this reader's table at the current row as a double. This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.

Parameters:

colName - column name, matched exactly

Returns:

value of named column as a double, or NaN on failure (no such column or value not numeric)

valueInt

public int valueInt(String colName)

Returns the value of a named column in this reader's table at the current row as an int. This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.

Parameters:

colName - column name, matched exactly

Returns:

value of column as an int; foundNull is called on failure (no such column or value not numeric or not finite)

valueLong

public long valueLong(String colName)

Returns the value of a named column in this reader's table at the current row as a long int. This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.

Parameters:

colName - column name, matched exactly

Returns:

value of column as a long; foundNull is called on failure (no such column or value not numeric or not finite)

valueString

public String valueString(String colName)

Returns the value of a named column in this reader's table at the current row as a String. This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.

Parameters:

colName - column name, matched exactly

Returns:

value of column as a String, or null if no such column

valueObject

public Object valueObject(String colName)

Returns the value of a named column in this reader's table at the current row as an Object; This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.

Parameters:

colName - column name, matched exactly

Returns:

value of column as an Object, or null if no such column

isBlank

protected boolean isBlank(int icol)

Description copied from class: JELRowReader

Indicates whether the value in a given column is null.

Specified by:

isBlank in class JELRowReader

Parameters:

icol - column index

Returns:

true if value at icol is null

getColumnClass

protected Class<?> getColumnClass(int icol)

Description copied from class: JELRowReader

Returns the class of values returned by a given column. If no column with the given index exists, null should be returned.

Specified by:

getColumnClass in class JELRowReader

Parameters:

icol - non-negative column index

Returns:

value class, or null for non-existent column

getColumnIndexByName

protected int getColumnIndexByName(String name)

Description copied from class: JELRowReader

Returns the column index of a column in the row given its name. If name does not refer to any known column, return -1.

Specified by:

getColumnIndexByName in class JELRowReader

Parameters:

name - column name

Returns:

column index, or -1

getDescribedValueByName

public DescribedValue getDescribedValueByName(String name)

Returns a table parameter that can be identified by the given designation. This will typically have a prefix such as "param$", "ucd$" etc. Called during expression evaluation, may be overridden.

Parameters:

name - designation in JEL expression

Returns:

fixed value for name, or null

getConstantByName

protected Constant<?> getConstantByName(String name)

Understands table parameters identified case-insensitively by name (using the PARAM_PREFIX prefix) or by UCD (using the UCD_PREFIX prefix) or by Utype (using the UTYPE_PREFIX prefix).

Specified by:

getConstantByName in class JELRowReader

Parameters:

name - constant name

Returns:

constant, or null

getSpecialByName

protected Constant<?> getSpecialByName(String name)

Adds to the superclass implementation the following:

• "$0", "index" or "$index" gives the (1-based) row number
• "$ncol" gives the number of columns in the table
• "$nrow" gives the number of rows in the table (null if unknown)
• "$random" or "RANDOM" returns a double random number, always the same for a given row

Overrides:

getSpecialByName in class JELRowReader

Parameters:

name - special name

Returns:

special, or null

createDescribedValueConstant

protected Constant<?> createDescribedValueConstant(DescribedValue dval)

Returns a Constant object based on a DescribedValue. The supplied implementation evaluates the constant's class and value once when this method is called.

Parameters:

dval - described value object

Returns:

constant which evaluates to dval's value

getBooleanColumnValue

protected boolean getBooleanColumnValue(int icol)

Description copied from class: JELRowReader

Returns a boolean value for a cell of the current row. Will only be called if the relevant column is declared boolean. Must call JELRowReader.foundNull() (and return any value) if the result is null.

Specified by:

getBooleanColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getByteColumnValue

protected byte getByteColumnValue(int icol)

Description copied from class: JELRowReader

Returns a byte value for a cell of the current row. Will only be called if the relevant column is declared byte. Must call JELRowReader.foundNull() (and return any value) if the result is null.

Specified by:

getByteColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getCharColumnValue

protected char getCharColumnValue(int icol)

Description copied from class: JELRowReader

Returns a char value for a cell of the current row. Will only be called if the relevant column is declared char. Must call JELRowReader.foundNull() (and return any value) if the result is null.

Specified by:

getCharColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getShortColumnValue

protected short getShortColumnValue(int icol)

Description copied from class: JELRowReader

Returns a short value for a cell of the current row. Will only be called if the relevant column is declared short. Must call JELRowReader.foundNull() (and return any value) if the result is null.

Specified by:

getShortColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getIntColumnValue

protected int getIntColumnValue(int icol)

Description copied from class: JELRowReader

Returns a int value for a cell of the current row. Will only be called if the relevant column is declared int. Must call JELRowReader.foundNull() (and return any value) if the result is null.

Specified by:

getIntColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getLongColumnValue

protected long getLongColumnValue(int icol)

Description copied from class: JELRowReader

Returns a long value for a cell of the current row. Will only be called if the relevant column is declared long. Must call JELRowReader.foundNull() (and return any value) if the result is null.

Specified by:

getLongColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getFloatColumnValue

protected float getFloatColumnValue(int icol)

Description copied from class: JELRowReader

Returns a float value for a cell of the current row. Will only be called if the relevant column is declared float. Must call JELRowReader.foundNull() (and return any value) if the result is null.

Specified by:

getFloatColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getDoubleColumnValue

protected double getDoubleColumnValue(int icol)

Description copied from class: JELRowReader

Returns a double value for a cell of the current row. Will only be called if the relevant column is declared double. Must call JELRowReader.foundNull() (and return any value) if the result is null.

Specified by:

getDoubleColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getObjectColumnValue

protected Object getObjectColumnValue(int icol)

Description copied from class: JELRowReader

Returns an Object value for a cell of the current row.

Specified by:

getObjectColumnValue in class JELRowReader

Parameters:

icol - column index

Returns:

value

getUcdRegex

public static Pattern getUcdRegex(String ucd)

Takes a (non-prefixed) UCD specification and returns a Pattern actual UCDs should match if they represent the same thing. Punctuation is mapped to underscores, and the pattern is case-insensitive, which means that the same syntax can work for UCD1s and UCD1+s. If a trailing underscore (or other punctuation mark) is present in the input ucd it is considered as a trailing match-all wildcard.

Parameters:

ucd - UCD1 or UCD1+ specification/pattern

Returns:

regular expression pattern which matches actual UCD1s or UCD1+s

getUtypeRegex

public static Pattern getUtypeRegex(String utype)

Takes a (non-prefixed) Utype specification and returns a Pattern actual Utypes should match if they represent the same thing. Punctuation is mapped to underscores, and the pattern is case-insensitive.

Parameters:

utype - utype specification

Returns:

regular expression pattern which matches actual Utypes