Copyright © 1998, 1999, 2000, 2001, 2003, 2006, 2007, 2009, 2015 Konstantin L. Metlov <metlov@fti.dn.ua>
Licensing
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the Appendix.
Table of Contents
This manual is mostly examples-based. It starts with two simple step-by-step examples (showing how to deal with static and dynamic libraries), which should give enough information for basic JEL usage (but don't forget to read the rest of this manual to learn how to get the top performance from JEL). Additional information can be found in API documentation.
The main design goal was to create light weight expression compiler generating extremely fast code. The main emphasis is the code execution time and not the compilation time (it is nevertheless small). The other goal was to make JEL language to be very close to Java language with direct access to all built-in Java data types and functions.
Support for all Java data types (boolean, byte, char, short, long, int, float, double, arrays, references)
Octal (0456) and hexadecimal (0x1FFF) literals.
Support for all Java arithmetic operators: + (add),- (subtract), * (multiply), / (divide), % (remainder), & (bitwise and),| (bitwise or), ^ (bitwise xor),~ (bitwise complement), << (left shift), >> (right signed shift), >>> (right unsigned shift); on most of supported data types according to Java Language Specification (JLS)
Comparison operators (==,!=,<,>=,>,<=) as defined by Java Language Specification (JLS).
dot (".") operator on objects ("abc".length()==3).
dot (".") operator on objects ("abc".length()==3).
Boolean logical operators (&&,||,!) with lazy evaluation (i.e. in the expression false&&complexBooleanFunction() the function is never called).
Conditionals (true?2:3 = 2)
Direct access to methods and fields of Java objects.
Method overloading according to Java Language Specification.
Support for methods with variable number of arguments (varargs), which is enabled for all methods, accepting array as their last argument.
Dynamic variables interface allowing to add variables to JEL namespace without supplying the class file defining them.
Automatic unwrapping of designated objects to Java primitive types.
Support for strings. Objects of class java.lang.String can be directly entered into expressions using double quotes, also the standard Java escape codes are parsed. Example : "a string\n\015".
String concatenation ("a"+2+(2>3)+object = "a2false"+object.toString()).
User definable string comparison using usual relational operators "<", "<=", ">", ">=", "==", "!=", which uses locale by default.
User-controllable object down-casting using "(class.name)var" syntax. It is possible to assign names to classes in JEL expressions to be different from their real Java class names.
Constants folding, extended (by default, but can be controlled) to static methods (which are automatically called at compile time) and static fields (which are considered constants).
High performance of generated code.
In this section a simple example of a program using JEL is
  given, and explained with references to more detailed sections of
  this manual. The example program evaluates the expression given on
  its command line (similar program exists in the distribution under
  the name ./samples/Calculator.java), let's
  follow it step by step.
    public static void main(String[] args) {
    
    // Assemble the expression
    StringBuffer expr_sb=new StringBuffer();
    for(int i=0;i<args.length;i++) {
      expr_sb.append(args[i]);
      expr_sb.append(' ');
      };
    String expr=expr_sb.toString();
  This first part of the program is not related to JEL. It's purpose is to assemble the expression, possibly, containing spaces into the single line. This has to be done, because shells tend to tokenize parameters but we don't need it here.
    // Set up the library
    Class[] staticLib=new Class[1];
    try {
      staticLib[0]=Class.forName("java.lang.Math");
    } catch(ClassNotFoundException e) {
      // Can't be ;)) ...... in java ... ;)
    };
    Library lib=new Library(staticLib,null,null,null,null);
    try {
    lib.markStateDependent("random",null);
    } catch (NoSuchMethodException e) {
      // Can't be also
    };
  
  This piece of code establishes the namespace for use in JEL compiled
  expressions. The gnu.jel.Library object
  maintains this namespace.
There can be two types of names in the Library : static and virtual (dynamic).
Methods and variables of the first class are assumed (by
  default) to be dependent only on their arguments i.e. not to save
  any information from call to call (they are
  "stateless")... Examples are mathematical functions like
  sin, cos,
  log, constants E,
  PI in java.lang.Math.  For
  such methods (fields) it does not matter how many times (when) they
  will be called (their value will be taken) the result will always be
  the same provided arguments (if they are present) are the
  same. Stateless methods will be evaluated by JEL at compile time if
  their arguments are constants (known at compile time). To define set
  of static functions(fields) it is needed to pass the array of Class
  objects, defining those functions, as the first parameter of the
  library constructor (see example above). Note ONLY STATIC functions
  of the Classes, passed in the first argument of the
  gnu.jel.Library constructor will be defined
  in the namespace. By default all static functions are considered
  "stateless" by JEL.
However, some static functions still save their state (in
  static variables) in between calls. Thus they return different
  results, depending on when (how many times) they are is called even
  if their arguments are the same. If such function is evaluated at
  compile time, we have troubles, because it will be evaluated only
  once during expression lifetime and it's state dependence will be
  lost. Typical example of the static function, having a state is
  java.lang.Math.random. JEL has special
  mechanism, provided by gnu.jel.Library class
  to mark static functions as state dependent. (see the above example
  to find out how it was done for the
  java.lang.Math.random)
The virtual functions, which are explicitly state dependent, will be discussed later in this document. The example we currently consider does not use them. However, virtual functions are, actually, most important to JEL because expression, containing all stateless functions, is a constant, it will be completely evaluated at compile time, there is absolutely no sense to evaluate such expression repeatedly (this is what JEL was designed for). Still we shall continue with this simple example as the following code is mostly independent of whether we use virtual functions or not...
    // Compile
    CompiledExpression expr_c=null;
    try {
      expr_c=Evaluator.compile(expr,lib);
    } catch (CompilationException ce) {
      System.err.print("–––COMPILATION ERROR :");
      System.err.println(ce.getMessage());
      System.err.print("                       ");
      System.err.println(expr);
      int column=ce.getColumn(); // Column, where error was found
      for(int i=0;i<column+23-1;i++) System.err.print(' ');
      System.err.println('^');
    };
    This chunk of code is for the expression compilation. The crucial
    line is the call to Evaluator.compile, it is the
    point, where expression gets transformed into Java bytecode,
    loaded into the Java Virtual Machine using JEL ClassLoader and
    returned to caller as an instance of the subclass of
    gnu.jel.CompiledExpression.
    Typical user of JEL is not
    required to know what magic is going on inside of
    Evaluator.compile(...). 
    Other code in this chunk is for
    the error reporting and will be discussed in the specialized
    section Error detection and reporting below.
  
      if (expr_c !=null) {
      
      // Evaluate (Can do it now any number of times FAST !!!)
      Number result=null;
      try {
	result=(Number)expr_c.evaluate(null);
      } catch (Throwable e) {
	System.err.println("Exception emerged from JEL compiled"+
			   " code (IT'S OK) :");
	System.err.print(e);
      };
  
  This code does the evaluation of the expression. It is done by
  calling the evaluate method of the JEL 
  compiled class, it is defined abstract in 
  gnu.jel.CompiledExpression but is
  redefined in the class compiled by JEL. The argument of this method
  is discussed in the section on virtual functions below. If only
  static functions are present in the library it is safe to pass the
  null pointer as the argument to 
  evaluate.
  
Result of the evaluate method is always
  an object. JEL converts primitive numeric types into instances of
  corresponding Java reflection classes (read the section 
  Making things faster  to find out how to avoid
  this conversion). For example, a value of primitive type
  long will be returned as an instance of
  java.lang.Long class (int maps to
  java.lang.Integer, float to
  java.lang.Float, etc.). If result is an arbitrary Java
  object it is returned as the reference to that object.
The
try ... catch
 clause
  around the call to evaluate will be enforced by the Java
  compiler. It is required as errors can appear during evaluation. The
  general rule is: syntax, types incompatibility and function
  resolution errors will be reported at compile time (as thrown
  instance of gnu.jel.CompilationException),
  while the errors in the
  values of numbers will be reported at the execution
  time. For example expression "1/0" will generate no error
  at compile time (nevertheless it is the constant expression and its
  evaluation is attempted), but at the time of calling
  execute
  you will get a java.lang.ArithmeticError (division
  by zero) as it should be.
      // Print result
      if (result==null) 
	System.out.println("void");
      else
	System.out.println(result.toString());
   };
};This last piece of code will print the result. And is concluding our brief tour of the JEL usage.
Table of Contents
The namespace of JEL expressions is represented by
gnu.jel.Library class. Its constructor:
Library(Class[] staticLib, Class[] dynamicLib, Class[] dotClasses, DVMap resolver, Hashtable cnmap)
has five arguments. Their purposes are following:
enumerates classes whose static
  methods are exported to JEL namespace and become usable from within
  expressions. Such methods do not require this pointer
  supplied to them at execution time.
  More details
enumerates classes whose virtual methods
  are exported. These methods require the references to the
  corresponding classes (this pointers) supplied to the
  expression at run-time. This is done using the Class[]>
  argument of CompiledExpression's 
  evaluate method.
  More details
controls access for the dot (".") operator on classes. More details
Dynamic variables interface. Allows to add new variables to the expressions names without supplying the class files defining them. More details
Maps the class names usable inside JEL expressions for non-primitive type casts into the Java classes More details
The details on usage of each of these arguments are given in a separate sections below.
The working example using all current functionality of JEL
namespace is given in the 
examples/YourTestBed directory in
the distribution. You'll want to check it after reading this section.
The array of references to classes 
  (java.lang.Class) whose public
  static methods and fields are to be exported should
  be passed as the first argument of the library constructor
  (staticLib). The public static fields and 
  methods of all these classes are merged together into the JEL namespace. The
  non-public or non-static members of staticLib classes
  are ignored.
Methods overloading is supported and works also across classes
  (because the JEL namespace works similarly to the namespace defined
  in a single Java class). For example, if a class C1
  contains the method public static C1.func(int) 
  and a class C2 contains the method 
  public static C2.func(double) and both these
  classes are passed as elements of the staticLib
  array. Then, the JEL expression "func(1)" calls 
  C1.func(int) and the expression
  "func(1.0)" calls 
  C2.func(double). It also means
  that methods and fields of all classes supplied to the 
  Library are subject to the same constraints
  as members of a single Java class.
Moreover, because JEL allows to call methods with no arguments
  omitting the empty brackets (that is "func()"
  and "func" are equivalent) there should be no
  fields and methods with no arguments having the same names in all
  classes presented to the Library constructor.
To check whether the set of classes you gave to the library
  constructor satisfies all required constraints run your program
  against the debug version of JEL library
  (jel_g.jar).  Then, potential problems will be
  reported to you on the standard output.
The second argument of the library constructor
(dynamicLib) works similarly to the first one.
Except that only public virtual members are taken from
the listed classes. These members are merged into the namespace created from
classes from the staticLib. The rules for methods
overloading are the same as for classes listed in the first argument of library
constructor. Also, the overloading is working across the classes
listed in both first and second arguments of the Library constructor.
The crucial difference in the handling of classes listed in the
dynamicLib and the staticLib
comes from the fact that virtual members of dynamicLib
require this reference to the instance of the object of
their defining class be supplied at run-time. Thus, if 
C1 contains the virtual method
public func(double x) its invocation actually requires
two arguments, one is x and the
other is the reference to the instance of class 
C1.
References to the instances of classes of the
dynamicLib array are supplied at the
execution time to the argument of the 
evaluate(Object[] context) method of
gnu.jel.CompiledExpression. 
The elements of the context array
should be instances of classes listed in dynamicLib
array at compile time and there should be one-to-one correspondence between
them. For example, if
dynamicLib[0]=com.mycompany.MyClass.class)
,
the corresponding
entry in the context array, context[0], 
must be a reference to
the instance of 
com.mycompany.MyClass.
Formally, for every i, it should be possible to cast 
the object in the context[i]
into the class, supplied in the dynamicLib[i] array
of the Library constructor, 
otherwise ClassCastException will be thrown from
evaluate.
Let's walk through the example, which calculates function of the single variable many times and uses virtual method calls. This example will consist of two classes : a user written class (providing access to the variable) and the main class compiling and evaluating expressions. First start with the variable provider:
public class VariableProvider {
  public double xvar;
  
  public double x() {return xvar;};
};
This class is trivial, it just defines the function, returning the
value of the variable x.
In the main class (see the first JEL example for headers) the code, constructing the library will be replaced with:
    // Set up library
    Class[] staticLib=new Class[1];
    try {
      staticLib[0]=Class.forName("java.lang.Math");
    } catch(ClassNotFoundException e) {
      // Can't be ;)) ...... in java ... ;)
    };
    Class[] dynamicLib=new Class[1];
    VariableProvider variables=new VariableProvider();
    Object[] context=new Object[1];
    context[0]=variables;
    dynamicLib[0]=variables.getClass();
    
    Library lib=new Library(staticLib,dynamicLib,null,null,null);
    try {
    lib.markStateDependent("random",null);
    } catch (NoSuchMethodException e) {
      // Can't be also
    };Absent in the static example, the additional code
    creates the VariableProvider and assigns its
    reference to an element of context array (to be
    passed to the evaluate method
    of the compiled expression). Also, now the 
    dynamicLib array as not null and contains
    the reference to the VariableProvider class.
The code for compilation is exactly the same as in the example for
    static functions, except we have additional function x
    and the variable xvar defined for use inside the 
    compiled expressions. JEL has the special notation for the functions, 
    having no arguments, namely, brackets in "x()" 
    can be omitted to be "x". This allows to compile now ( with the above 
    defined library) the expressions like "sin(x)",
    "exp(x*x)", 
    "pow(sin(x),2)+pow(cos(x),2)"...
The code for evaluation of an expression having virtual functions is replaced with:
      if (expr_c !=null) {
    
        try {
           for(int i=0;i<100;i++) {
              variables.xvar=i;      // <- Value of the variable
              System.out.println(expr_c.evaluate(context));
                               //^^^^^^^^^^^^^^^ evaluating 100 times
           };
        } catch (Throwable e) {
	   System.err.println("Exception emerged from JEL compiled"+
		              " code (IT'S OK) :");
           System.err.print(e);
        };
    };
    Note the two major differences: 1. we have explicitly 
    assigned the value to the variable; 2. the array of object references 
    (consisting of one element in this example) is passed to the 
    evaluate method. This piece of code will evaluate
    expressions for x=0..99 with 
    step 1.
This concludes our dynamic library example. Try to modify the
    ./Calculator.java sample yourself to allow 
    compilation of virtual functions as described above.
Since the version 2.0.3 JEL supports calling methods with variable number of arguments. Moreover, because the information about the variable arguments declaration is not available via Java reflection, this support extends to all methods, having the array last argument. For example, if two following functions are declared in the library classes (static or dynamic)
       public int sum (int[] args);
       public double powersum(double power, double[] args);
    it is possible to use them in the expressions as
    "sum(1)",
    "sum(1,2)",
    "powersum(2,1,2,3)", etc... The argument
    array will be created automatically by the compiler in these
    cases. The methods with variable number of arguments are subject
    to the same method overloading rules, automatic argument type
    conversions and constants folding as other methods.
The third argument of gnu.jel.Library
  constructor enumerates classes which are available for dot operator
  within the expression. If this parameter is null
  JEL would not allow to use the dot operator at all. If it is an array
  of the length zero (e.g. new Class[0]) 
  JEL will open access to public methods
  of ALL objects encountered in the expression. From the
  security point of view allowing access to all objects can be
  dangerous, that is why there is a third case of non-zero length
  array explicitly enumerating classes allowing the dot operator on
  them.
Once the dot operator is allowed on a class, it is possible to call
  all its public methods using the syntax
  ".method(arg1,arg2,...)" in any context 
  where this class appears in an expression.
All methods of exporting names into JEL namespace described up to this point relied on the Java class files for actual description of methods names and parameters. However, sometimes it is required to add a new variable to JEL namespace at run-time.
One of the solutions would be to generate a new class file (e.g. using JEL) and supply it as a first or second argument of the library constructor. Unfortunately this can be quite cumbersome and time consuming.
The other solution can be to define a family of methods in JEL namespace
YYY getXXXProperty(String name)
for
  each possible variable types, where YYY is the class
  representing the property type and XXX is the name 
  of the type. Then, supposing we have methods
  
double getDoubleProperty(String name); // YYY=double XXX=Double String getStringProperty(String name); // YYY=java.lang.String XXX=String
in the JEL namespace (either static or dynamic), the variables with arbitrary names can be entered into expression using the syntax
getStringProperty("x") +
  (getDoubleProperty("y")+1.0)This way has two drawbacks: 1) user has to remember the type of the
  variable (to call the appropriate getXXX() method); 
  2) a lot to type.
Since the version 0.9.3 JEL provides the way to solve both
  these problems. To do that the fourth argument
  (resolver) of the library constructor is
  used. This argument supplies the reference to the subclass of
  gnu.jel.DVMap, and is used by JEL to resolve
  the dynamic variable names.  The gnu.jel.DVMap
  has an abstract method
  
public String getTypeName(String name)
which returns XXX (see above) for a given variable name, or null if no such variable is defined. Note that for resolver to work the family of methods
YYY getXXXProperty(String name)
  must still be present in JEL namespace (e.g. as members of one of
  dynamicLib[] classes).
Then, supposing
resolver.getTypeName("x")=="String" &&
resolver.getTypeName("y")=="Double"
   the expression "x+(y+1.0)" will be automatically
   converted by JEL into
   
getStringProperty("x")+(getDoubleProperty("y")+1.0)and compiled. Thus, user does not have to remember the variable types, typing is reduced and the existence of variables can be checked at the compile time.
JEL also supports a hierarchical structure of variables. This means the dot (".") symbol can be present in the dynamic variable names. For example if
resolver.getTypeName("x")!=null && 
resolver.getTypeName("x.f1")=="String" && 
resolver.getTypeName("x.f2")=="Double"
  the expression "x.f1+(x.f2+1.0)" will
  be compiled by JEL as
  
getStringProperty("x.f1")+(getDoubleProperty("x.f2")+1.0)
  and (combined with dot operator) the expression 
  "x.f1.length()" will result in the length
  of the string getString("x1.f1").
Notice in the last example that if one wants to have defined
  the dynamic variable "x.y" the variable
  "x" must
  also be the dynamic variable
  (resolver.getTypeName("x")!=null).
If there is conflict between the dynamic variable name and other name in JEL namespace the dynamic variable has a priority.
Since JEL 0.9.9 it is possible to translate the names of dynamic
  variables from strings into the constants of Java primitive
  types. This is done using non-identity DVMap.translate
  method. The translation helps to improve performance in some cases.
Consider the following example. Suppose the underlying storage for
  dynamic variables is an array (or Vector), so that
  the value of the variable can be obtained by an integer index into that 
  array (like numbered columns in a spreadsheet). Next, assume you still
  want to refer to the variables by names (e.g. you allowed user to assign 
  names to the columns). Now, if the first column is named 
  "x" and
  is of Double type, an expression "x",
  using dynamic variables interface with identity translation will be
  compiled into getDoubleProperty("x").
  It means the translation of
  the string "x" into the column number
  1 will have to be
  performed at run-time each time the expression is
  evaluated. Considering that Java strings are immutable, this may incur
  a substantial performance penalty.
The performance can be improved if the translate
  method of DVMap is overridden by the following:
  
public Object translate(String name) {
   if (name.equals("x")) return new Integer(1);
   return name;
   };
   This is already a non-identity translation. With such
   DVMap the expression "x" will be
   compiled by JEL into getDoubleProperty(1), 
   note that it is
   getDoubleProperty(int) method, which is called.
   This way the mapping of the variable name into the variable index is
   performed at compile-time, while at run-time the index is readily available.
   By defining the appropriate translations the dynamic variable lookup can
   be split in a user-controlled way between the expression compilation
  and execution stages to achieve the best performance.
The translate method is allowed to return
  only instances of Java reflection classes wrapping the primitive types
  (java.lang.Integer,
  java.lang.Double, etc), or
  strings (otherwise an exception will emerge at compile-time). This is
  because only these types of objects can be stored in the Java class
  files directly. Also, it is responsibility of the caller to ensure
  that JEL namespace contains getXXXProperty methods
  with all the necessary argument types, corresponding to the translations
  defined in DVMap. For identity translations only
  getXXXProperty methods accepting strings are
  necessary.
The cnmap argument of 
  gnu.jel.Library constructor,
  allows to enable the non-primitive type casts in JEL compiled
  expressions. If cnmap!=null it must be
  java.util.Hashtable with 
  java.lang.Class objects as
  elements and java.lang.String objects as keys.
  When the object cast 
  "(non_primitive_type_name) var" is
  encountered in the expression, "the non_primitive_type_name"
  string is looked in the cnmap hashtable and the 
  cast to the corresponding class is generated by JEL. The absence of the
  name in the hashtable produces the compile-time error. It is possible for
  keys in cnmap to contain "." (dot) symbols
  in them.
This problem appears mostly when one uses dynamic variables, but may
  also arise in other cases. Suppose a reference to the object of the
  class Weight (representing a weight of a certain item)
  appeared in the expression. It is clear that 
  Weight is always represented by a floating point
  number (although it may have other properties, like units). If the 
  class Weight has the method
  
public double getValue()
  the value of weight can be accessed in expressions using syntax
  w.getValue(), supposing the variable
  w has type Weight.
To save typing (since version 0.9.3 of JEL) one may have the class
  Weight implement
  gnu.jel.reflect.Double interface. Then,
  the aforementioned getValue method will be called automatically by JEL
  (or object w will be "unwrapped" to 
  primitive type). This
  unwrapping will be performed automatically when needed: one can have
  expressions "w+1.0" meaning 
  "w.getValue()+1" and 
  "w.getUnits()" both
  valid (in the second case w 
  is not "unwrapped"). 
There are gnu.jel.reflect.* interfaces
  for all Java primitive types. To use the automatic unwrapping one
  just needs to make his classes to implement one of these interfaces.
There is a similar mechanism for strings (since version 0.9.6)
  and a corresponding empty interface 
  gnu.jel.reflect.String
  to denote objects automatically convertible to
  java.lang.String by means of their 
  .toString() method. For
  example, if x is of a class implementing
  gnu.jel.reflect.String interface the expression
  x+"a" will be compiled into
  x.toString()+"a" (otherwise this expression
  produces a error message). The objects automatically convertible to
  strings can also be supplied as arguments of methods requiring
  java.lang.String (usual method overloading rules
  apply). Still, in the current version of JEL it is impossible to
  cast methods of java.lang.String on such objects.
  That is x.substring(1) is a syntax error 
  (unless x itself
  has the .substring(int) method). This deficiency can be
  addressed in future.
Expressions are made by human, and making errors is the natural property of humans, consequently, JEL has to be aware of that.
There are two places, where errors can appear. First are the
  compilation errors, which are thrown in the form of
  gnu.jel.CompilationException by the
  gnu.jel.Evaluator.compile. These errors signal about
  syntax problems in the entered expressions, wrong function names,
  illegal types combinations, but NOT about illegal
  values of arguments of functions. The second source of errors is the
  compiled code itself, Throwables, thrown out of
  gnu.jel.CompiledExpression.evaluate are primarily due to
  the invalid values of function arguments.
Compilation errors are easy to process. Normally, you should surround compilation by the
   try {
      // ... compilation
   catch (CompilationException e) {
      // ... process and report the error
   }
   block. Caught gnu.jel.CompilationException can be
   interrogated, then, on the subject of WHERE error has occurred
   (getCol) and WHAT was the
   error (getMessage). This
   information should then be presented to user. It is wise to use
   information about error column to position the cursor automatically
   to the erroneous place in the expression.
Errors of the second type are appearing during the function
   evaluation and can not be so nicely dealt with by JEL. They depend
   on the actual library, supplied to the compiler. For example
   methods of java.lang.Math do not generate any checked
   exceptions at all (still, Errors are possible), but you may connect
   library, of functions throwing exceptions. As a general rule :
   exceptions thrown by functions from the library are thrown from
   evaluate method
In the above text the result of the computation, returned by
   evaluate was always an object. While this is
   very flexible it is not very fast. Objects have to be allocated on
   heap and garbage collected. When the result of computation is a
   value of one of Java primitive types it can be desirable to
   retrieve it without creation of the object. This can be done (since
   the version 0.2 of JEL) with evaluateXX()
   family of calls (see
   gnu.jel.CompiledExpression. There is an
   evaluateXX() method for each Java primitive
   type, if you know what type expression has you can just call the
   corresponding method.
If you do not know the type of the compiled expression you can
   query it using getType. Be warned, that the
   call to wrong evaluateXX method will result in
   exception. Another tricky point is that JEL always selects smallest
   data type for constant representation. Namely, expression
   "1" has type 
   byte and not int, thus in
   most cases you will have to query the type, and only then, call the
   proper evaluateXX method.
It is anyway possible to eliminate type checks at evaluation
   time completely. There is a version of
   compile method in 
   gnu.jel.Evaluator, which allows to fix
   the type of the result. It directs the compiler to perform the
   widening conversion to the given type, before returning the
   result. For example: if you fix the type to be int
   (passing java.lang.Integer.TYPE as an 
   argument to compile) all expressions (such as 
   "1", "2+5",
   "2*2") will be evaluated by 
   evaluate_int method of
   the compiled expression. Also, the attempt to evaluate
   "1+2L" will be rejected by compiler, 
   asking to insert the explicit narrowing conversion (such as
   "(int)(1+2L)").
There used to be a specialized serialization interface in JEL up to version 0.8.3. The need for such interface was dictated by the fact that JEL allowed to use constants of arbitrary reference types in expressions, which is not supported directly by the Java class file format. Starting with version 0.9 this feature was removed and now JEL generates ordinary Java class files.
To store compiled expressions into a file just grab their code with
  gnu.jel.Evaluator.compileBits. The code is returned as a
  byte array which is easy to save/restore. Then, the expression can be
  instantiated using gnu.jel.ImageLoader with the code
  
byte[] image; // ... code to read the JEL-generated class file into the "image" ... CompiledExpression expression=(CompiledExpression)(ImageLoader.load(image)).newInstance();
or, alternatively, by compiling your source against generated class file. Note that in this version of JEL all generated classes have the name "dump" and are in the root package. If there will be such need in future the Evaluator interface can be extended to assign user-supplied names for new expressions.
There is one serious limitation, which should be mentioned. Actually it is not a JEL limitation but rather a limitation of the typical Java run-time
To load compiled expressions into the Java virtual machine memory
  JEL uses a custom java.lang.ClassLoader. While there
  is nothing wrong with that, setting up a classLoader is a privileged
  operation in Java. This means either JEL should run in a Java
  application (there are no security restrictions on Java
  applications), or , if JEL is distributed in some custom
  applet the applet should be
  signed.
I hope you found JEL useful. Don't hesitate to contact me if there are any problems with JEL, please, report BUGS, suggest tests, send me your patches,... There are still many improvements to be done.
Most current information about JEL should be available at http://www.fti.dn.ua/JEL/.
JEL is the "free software" and is distributed to you under terms of GNU General Public License. Find the precise terms of the license in the file ./COPYING in the root of this distribution.
Please, contact the author directly if you'd like JEL to be commercially licensed to you on a different terms.
Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties — for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”.
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See Copyleft.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright © YEAR YOUR NAME Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with… Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.