# Class JELUtils

java.lang.Object
uk.ac.starlink.ttools.jel.JELUtils

public class JELUtils extends Object
This class provides some utility methods for use with the JEL expression compiler.

Since:
  11 Feb 2005
Author:
  Mark Taylor (Starlink)

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`CLASSES_PROPERTY`
System property name for adding colon-separated list of additional classnames containing static methods.

## Constructor Summary

Constructors
Constructor
Description
`JELUtils()`

## Method Summary

Modifier and Type
Method
Description
`static void`
`checkExpressionType(gnu.jel.Library lib, uk.ac.starlink.table.StarTable table, String expr, Class<?> clazz)`
Checks that an expression is legal and returns a particular class.
`static gnu.jel.CompiledExpression`
`compile(gnu.jel.Library lib, uk.ac.starlink.table.StarTable table, String expr)`
Compiles an expression in the context of a given table.
`static gnu.jel.CompiledExpression`
`compile(gnu.jel.Library lib, uk.ac.starlink.table.StarTable table, String expr, Class<?> clazz)`
Compiles an expression in the context of a given table with a required type for the result.
`static gnu.jel.CompiledExpression[]`
`compileExpressions(StarTableJELRowReader reader, String[] exprs)`
Compiles a set of expressions relating to a table.
`static JELQuantity`
`compileQuantity(gnu.jel.Library lib, StarTableJELRowReader jelRdr, String expr, Class<?> clazz)`
Compiles an expression in the context of a table reader to give a JELQuantity.
`static Function<gnu.jel.Library, gnu.jel.CompiledExpression>`
`compiler(uk.ac.starlink.table.StarTable table, String expr, Class<?> clazz)`
Returns a function that can compile a fixed expression from a Library.
`static JELRowReader`
`createDatalessRowReader(uk.ac.starlink.table.StarTable table)`
Returns a row reader that can be used for expression evaluation, optionally in the context of the non-data parts of a given context table.
`static gnu.jel.Library`
`createLibrary(Class<?>[] staticLib, Class<?>[] dynamicLib, gnu.jel.DVMap resolver)`
Creates a JEL Library from basic information.
`static Class<?>`
`getExpressionType(gnu.jel.Library lib, uk.ac.starlink.table.StarTable table, String expr)`
Gives the return type of an expression.
`static gnu.jel.Library`
`getLibrary(JELRowReader reader)`
Returns a JEL Library suitable for expression evaluation within a table.
`static List<Class<?>>`
`getStaticClasses()`
Returns the list of classes whose static methods will be mapped into the JEL evaluation namespace.
`static Class<?>`
`getWrapperType(Class<?> clazz)`
Returns a non-primitive version of a given class.
`static IOException`
`toIOException(gnu.jel.CompilationException e, String expr)`
Utility method to convert a CompilationException into an IOException.

### Methods inherited from class Object

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

## Field Details

### CLASSES_PROPERTY

public static final String CLASSES_PROPERTY
System property name for adding colon-separated list of additional classnames containing static methods.

See Also:
  - Constant Field Values

## Constructor Details

### JELUtils

public JELUtils()

## Method Details

### getLibrary

public static gnu.jel.Library getLibrary(JELRowReader reader)
Returns a JEL Library suitable for expression evaluation within a table.

Parameters:
  `reader` - object which can read rows from the table to be used for expression evaluation; may be null if there are no references to table-related expressions
Returns:
  a JEL library

### createLibrary

public static gnu.jel.Library createLibrary(Class<?>[] staticLib, Class<?>[] dynamicLib, gnu.jel.DVMap resolver)
Creates a JEL Library from basic information. This method should generally be used rather than the Library constructor, since it may apply additional customisation. Currently, it fixes static methods marked with the `StateDependent` annotation appropriately.

Parameters:
  `staticLib` - array of classes whose public static methods are exported
  `dynamicLib` - array of classes whose public methods are exported
  `resolver` - object used to resolve names
Returns:
  new library
See Also:
  - `Library(Class[], Class[], Class[], DVMap, HashMap)`

### createDatalessRowReader

public static JELRowReader createDatalessRowReader(uk.ac.starlink.table.StarTable table)
Returns a row reader that can be used for expression evaluation, optionally in the context of the non-data parts of a given context table. If the table is non-null, things like its parameters and row counts are available for reference. If the table is null, those things won't be available. In any case, references to table columns will not be recognised.

Parameters:
  `table` - context table, or null
Returns:
  row reader

### getStaticClasses

public static List<Class<?>> getStaticClasses()
Returns the list of classes whose static methods will be mapped into the JEL evaluation namespace. This may be modified.

Returns:
  list of classes with static methods

### getExpressionType

public static Class<?> getExpressionType(gnu.jel.Library lib, uk.ac.starlink.table.StarTable table, String expr) throws gnu.jel.CompilationException
Gives the return type of an expression. This also has the effect of testing that an expression is legal.

Parameters:
  `lib` - JEL library
  `table` - context table
  `expr` - string representation of the expression
Returns:
  class which evaluation of `expr` using `lib` will return
Throws:
  `gnu.jel.CompilationException` - if `expr` cannot be compiled

### checkExpressionType

public static void checkExpressionType(gnu.jel.Library lib, uk.ac.starlink.table.StarTable table, String expr, Class<?> clazz) throws gnu.jel.CompilationException
Checks that an expression is legal and returns a particular class.

Parameters:
  `lib` - JEL library
  `table` - context table
  `expr` - string representation of the expression
  `clazz` - return type required from `expr`
Throws:
  `gnu.jel.CompilationException` - if `expr` cannot be compiled or will return a type other than `clazz` (or one of its subtypes)

### compile

public static gnu.jel.CompiledExpression compile(gnu.jel.Library lib, uk.ac.starlink.table.StarTable table, String expr, Class<?> clazz) throws gnu.jel.CompilationException
Compiles an expression in the context of a given table with a required type for the result. Additional to the behaviour of Evaluator.compile this also checks for expressions which exactly match table column names, even if they are not syntactically legal identifiers.

Parameters:
  `lib` - JEL library
  `table` - context table
  `expr` - expression string
  `clazz` - required class of resulting expression
Returns:
  compiled expression
Throws:
  `gnu.jel.CompilationException`

### compile

public static gnu.jel.CompiledExpression compile(gnu.jel.Library lib, uk.ac.starlink.table.StarTable table, String expr) throws gnu.jel.CompilationException
Compiles an expression in the context of a given table. Additional to the behaviour of Evaluator.compile this also checks for expressions which exactly match table column names, even if they are not syntactically legal identifiers.

Parameters:
  `lib` - JEL library
  `table` - context table
  `expr` - expression string
Returns:
  compiled expression
Throws:
  `gnu.jel.CompilationException`

### compileQuantity

public static JELQuantity compileQuantity(gnu.jel.Library lib, StarTableJELRowReader jelRdr, String expr, Class<?> clazz) throws gnu.jel.CompilationException
Compiles an expression in the context of a table reader to give a JELQuantity. This does the same job as the `compile` methods, but it provides additional metadata if it can be retrieved from the table context.

Parameters:
  `lib` - JEL library
  `jelRdr` - context table reader
  `expr` - expression string
  `clazz` - required return type of compiled expression, or null if no requirement
Returns:
  compiled quantity
Throws:
  `gnu.jel.CompilationException`

### compiler

public static Function<gnu.jel.Library, gnu.jel.CompiledExpression> compiler(uk.ac.starlink.table.StarTable table, String expr, Class<?> clazz) throws gnu.jel.CompilationException
Returns a function that can compile a fixed expression from a Library. This method does a test compilation before it returns, so that if there's something wrong with the expression this method will throw a CompilationException, but invocations of the returned Function on Libraries compatible with the supplied `table` ought not to. The returned function therefore does not need to declare throwing a CompilerException. If for some reason the deferred compilations do fail, a RuntimeException is returned.

Parameters:
  `table` - table from which libraries will be derived
  `expr` - expression to compile
  `clazz` - required result type of expression, or null for automatic
Throws:
  `gnu.jel.CompilationException`

### compileExpressions

public static gnu.jel.CompiledExpression[] compileExpressions(StarTableJELRowReader reader, String[] exprs) throws IOException
Compiles a set of expressions relating to a table.

Any CompilationExceptions are rethrown as IOExceptions; this method should therefore generally be used only if the expressions are expected to be free from errors (have been compiled before).

Parameters:
  `reader` - table reader
  `exprs` - strings giving JEL expressions to be compiled
Returns:
  array with one compiled expression for each input string
Throws:
  `IOException` - in case of any CompilationException

### toIOException

public static IOException toIOException(gnu.jel.CompilationException e, String expr)
Utility method to convert a CompilationException into an IOException.

Parameters:
  `e` - compilation exception
  `expr` - expression for which compilation failed, to be reported in error message

### getWrapperType

public static Class<?> getWrapperType(Class<?> clazz)
Returns a non-primitive version of a given class. If `clazz` is a non-primitive type, it will be returned, otherwise the wrapper class corresponding to the primitive type of `clazz` will be returned (e.g. `Integer` for `int`).

Parameters:
  `clazz` - input class
Returns:
  non-primitive class matching `clazz`