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.
| expression | ::= | conditional ( <EOF> ) |
| conditional | ::= | lor ( "?" conditional ":" conditional )? |
| lor | ::= | land ( <LOR> land )* |
| land | ::= | bor ( <LAND> bor )* |
| bor | ::= | bxor ( <OR> bxor )* |
| bxor | ::= | band ( <XOR> band )* |
| band | ::= | equality ( <AND> equality )* |
| equality | ::= | relation ( ( <EQ> | <NE> ) relation )* |
| relation | ::= | shift ( ( <LT> | <GE> | <GT> | <LE> ) shift )* |
| shift | ::= | sum ( ( <LS> | <RS> | <RUS> ) sum )* |
| sum | ::= | term ( ( <PLUS> | <MINUS> ) term )* |
| term | ::= | unary ( ( <MULTIPLY> | <DIVIDE> | <REMAINDER> ) unary )* |
| unary | ::= | ( <BWCOMPL> | <LOGCOMPL> | <MINUS> ) unary |
| | | "(" <ID> ( "." <ID> )* ")" element | |
| | | element | |
| element | ::= | <TRUE> |
| | | <FALSE> | |
| | | ( ( literal | "(" conditional ")" | invocation ) ( <DOT> invocation )* ) | |
| invocation | ::= | <ID> ( "(" ( conditional ( "," conditional )* )? ")" )? ( "[" conditional "]" )* |
| literal | ::= | <INTEGER_LITERAL> |
| | | <FLOATING_POINT_LITERAL> | |
| | | <CHARACTER_LITERAL> | |
| | | <STRING_LITERAL> |
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 JEL manual.
]]>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.
| expression | ::= | conditional ( <EOF> ) |
| conditional | ::= | lor ( "?" conditional ":" conditional )? |
| lor | ::= | land ( <LOR> land )* |
| land | ::= | bor ( <LAND> bor )* |
| bor | ::= | bxor ( <OR> bxor )* |
| bxor | ::= | band ( <XOR> band )* |
| band | ::= | equality ( <AND> equality )* |
| equality | ::= | relation ( ( <EQ> | <NE> ) relation )* |
| relation | ::= | shift ( ( <LT> | <GE> | <GT> | <LE> ) shift )* |
| shift | ::= | sum ( ( <LS> | <RS> | <RUS> ) sum )* |
| sum | ::= | term ( ( <PLUS> | <MINUS> ) term )* |
| term | ::= | unary ( ( <MULTIPLY> | <DIVIDE> | <REMAINDER> ) unary )* |
| unary | ::= | ( <BWCOMPL> | <LOGCOMPL> | <MINUS> ) unary |
| | | "(" <ID> ( "." <ID> )* ")" element | |
| | | element | |
| element | ::= | <TRUE> |
| | | <FALSE> | |
| | | ( ( literal | "(" conditional ")" | invocation ) ( <DOT> invocation )* ) | |
| invocation | ::= | <ID> ( "(" ( conditional ( "," conditional )* )? ")" )? ( "[" conditional "]" )* |
| literal | ::= | <INTEGER_LITERAL> |
| | | <FLOATING_POINT_LITERAL> | |
| | | <CHARACTER_LITERAL> | |
| | | <STRING_LITERAL> |
Additionally it counts line and column numbers. The read character
* is automatically set as a current char of this Tokenizer.
*
* @return next character from the selected input.
*/
protected int read() {
try {
c=in.charAt(pos++);
} catch (Exception e) {
c=-1;
};
column++;
if (prevLF)
{
prevLF = false;
line += (column = 1);
}
else if (prevCR)
{
prevCR = false;
if (c == '\n')
{
prevLF = true;
}
else
line += (column = 1);
}
switch (c) {
case '\r':
prevCR = true;
break;
case '\n':
prevLF = true;
break;
case '\t':
column--;
column += (8 - (column & 07));
break;
default:
break;
};
return c;
};
public void error(int code, Object param, int column)
throws CompilationException {
CompilationException exc = new CompilationException(code,param);
exc.col=column;
throw exc;
}
// because EOF can never be expected, "consume(-1)" has a special
// meaning, which is just to report the "current unexpected" char.
protected void consume(int cc) throws CompilationException {
if ((cc<0) || (c!=cc))
error(c==-1?1:3,new Character((char)c),column-(c==-1?1:0));
read();
};
public void nextToken() throws CompilationException {
// store the column and line of the current token
ct_column=column;
ct_line=line;
int cc;
while (true) {
switch (c) {
case -1: // EOF
type=-1; return;
case ' ':
case '\r':
case '\t':
case '\n':
read(); // just ignored
ct_column=column; // adjust start token
ct_line=line; // adjust start token
break;
case '+':
read(); type=0; return;
case '-':
read(); type=1; return;
case '*':
read(); type=2; return;
case '/':
read(); type=3; return;
case '%':
read(); type=4; return;
case '&':
switch (read()) {
case '&':
read(); type=17; return;
default:
type=5; return;
}
case '|':
switch (read()) {
case '|':
read(); type=18; return;
default:
type=6; return;
}
case '^':
read(); type=7; return;
case '=':
read(); consume('='); type=8; return;
case '!':
switch(read()) {
case '=':
read(); type=9; return;
default:
type=31; return;
}
case '<':
switch (read()) {
case '=':
read(); type=13; return;
case '<':
read(); type=14; return;
default:
type=10; return;
}
case '>':
switch (read()) {
case '=':
read(); type=11; return;
case '>':
switch(read()) {
case '>':
read(); type=16; return;
default:
type=15; return;
}
default:
type=12; return;
}
case '~':
read(); type = 30; return;
case '[':
read(); type = 19; return;
case ']':
read(); type = 20; return;
case '?':
read(); type = 35; return;
case ':':
read(); type = 36; return;
case '.':
cc=read();
if ((cc>='0') && (cc<='9')) {
// case '0': case '1': case '2': case '3': case '4':
// case '5': case '6': case '7': case '8': case '9':
parseReal();
} else {
type=40;
};
return;
case '0': case '1': case '2': case '3': case '4':
case '5': case '6': case '7': case '8': case '9':
parseNumber();
return;
case '(':
read(); type=41; return;
case ')':
read(); type=42; return;
case ',':
read(); type=43; return;
case '\"':
read();
parseString();
return;
case '\'':
parseChar();
return;
default:
if (Character.isJavaIdentifierStart((char)c)) {
parseID();
return;
} else consume(-1);
}
}
};
// current char must be starting slash
private int parseEscape() throws CompilationException {
switch (read()) {
case 'r':
read(); return '\r';
case 'n':
read(); return '\n';
case 'f':
read(); return '\f';
case 'b':
read(); return '\b';
case 't':
read(); return '\t';
case 'u': { // parsing unicode escapes
int v=0;
for(int i=0;i<4;i++) {
read();
v=v<<4;
if ((c>='0')&&(c<='9')) {
v+=c-'0';
} else if ((c>='a') && (c<='f')) {
v+=c-'a'+10;
} else if ((c>='A') && (c<'F')) {
v+=c-'A'+10;
} else {
consume(-1);
return -1; // never reached
};
};
read(); // position to the next in stream
return v; // character parsed
}
case '\\': case '\"': case '\'':
// TRICK ! This should return an _old_ c before read, and then read().
return c+(read()-c);
default: { // parsing octal escapes
if ((c>='0') && (c<='7')) {
int v=c-'0';
for (int i=0;i<2;i++) {
read();
if ((c>='0') && (c<='7')) {
v = (v << 3) + c - '0';
} else {
if (v>0xFF) consume(-1);
return v;
};
};
read();
if (v>0xFF) consume(-1);
return v;
} else {
// invalid escape character
consume(-1);
return -1; // never reached
}
}
} // case
};
private void parseChar() throws CompilationException {
char ch=0;
switch(read()) {
case '\\':
ch=(char)parseEscape();
break;
case -1: // EOF
case '\n':
case '\r':
case '\'':
// these can't be encountered inside char literal
consume(-1);
break;
default:
ch=(char)c;
read();
};
consume('\'');
type=60; // There are two types of members in the library, those which are stateless
* (i.e. their value depends only on their arguments, if there are any) and
* stateful (also called here dynamic). The result of evaluation of
* stateful members may depend on other factors besides their arguments.
*
* Examples of possible stateless members are : Math.sin(double),
* Math.PI.
* Examples of possible stateful members are : Math.random(),
* System.currentTimeMillis().
*
* Stateless members of this library are always static members of the
* classes, which define them. The inverse is generally not true. However,
* this library goes as far as assuming that static members are stateless,
* if this assumption does not hold for some of Your members it is possible to
* mark them as stateful using the markStateDependent() method of
* this class.
*
* The most crucial difference between the two kind of members of this
* library is that evaluation of stateless methods is attempted by JEL at
* a compile time during the constants folding phase.
*/
public class Library {
private HashMap The following should be kept in mind when constructing a library:
* The array (dotClasses), which is the third argument of
* this constructor determines how (and whether) to compile the
* dot operators encountered in expressions. These operators are
* of the form <object>.(<method>|<field>),
* which means to call method (access field)
* of an <object>. There can be three types of the behaviour:
* 1) dot operators are prohibited (dotClasses==null),
* this is behaviour of older version of JEL.
* 2) dot operators are allowed on all classes
* (dotClasses==new Class[0], an empty array).
* Depending on the types of objects returned by the static/dynamic library
* classes this may pose a security risk.
* 3) dot operators are allowed only on some classes. This is achieved
* by listing these classes in the dotClasses array.
* @param staticLib is the array of classes, whose public static
* methods are exported.
* @param dynamicLib is the array of classes, whose public virutal
* methods are exported.
* @param dotClasses is the array of classes on which the dot ('.')
* operation is allowed.
* @param resolver is the object used to resolve the names.
* @param cnmap Maps class names into classes for non-primitive type casts.
*/
public Library(Class[] staticLib,Class[] dynamicLib,Class[] dotClasses,
DVMap resolver,HashMap If java.lang.Math is included into the library it is
* necessary to mark java.lang.Math.random() as having the
* state. This can be done by calling
* markStateDependent("random",null).
* Please specify parameters as close as possible, otherwise you can
* accidentally mark another function.
* @param name is the function name.
* @param params are the possible invocation parameters of the function.
* @exception CompilationException if the method can't be resolved
*/
public void markStateDependent(String name, Class[] params)
throws CompilationException {
Object m;
try {
m=getMember(null,name,params);
} catch (CompilationException exc) {
if (exc.col<0) exc.col=0;
throw exc;
}
Object removed=stateless.remove(m);
if (Debug.enabled)
Debug.check(removed!=null,"State dependent methos \""+m+
"\"is made state dependend again.");
};
/**
* Used to check if the given method is stateless.
* @param o is method or field to check.
* @return true if the method is stateless and can be invoked at
* compile time.
*/
public boolean isStateless(Member o) {
return stateless.containsKey(o);
};
/**
* Searches the namespace defined by this library object for method or field.
* The method with the same name, and closest (convertible) parameter
* types is returned. If there are several methods the most specific one
* is used.
* Ambiguities are detected. Example of detectable ambiguity: Java compiler normally would not allow to define such ambiguous
* methods in the same class. However, as this library is assembled from
* several Java classes, such ambiguities can happen, and should be
* detected.
* @param container the class to search the method within, if null
* the root namespace is searched.
* @param name is the name of the method to find.
* @param params are the types of formal parameters in the method invocation.
* @return the method/field object of the resolved method/field.
* @exception CompilationException if the method can't be resolved
*/
public Member getMember(Class container,String name,Class[] params)
throws CompilationException {
HashMap The type of a method is its return type, the type of a constructor is
* void.
* @param m member whose type is to be determined
* @return type of the member
*/
public static Class getType(Member m) {
if (m instanceof Method) return ((Method)m).getReturnType();
if (m instanceof Field) return ((Field)m).getType();
if (m instanceof LocalField) return ((LocalField)m).getType();
// otherwise it must be java.lang.reflect.Constructor
if (Debug.enabled)
Debug.check(m instanceof java.lang.reflect.Constructor);
return OP.specialTypes[9]; // java.lang.reflect.Void.TYPE
};
/**
* Used to get types of formal parameters of a member.
* The reference to the class instance "this" is not counted by
* this method.
* @param m member whose formal parameters are to be obtained
* @param np numer of parameters for varargs expansion (if np==-1
* or the last argument is not an array, the expansion is not
* performed). It is also an error to pass the np, smaller
* then the number of method parameters.
* @return array of formal parameter types (empty array if none).
*/
public static Class[] getParameterTypes(Member m, int np) {
Class[] params=null;
if (m instanceof Method) params=((Method)m).getParameterTypes();
if (m instanceof LocalMethod) params=((LocalMethod)m).getParameterTypes();
if (m instanceof Constructor) params=((Constructor)m).getParameterTypes();
if (params!=null) {
if ((np The same can be done using java.lang.Class.getName() by
* converting it's result into the "historical form".
* This utility method can be used outside of the JEL package
* it does not involve any JEL specific assumptions and should follow
* JVM Specification precisely.
* @param cls is the class to compute the signature of. Can be primitive or
* array type.
* @return the class signature.
*/
public static String getSignature(Class cls) {
return appendSignature(new StringBuilder(),cls).toString();
};
private static StringBuilder appendSignature(StringBuilder buff, Class cls) {
if (cls.isPrimitive()) {
int tid;
buff.append((tid=OP.typeID(cls))>9?'L':"ZBCSIJFDLV".charAt(tid));
} else if (cls.isArray()) {
buff.append('[');
appendSignature(buff,cls.getComponentType());
} else { // just a class
buff.append('L');
appendHistoricalForm(buff,cls.getName());
buff.append(';');
};
return buff;
};
public static String toHistoricalForm(String className) {
return appendHistoricalForm(new StringBuilder(),className).toString();
};
private static StringBuilder appendHistoricalForm(StringBuilder buff,
String className) {
int namelen=className.length();
for(int i=0;i It is intended for compilation of algebraic expressions involving
* functions.
* Syntax allows variables, which can be either a public fields of
* certain objects or functions with no arguments. If a method like
* "double x() {};" is defined in the dynamic library class
* (see gnu.jel.Library documentation on how to do this), an
* expression "sin(x)" will call the method "x()" (
* and function Math.sin() ) each time it is evaluated.
* Static methods in namespace are assumed to be stateless (unless
* this default behaviour is explicitly overridden, as is necessary
* for Math.random()) and will be called at compile time if
* their arguments are known.
* It is possible to have any type of intermediate object
* throughout the calculation as long as types of the function return
* values and parameters stay compatible. The compiler can
* do all the type conversions permissible in Java language and more
* (e.g. between reflection wrappers java.lang.Integer,... and
* primitives). Widening type conversions (not leading to precision loss)
* are applied by JEL automatically, narrowing should be explicitly
* requested.
* There is variant of the "compile" function with three arguments,
* which allows to fix the type of the expression result. For example:
* Care should be taken during the assembly of static and dynamic libraries
* to avoid conflicts and unexpected return types.
*
* (c) 1998-2003, by Konstantin Metlov This variant of compile allows to store expressions in a
* java.io.OutputStream using Java serialization mechanism.
* @param expression is the expression to compile. i.e. "sin(666)" .
* @param lib Library of functions exported for use in expression.
* @param resultType identifies the type result should be converted to. Can
* be null, in this case the result type is not fixed.
* @return Byte array, representing the expression
* in a standard Java classfile format. It can be conveniently
* loaded (with renaming, if necessary)
* into Java VM using gnu.jel.ImageLoader.
* @exception gnu.jel.CompilationException if the expression is not
* syntactically or semantically correct.
* @see gnu.jel.CompiledExpression
* @see gnu.jel.ImageLoader
*/
public static byte[] compileBits(String expression, Library lib,
Class resultType)
throws CompilationException {
OP code=parse(expression,lib,resultType);
// Perform constants folding
try {
code=new OPload(code,code.eval());
} catch (Exception exc) {
};
return getImage(code);
};
/**
* Compiles expression, resolving the function names in the library.
* @param expression is the expression to compile. i.e. "sin(666)" .
* @param lib Library of functions exported for use in expression.
* @return Instance of the CompiledExpression subclass, implementing
* the specified expression evaluation.
* @exception gnu.jel.CompilationException if the expression is not
* syntactically or semantically correct.
* @see gnu.jel.CompiledExpression
*/
public static CompiledExpression compile(String expression, Library lib)
throws CompilationException {
return compile(expression, lib, null);
};
/**
* Compiles expression, resolving the function names in the library.
* This variant of compile allows to store expressions in a
* java.io.OutputStream using Java serialization mechanism.
* @param expression is the expression to compile. i.e. "sin(666)" .
* @param lib Library of functions exported for use in expression.
* @return Byte array, representing the expression
* in a standard Java classfile format. It can be conveniently
* loaded (with renaming, if necessary)
* into Java VM using gnu.jel.ImageLoader.
* @exception gnu.jel.CompilationException if the expression is not
* syntactically or semantically correct.
* @see gnu.jel.CompiledExpression
* @see gnu.jel.ImageLoader
*/
public static byte[] compileBits(String expression, Library lib)
throws CompilationException {
return compileBits(expression, lib, null);
};
static OP parse(String expression, Library lib,
Class resultType) throws CompilationException {
return (new Parser(expression,lib)).parse(resultType);
// return (new EC(new CharStream(expression))).parse(resultType,lib);
};
static byte[] getImage(OP code) {
int retID=code.resID;
ClassFile cf=cf_orig.clone();
// set return type
int otsize=cf.tsize;
cf.tsize=retID_patchback;
cf.write((byte)retID);
cf.tsize=otsize;
String retName;
if ((retID<8))
retName=OP.specialTypes[20+retID].getName();
else if (retID==9)
retName="java.lang.Void";
else
retName=code.resType.getName();
// set return class
otsize=cf.tsize;
cf.tsize=retIDC_patchback;
cf.writeShort(cf.getIndex(retName,8));
cf.tsize=otsize;
// add the evaluate method
cf.newMethod(eval_methods[retID],null);
code.compile(cf);
return cf.getImage();
};
};
source/src/java/gnu/jel/OPload.java 0000644 0001750 0001750 00000006044 12714113765 016153 0 ustar oles oles /* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* This file is part of the Java Expressions Library (JEL).
* For more information about JEL visit : http://fti.dn.ua/JEL/
*
* Copyright (C) 1998, 1999, 2000, 2001, 2003, 2006, 2007, 2009 Konstantin L. Metlov
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see For private JEL usage in constants folding.
* @param instead an OP, which will be raplaced by this OPload.
* @param what is a constant wrapped into a reflection object. E.g
* java.lang.Integer(1) to load 1 of
* primitive type int.
*/
public OPload(OP instead,Object what) {
if (Debug.enabled) {
if (!(
(
(typeIDObject(what)==instead.resID) &&
(instead.resID!=8)
) ||
(
(instead.resID==10) &&
(what instanceof StringBuffer)
)
)
) {
Debug.println("typeIDObject(what)="+
typeIDObject(what));
Debug.println("instead.resID="+instead.resID);
Debug.println("what="+what);
Debug.println("what.getClass()="+what.getClass());
};
Debug.check((
(typeIDObject(what)==instead.resID) &&
(instead.resID!=8)
) ||
(
(instead.resID==10) &&
(what instanceof StringBuffer)
)
);
};
this.resType=instead.resType;
this.resID=instead.resID;
this.what=what;
};
public Object eval() throws Exception {
return what;
};
public void compile(ClassFile cf) {
cf.codeLDC(what,resID);
};
};
source/src/java/gnu/jel/CompilationException.java 0000644 0001750 0001750 00000005521 12714113765 021131 0 ustar oles oles /* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* This file is part of the Java Expressions Library (JEL).
* For more information about JEL visit : http://fti.dn.ua/JEL/
*
* Copyright (C) 1998, 1999, 2000, 2001, 2003, 2006, 2007, 2009 Konstantin L. Metlov
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see The text of the messages can be changed/internationalized by
* modification of JEL.properties file
*/
@SuppressWarnings("serial") public class CompilationException extends Exception {
public int col=-1;
private int code=-1; // error code
private Object[] params=null; // parameters to generate messages
/**
* Constructs new CompilationException with a single formatting parameter.
* @param code is the error code (must correspond to a message in
* JEL.properties file).
* @param param is the single Object parameter or an array of Objects to
* be used in message formatting.
*/
public CompilationException(int code, Object param) {
if (Debug.enabled)
Debug.check(code>=0);
this.code=code;
if (param!=null)
if (param.getClass().isArray())
this.params=(Object[])param;
else {
Object[] temp={param};
this.params=temp;
}
}
/**
* Used to obtain the column, where error have occurred.
* @return column, where error have occurred.
*/
public int getColumn() {
return col;
};
/**
* Used to obtain the error code.
* @return the error code, corresponding to one of the messages in
* JEL.properties file.
*/
public int getType() {
return code;
};
/**
* Used to obtain the parameters for this error.
* @return the parameters to be used in message formatting, they provide
* further information about the error.
*/
public Object[] getParameters() {
return params;
};
/**
* Used to obtain the formatted error message.
* @return the formatted error message.
*/
public String getMessage() {
if (Debug.enabled)
Debug.check(col>=0);
return TableKeeper.getMsg(code,params);
};
};
source/src/java/gnu/jel/debug/ 0000755 0001750 0001750 00000000000 12714113765 015214 5 ustar oles oles source/src/java/gnu/jel/debug/Debug.java 0000644 0001750 0001750 00000007435 12714113765 017116 0 ustar oles oles /* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* This file is part of the Java Expressions Library (JEL).
* For more information about JEL visit : http://fti.dn.ua/JEL/
*
* Copyright (C) 1998, 1999, 2000, 2001, 2003, 2006, 2007, 2009 Konstantin L. Metlov
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see Upon success this node is to be replaced by the constant node
* holding the returned object.
* @return an object to which this node evaluates
* @exception if can't evaluate, in this case the sub-nodes
*/
public abstract Object eval() throws Exception;
/**
* Called to generate the code implementing this OP.
* @param cf class file with a new open method to write the code into.
*/
public abstract void compile(ClassFile cf);
//======================================================
// Utility methods for dealing with types, etc...
//======================================================
/**
* Classes of the special types by ID.
* The frequently used types (those on which many operations are
* defined) are identified by an integer number. The advantage is
* the possibility to have almost completely table driven code generator.
* So, the special types are only special in the fact that except
* of the reference to their class object they are also identified by an
* integer number.
*/
public final static Class[] specialTypes; // defined in gnu.jel.TablesKeeper
/**
* Unwraps the type ID.
* That is all special types which are references are translated into 8.
*/
public final static byte[] unwrapType;
static {
specialTypes=(Class[])TableKeeper.getTable("specialTypes");
unwrapType=(byte[]) TableKeeper.getTable("unwrapType");
};
/**
* Identifies the primitive type of the given class.
* @param c class to identify.
* @return id of the corresponding primitive type.
*/
public static final int typeID(Class c) {
final int NUM_SPECIAL_PRIMITIVE_TYPES=10;
// ^^^ it is the number of primitive types out of special ones
if (c==null) return 8;
if (c.isPrimitive()) {
int i;
for(i=0;(i Allows to translate variable names into
* constants of Java primitive types at compile-time. See the section of the
* manual on dynamic variables.
*/
public abstract class DVMap {
/**
* Returns the name of the type of the named property.
* The dot ('.') symbol can be present in the property name to denote
* hierarchical naming scheme.
* If hierarchical naming scheme is used and the variable
* x.y is defined the variable x must also be defined.
* @param name is the name of the property.
* @return the XXX in the name of the corresponding getXXXProperty()
* method of dynamic library, null if the variable with the given name
* is not defined.
*/
public abstract String getTypeName(String name);
/**
* Translates the variable name (a String) to a constant of any primtive
* type (e.g. a number).
*
* The performance of the compiled code can be sometimes improved
* by letting it not to deal with strings. For example, in older JEL <=0.9.8
* this method was absent, and, if the underlying representation of the
* dynamic variables storage was an array, the translation of variable name
* (represented by String) into integer index had to happen at run-time,
* taking up the valuable processor cycles. Defining the proper
* DVMap.translate one can perform the translation
* "variable name(String)"->"slot number(int)" at compile
* time. There can be also other clever ways of using translation to
* improve performance even if variables are not stored in an array or
* vector.
* The default implementation provides the identity translation, which
* simulates the behaviour of older versions of JEL.
*
* @since 0.9.9
* @param name Name of the variable to be translated.
* @return Object representing the translated name, this object must be
* either a reflection type wrapping a primitive (e.g. java.lang.Integer,
* java.lang.Byte) or String. No other object is allowed, othwerwise an
* exception will emerge at compile-time. This limitation is due to Java
* class file format not allowing to store constants of types other than
* specified above.
*/
public Object translate(String name) {
return name;
};
};
source/src/java/gnu/jel/OPunary.java 0000644 0001750 0001750 00000026330 12714113765 016372 0 ustar oles oles /* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* This file is part of the Java Expressions Library (JEL).
* For more information about JEL visit : http://fti.dn.ua/JEL/
*
* Copyright (C) 1998, 1999, 2000, 2001, 2003, 2006, 2007, 2009 Konstantin L. Metlov
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see Codes are following:
* Fails assertion if called on the field which is not public
* static final.
* @return value of the field, object of wrapped primitive type or string.
*/
public Object getConstValue() {
if (Debug.enabled)
Debug.check(constValue!=null);
return constValue;
};
};
source/src/java/gnu/jel/ClassFile.java 0000644 0001750 0001750 00000102532 12714113765 016641 0 ustar oles oles /* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* This file is part of the Java Expressions Library (JEL).
* For more information about JEL visit : http://fti.dn.ua/JEL/
*
* Copyright (C) 1998, 1999, 2000, 2001, 2003, 2006, 2007, 2009 Konstantin L. Metlov
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see Sizes of fAccess, fNames and fTypes
* arrays must be the same.
* @param modifiers sum of one or more of PUBLIC, FINAL,
* INTERFACE, ABSTRACT
* constants of java.lang.reflect.Modifier
* @param name is the name of new class (must be in Java historical form,
* i.e. with dots replaced by slashes '/')
* @param superClass is the superclass of this class
* @param interfaces array of interfaces this class implements
* @param fields fields this class will have
*/
public ClassFile(int modifiers,String name,Class superClass,
Class[] interfaces,LocalField[] fields) {
constPoolData=new ByteArrayOutputStream();
constPool=new DataOutputStream(constPoolData);
text=new byte[256];
if (Debug.enabled)
Debug.check(cstk.length==6);
for (int i=0;i<6;i++)
cstk[i]=new IntegerStack();
try {
if (Debug.enabled) // check if the name is in historical form
Debug.check(name.indexOf('.')==-1);
getUTFIndex(name); // must be the first entry
if (Debug.enabled)
Debug.check((modifiers & ~(java.lang.reflect.Modifier.PUBLIC+
java.lang.reflect.Modifier.FINAL+
java.lang.reflect.Modifier.INTERFACE+
java.lang.reflect.Modifier.ABSTRACT))==0);
isInterface=((modifiers & 0x0200)>0);
// write modifiers
writeShort(modifiers | 0x0020); // set ACC_SUPER flag
// CONSTANT_CLASS for a new class, has to be written by hand
// since no corresponding java.lang.Class object exists yet.
if (Debug.enabled)
Debug.check(poolEntries==2);
poolEntries++;
constPool.write(7);
constPool.writeShort(1); //name of this class is always the first entry.
// write class cp index
writeShort(2);
// write superclass cp index
writeShort(getIndex(superClass,9));
// write out interfaces
int nInterfaces;
if (interfaces==null) nInterfaces=0; else nInterfaces=interfaces.length;
writeShort(nInterfaces);
for(int i=0;i If either is negative the corresponding operation
* (addition/removal) is skipped. This method is needed to allow ClassFile
* to compute the maximum stack occupation for the generated code. It is
* responsibility of the user (of this class) to call noteStk() each
* time the stack is changed from within the code.
* @param s typeid to be put on stack (-1 if none).
* @param a typeid to be taken off Java stack (-1 if none).
*/
public void noteStk(int s,int a) {
if (Debug.enabled)
Debug.check(cW<=mW);
if ((s>=0) && (s!=9)) {
cW--;
if ((s & (~2)) == 5) cW--; // Note additional word for J and D
if (Debug.enabled)
Debug.check(cW>=0);
};
if ((a>=0) && (a!=9)) {
cW++;
if ((a & (~2)) == 5) cW++; // Note additional word for J and D
if (cW>mW) mW=cW;
};
};
/**
* classes frequently used in generated code
*/
private static final Class[] specialClasses;
static {
if (Debug.enabled)
Debug.check(OP.specialTypes.length==29,
"You changed special types in TypesStack please update "+
"specialClasses array in ClassFile.");
specialClasses=(Class[])TableKeeper.getTable("specialClasses");
};
private static final Member[] specialMethods;
static {
char[][] specialMds=(char[][]) TableKeeper.getTable("specialMds");
String[] specialMdsN=(String[]) TableKeeper.getTable("specialMdsN");
specialMethods=new Member[specialMds.length];
{
Class definingClass=null;
String name=null;
Class[] params=null;
int i=0;
try {
for (i=0;i If the specified string was not found in the pool -- it is added.
* @param str the string to look for ( to add )
* @return index of the string in the Constant Pool.
*/
int getUTFIndex(String str) {
// Check if it is in the pool already
Integer index=UTFs.get(str);
if (index==null) { // add UTF to the pool
index=new Integer(poolEntries++);
try {
constPool.write(1); // CONSTANT_Utf8 = 1;
constPool.writeUTF(str);
} catch (java.io.IOException e) {
if (Debug.enabled) Debug.reportThrowable(e);
};
UTFs.put(str,index);
};
return index.intValue();
};
// encodes types of relevant objects as integers
// for classes corresponding to primitive types codes are the same as
// primitiveID's
private int typeID(Object item) {
int id=OP.typeIDObject(item);
if (id<8) return id;
if (item instanceof String) return 8;
if (item instanceof Class) return 9;
if (item instanceof Member) return 10;
return -1;
};
/**
* Used to determine an old CP index or to create a new one for an item.
* @param item an item to create or get an index for
* @return index for an item (negative if it has to be written)
*/
private final int getIndex(Object item) {
return getIndex(item,typeID(item));
};
/**
* Used to determine an old CP index or to create a new one for an item.
* @param item an item to create or get an index for
* @param typeid identifies type of argument to avoid linear searches
* @return index for an item (negative if it has to be written)
*/
public int getIndex(Object item,int typeid) {
Integer index=Items.get(item);
if (index==null) {
int newIndex=-1;
try {
int ival=-1;
switch (typeid) {
case 0:
ival=((Boolean)item).booleanValue()?1:0;
case 2:
if (ival<0) ival=(int)((Character)item).charValue();
case 1:
case 3:
case 4:
if (ival<0) ival=((Number)item).intValue();
newIndex=poolEntries++;
constPool.write(3); // CONSTANT_Integer = 3;
constPool.writeInt(ival);
break;
case 5:
newIndex=poolEntries;
constPool.write(5); // CONSTANT_Long = 5;
constPool.writeLong(((Long)item).longValue());
poolEntries+=2; // Long occupies two entries in CP, weird !!!
break;
case 6:
newIndex=poolEntries++;
constPool.write(4); // CONSTANT_Float = 4;
constPool.writeFloat(((Float)item).floatValue());
break;
case 7:
newIndex=poolEntries;
constPool.write(6); // CONSTANT_Double = 6;
constPool.writeDouble(((Double)item).doubleValue());
poolEntries+=2; // Double occupies two entries in CP, weird !!!
break;
case 8:
{
int UTFIndex=getUTFIndex((String)item); // write string , if needed
newIndex=poolEntries++;
constPool.write(8); // CONSTANT_String = 8;
constPool.writeShort(UTFIndex);
}
break;
case 9:
{
String histNameStr=
Library.toHistoricalForm(((Class)item).getName());
int UTFIndex=getUTFIndex(histNameStr); // write FQCN , if needed
newIndex=poolEntries++;
constPool.write(7); // CONSTANT_Class = 7;
constPool.writeShort(UTFIndex);
}
break;
case 10: // Method
case 11: // Constructor
case 12: // Field
Member member = (Member) item;
Class dClass=member.getDeclaringClass();
int entryType;
if (Library.isField(member))
entryType=9; // CONSTANT_Fieldref = 9;
else if ((dClass!=null) && (dClass.isInterface()))
entryType=11; // CONSTANT_InterfaceMethodref = 11;
else
entryType=10; // CONSTANT_Methodref = 10;
newIndex=writeMemberRef(member,entryType);
break;
default:
if (Debug.enabled)
Debug.println("Can't place an item of type \""+
item.getClass().getName()+
"\" to the constant pool.");
};
} catch (java.io.IOException e) {
if (Debug.enabled) Debug.reportThrowable(e);
};
index=new Integer(newIndex);
Items.put(item,index);
};
return index.intValue();
};
// writes out full reference to method, interface or field
// this includes UTFs, Name&Type and XXX_ref entries
private int writeMemberRef(Member member, int entry)
throws java.io.IOException {
if (Debug.enabled)
Debug.check((entry==10)||(entry==9)||(entry==11));
// CONSTANT_Fieldref = 9; CONSTANT_Methodref = 10;
// CONSTANT_InterfaceMethodref = 11;
int name_ind=getUTFIndex((member instanceof Constructor)?" Specifics of JEL generated classes is that the class name UTF8 is always
* the first entry in the constant pool. This loader will not load
* other classes.
*/
public class ImageLoader extends ClassLoader {
String name;
byte[] bytes;
Class c;
ClassLoader parent;
private ImageLoader(String name, byte[] bytes) {
this.name=name;
this.bytes=bytes;
this.c=null;
this.parent=this.getClass().getClassLoader();
};
/**
* Loads given JEL-generated image under its own name.
* @param image to load
* @return the class object for the new class or null
* if unsuccessful.
*/
public static Class load(byte[] image) {
if (Debug.enabled)
Debug.check(image[10]==1,
"Attempt to load non-JEL generated class file");
// JEL generated class file never have UNICODE class name
// although they might reference UNICODE methods, etc...
int len=(image[11]<<8)+image[12];
char[] nameChr=new char[len];
for(int i=0;i Example: "gnu.jel.generated.E_"
// */
// public static String classNamePrefix="gnu.jel.generated.E_";
// /**
// * Loads given JEL-generated image under unique name.
// * The unique name is generated by appending a steadily incremented
// * number to the classNamePrefix.
// * @param image to load
// * @return the class object for the new class or null
// * if unsuccessful.
// * @see gnu.jel.ImageLoader#classNamePrefix
// */
// public static Class loadRenamed(byte[] image) {
// if (Debug.enabled)
// Debug.check(image[10]==1,
// "Attempt to load non-JEL generated class file");
// String newname=classNamePrefix+Long.toString(expressionUID++);
// String newnameHF=TypesStack.toHistoricalForm(newname);
// // JEL generated class file never have UNICODE class name
// // although they might reference UNICODE methods, etc...
// int len=(image[11]<<8)+image[12];
// int newlen=newname.length();
// byte[] newimage=new byte[image.length-len+newlen];
// System.arraycopy(image,0,newimage,0,11);
// newimage[11]=(byte)(newlen>>8);
// newimage[12]=(byte)newlen;
// for(int i=0;i On entry the paramOPs should contain 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:
* 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 gnu.jel.Library
* @see gnu.jel.Evaluator
*/
public abstract class CompiledExpression {
/**
* Returns type of the expression result.
* The type is encoded in integer. Following table could help
* in determining what it is :
* 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.
* @return the type of the expression, encoded in integer.
*/
public abstract int getType();
/**
* 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.
*/
public abstract Class getTypeC();
/**
* 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,...
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public Object evaluate(Object[] dl) throws Throwable {
int type=getType();
Object res=null;
switch (type) {
case 0: res=new Boolean(evaluate_boolean(dl)); break;
case 1: res=new Byte(evaluate_byte(dl)); break;
case 2: res=new Character(evaluate_char(dl)); break;
case 3: res=new Short(evaluate_short(dl)); break;
case 4: res=new Integer(evaluate_int(dl)); break;
case 5: res=new Long(evaluate_long(dl)); break;
case 6: res=new Float(evaluate_float(dl)); break;
case 7: res=new Double(evaluate_double(dl)); break;
case 9: evaluate_void(dl); break;
default:
if (Debug.enabled)
Debug.check(false,"WrongTypeReturned from "+
"CompiledExpression.getType().");
};
return res;
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public boolean evaluate_boolean(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return false;
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public byte evaluate_byte(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return 0;
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public short evaluate_short(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return 0;
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public char evaluate_char(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return '?';
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public int evaluate_int(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return 0;
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public long evaluate_long(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return 0L;
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public float evaluate_float(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return 0.0F;
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @return the result fo computation.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public double evaluate_double(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return 0.0D;
};
/**
* 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.
* @param dl Array of the instance references to the objects in dynamic
* library. See description of this class above for more details.
* @exception Throwable if any runtime error have occured (i.e. division
* by 0)
* @see gnu.jel.Evaluator#compile
* @see gnu.jel.Library
*/
public void evaluate_void(Object[] dl) throws Throwable {
if (Debug.enabled)
Debug.println("Wrong evaluateXXXX() method called,"+
" check value of getType().");
return;
};
// String and object comparisons
private static java.text.Collator collator=null;
public static int compare(String s1,String s2) {
if (collator==null)
collator = java.text.Collator.getInstance();
return collator.compare(s1,s2);
};
};
source/src/java/gnu/jel/OPbinary.java 0000644 0001750 0001750 00000026303 12714113765 016520 0 ustar oles oles /* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* This file is part of the Java Expressions Library (JEL).
* For more information about JEL visit : http://fti.dn.ua/JEL/
*
* Copyright (C) 1998, 1999, 2000, 2001, 2003, 2006, 2007, 2009 Konstantin L. Metlov
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see Codes are following:
*
*
* If methods in the library classes conflict with each other, the last
* conflicting method will be skipped. You will not get any messages unless
* debugging is ON (see gnu.jel.debug.Debug.enabled). This is
* done to avoid unnecessary error messages in the production code of the
* compiler.
*
* you ask for a call someName(int, int), but there are two
* applicable methods someName(int, double) and
* someName(double, int). Requirements to parameter types
* of both can be satisfied by _widening_ conversions. Thus, there
* is no most specific method of these two in terms of Java Language
* Specification (15.11.2.2). It means, that an ambiguity is present,
* and null will be returned.
*
* CompiledExpression expression=compile("2*6+6",lib,Double.TYPE);
*
* will produce a compiled expression, whose return type is always
* double. For additional information on how to use this
* feature to eliminate object allocation overhead see
* gnu.jel.CompiledExpression documentation.
*
*
* Prague, CZ
* @see gnu.jel.CompiledExpression
* @see gnu.jel.Library
*/
public class Evaluator {
protected static ClassFile cf_orig;
protected static int retID_patchback=0;
protected static int retIDC_patchback=0;
protected static LocalMethod[] eval_methods= new LocalMethod[10];
static {
try {
// prepare eval methods
Class[] paramsE=new Class[1];
paramsE[0]=(new Object[0]).getClass();
Class[] excptnsE=new Class[1];
excptnsE[0]=Class.forName("java.lang.Throwable");
for(int i=0;i<10;i++) {
String name="evaluate";
Class cls=OP.specialTypes[i];
if (i!=8)
name=name+'_'+cls;
else
cls=(new Object()).getClass();
eval_methods[i]=new LocalMethod(0x0001,cls,name,paramsE,excptnsE);
};
Class cmplExpr=Class.forName("gnu.jel.CompiledExpression");
ClassFile cf=new ClassFile(0x0001,"dump",cmplExpr,null,null);
// public
LocalMethod cnstr=
new LocalMethod(0x0001,Void.TYPE,"
None of these functions does anything if Debug.enabled is false.
*
If you really want to throw ALL debug messages from the final,
* compiler generated, code -- wrap calls to Debug methods into the
* if statement, checking Debug.enabled constant.
* As shown in the example :
*
* import cz.fzu.metlov.jel.*;
* ..... BLA BLA BLA ...
* if (Debug.enabled) {
* Debug.println("I want this message to disappear in the optimized version");
* Debug.check(foo==superTimeConsumingFunction(bar),
* "I do not want to evaluate superTimeConsumingFunction(), when optimized.");
* };
*
*/
public final class Debug {
/**
* Determines if debugging is enabled in current compilation.
*/
public final static boolean enabled=@DEBUG@; // <-- AUTO GENERATED
/**
* Prints a line of the debug output.
* The resulting line goes to System.err and is prefixed by "[DEBUG] ".
* @param message message to print.
*/
public final static void println(String message) {
if (enabled) {
System.err.print("[DEBUG] ");
System.err.println(message);
};
};
/**
* Checks for the condition.
* If condition is false this function prints a given message
* to the System.err along with the stack trace.
* @param condition is the condition to check.
* @param message is the message to print if condition is false.
*/
public final static void check(boolean condition, String message) {
if (enabled && (!condition)) {
System.err.print("Assertion failed :");
System.err.println(message);
Throwable tracer=new Throwable(message);
tracer.printStackTrace();
};
};
/**
* Checks for the condition.
* If condition is false this function prints a "Assertion failed."
* to the System.err along with the stack trace.
* @param condition is the condition to check.
*/
public final static void check(boolean condition) {
if (enabled && (!condition)) {
Throwable tracer=new Throwable("Assertion failed.");
tracer.printStackTrace();
};
};
/**
* Reports an exception, which should not occur(i.e. handled improperly).
* @param t is what was thrown.
* @param message is algorithm specific message.
*/
public final static void reportThrowable(Throwable t,String message) {
if (enabled) {
System.err.println("Unexpected exception has occured :");
System.err.println(message);
t.printStackTrace();
};
};
/**
* Reports an exception, which should not occur(i.e. handled improperly).
* @param t is what was thrown.
*/
public final static void reportThrowable(Throwable t) {
if (enabled) {
System.err.println("Unexpected exception has occured :");
t.printStackTrace();
};
};
};
source/src/java/gnu/jel/OP.java 0000644 0001750 0001750 00000020127 12714113765 015311 0 ustar oles oles /* -*- Mode: Java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* This file is part of the Java Expressions Library (JEL).
* For more information about JEL visit : http://fti.dn.ua/JEL/
*
* Copyright (C) 1998, 1999, 2000, 2001, 2003, 2006, 2007, 2009 Konstantin L. Metlov
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see
* 0 -- negation (applicable to anything except boolean)
* 1 -- bitwise not (applicable to all integral types)
* 2 -- logical not (applicable to booleans only)
* 3 -- return the type in stack
*
* @param paramOPs stack holding the operands
* @param code operation code
*/
public OPunary(Stack
* 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(...)
* -----------------------------------
*
*
* getType() | method to call
* ------------+-----------------
* 0 | boolean
* 1 | byte
* 2 | char
* 3 | short
* 4 | int
* 5 | long
* 6 | float
* 7 | double
* 8 | Object
* 9 | void
*
*
* 0 -- addition
* 1 -- substraction
* 2 -- multiplication
* 3 -- division
* 4 -- remainder
* 5 -- bitwise AND
* 6 -- bitwise OR
* 7 -- bitwise and logical XOR
* 8 -- comparizon for equality
* 9 -- comparizon for non-equality
* 10 -- comparizon for "less" <
* 11 -- comparizon for "greater or equal" >=
* 12 -- comparizon for "greater" >
* 13 -- comparizon for "less or equal" <=
* 14 -- bitwise left shift <<
* 15 -- bitwise right signed shift >>
* 16 -- bitwise right unsigned shift >>>
* 17 -- logical conjunction operator (AND)
* 18 -- logical disjunction operator (OR)
* 19 -- array element access operation
* 20 -- reserved (used internally for string concatenation)
*
* @param paramOPs stack holding the operands
* @param opcode is the operation code
*/
public OPbinary(Stack