Package gnu.jel

# Class CompiledExpression

java.lang.Object
gnu.jel.CompiledExpression

    public abstract class CompiledExpression
    extends java.lang.Object

This abstract class is a superclass of every JEL-compiled expression, each of which overrides some of the abstract methods below.

Most methods of this class accept a reference to the array of objects. This reference is a pointer to the dynamic object library. As you know, JEL allows to call virtual methods of Java classes, but, as you also know, virtual methods require a reference to an object instance (`this`) to be passed along with parameters. The array `dl` (dynamic library) serves just this purpose. It should contain references to objects of all classes, whose virtual methods were put into the Library of callable functions. Objects in the `dl` array should correspond one-to-one to classes in the array, passed as a second argument of `gnu.jel.Library` constructor.

There are two ways of evaluating the compiled expressions allowing to compromise between raw performance and simplicity:

The first method (simplest one) is based on the call to the `evaluate` method, which will return an object even if the result of computation was of a primitive type. The primitive types will be automatically converted into the corresponding reflection objects. There is certain overhead, associated with object creation, it takes CPU cycles and also produces load on the garbage collector later..

For massive (thousand times) evaluations of functions, producing results of primitive Java types, the second method can be more suitable. It is based on : first, determining the type of the result, and, then, subsequent call to the corresponding evaluateXXX method.

The type of the resulting expression can be determined by call to the getType() method. It will return an integer number, indentifying the type, proper evaluateXXX method can be determined, based on the following table:

     getType()   |  method to call
     ------------+----------------------
     0           | evaluate_boolean(...)
     1           | evaluate_byte(...)
     2           | evaluate_char(...)
     3           | evaluate_short(...)
     4           | evaluate_int(...)
     5           | evaluate_long(...)
     6           | evaluate_float(...)
     7           | evaluate_double(...)
     8           | evaluate(...)         <- result is Object (universal method)
     9           | evaluate_void(...)
     -----------------------------------

Note: If a wrong evaluateXXX() method is called, it will return zero, and, in debug version of JEL (jel_g.jar) only, a warning will be printed to stderr.

There is a possibility to enforce resulting type of the expression at compile time (see `gnu.jel.Evaluator`). Use it to avoid unnecesary type checks.

See Also:
  `Library`, `Evaluator`

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `CompiledExpression()` |

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `static int` | `compare​(java.lang.String s1, java.lang.String s2)` |
  `java.lang.Object` | `evaluate​(java.lang.Object[] dl)` | Evaluates the expression, representing result as an object.
  `boolean` | `evaluate_boolean​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `boolean`.
  `byte` | `evaluate_byte​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `byte`.
  `char` | `evaluate_char​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `char`.
  `double` | `evaluate_double​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `double`.
  `float` | `evaluate_float​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `float`.
  `int` | `evaluate_int​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `int`.
  `long` | `evaluate_long​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `long`.
  `short` | `evaluate_short​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `short`.
  `void` | `evaluate_void​(java.lang.Object[] dl)` | Evaluates the expression whose result has type `void`.
  `abstract int` | `getType()` | Returns type of the expression result.
  `abstract java.lang.Class<?>` | `getTypeC()` | Returns the type of the expression result.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### CompiledExpression

    public CompiledExpression()

- ## Method Details

  - ### getType

    public abstract int getType()
    Returns type of the expression result.

    The type is encoded in integer. Following table could help in determining what it is :

         getType()   |  method to call
         ------------+-----------------
         0           | boolean
         1           | byte
         2           | char
         3           | short
         4           | int
         5           | long
         6           | float
         7           | double
         8           | Object
         9           | void

    The reason not to introduce the family of, say, TYPE_XXX constants is to save space. There are so many things connected with these particular numbers in code generator that it could be a pain to change their meaning. Also, this shoul never be necessary because these are ALL Java 1.X primitive types.

    Returns:
      the type of the expression, encoded in integer.

  - ### getTypeC

    public abstract java.lang.Class<?> getTypeC()
    Returns the type of the expression result.

    If the result has primitive type the corresponding wrapper class is returned (please note that it is just a wrapper class like java.lang.Integer instead of exact primitive type class java.lang.Integer.TYPE). This corresponds to the wrapping done in non-specialized evaluate() method.

    When the result is an object, the returned value is the most specific reference to the class of that object (which is always a subclass of the returned class) available at compile time.

    The precision of determining the result type this way mainly depends on the design of the user's function namespace (defined by gnu.jel.Library class). It is possible to design a library in such a way that the best approximation to the result type obtainable at compile time would be the java.lang.Object class, which will be returned by this method, thus, providing no useful information about the actual type.

    Please note again that the guaranteed exact type of the result can't be determined at compile time and can be quiered only after evaluating the expression (directly from resulting object).

    The only guarantee this method provides is that a variable of the returned expression type can be assigned by a reference, resulting from a call to evaluate.

  - ### evaluate

    public java.lang.Object evaluate​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression, representing result as an object.

    If the result of evaluation is Java primitive type it gets wrapped into corresponding reflection object , i.e. `int` -> `java.lang.Integer`, `boolean` -> `java.lang.Boolean`,...

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_boolean

    public boolean evaluate_boolean​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `boolean`.

    If the type of the result is not a `boolean` this function returns always `false`, debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_byte

    public byte evaluate_byte​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `byte`.

    If the type of the result is not a `byte` this function returns always `0`, debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_short

    public short evaluate_short​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `short`.

    If the type of the result is not a `short` this function returns always `0`, debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_char

    public char evaluate_char​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `char`.

    If the type of the result is not a `char` this function returns always `'?'`, debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_int

    public int evaluate_int​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `int`.

    If the type of the result is not a `int` this function returns always `0`, debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_long

    public long evaluate_long​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `long`.

    If the type of the result is not a `long` this function returns always `0`, debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_float

    public float evaluate_float​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `float`.

    If the type of the result is not a `float` this function returns always `0.0`, debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_double

    public double evaluate_double​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `double`.

    If the type of the result is not a `double` this function returns always `0.0`, debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Returns:
      the result fo computation.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### evaluate_void

    public void evaluate_void​(java.lang.Object[] dl) throws java.lang.Throwable
    Evaluates the expression whose result has type `void`.

    If the type of the result is not a `void` debug version will print a warning to stderr.

    Parameters:
      `dl` - Array of the instance references to the objects in dynamic library. See description of this class above for more details.
    Throws:
      `java.lang.Throwable` - if any runtime error have occured (i.e. division by 0)
    See Also:
      `Evaluator.compile(java.lang.String, gnu.jel.Library, java.lang.Class<?>)`, `Library`

  - ### compare

    public static int compare​(java.lang.String s1, java.lang.String s2)