Module org.apache.lucene.expressions

Package org.apache.lucene.expressions.js

Class JavascriptCompiler

java.lang.Object

org.apache.lucene.expressions.js.JavascriptCompiler

public final class JavascriptCompiler
extends Object

An expression compiler for javascript expressions.

Example:

   Expression foo = JavascriptCompiler.compile("((0.3*popularity)/10.0)+(0.7*score)");
 

See the package documentation for the supported syntax and default functions.

You can compile with an alternate set of functions via compile(String, Map). For example:

   Map<String,MethodHandle> functions = new HashMap<>();
   // add all the default functions
   functions.putAll(JavascriptCompiler.DEFAULT_FUNCTIONS);
   // add cbrt()
   functions.put("cbrt", MethodHandles.publicLookup().findStatic(Math.class, "cbrt",
                 MethodType.methodType(double.class, double.class)));
   // call compile with customized function map
   Expression foo = JavascriptCompiler.compile("cbrt(score)+ln(popularity)",
                                               functions);
 

It is possible to pass any MethodHandle as function that only takes double parameters and returns a double. The method does not need to be public, it just needs to be resolved correctly using a private MethodHandles.Lookup instance. Ideally the methods should be static, but you can use MethodHandle.bindTo(Object) to bind it to a receiver.

Field Summary

Fields

Modifier and Type	Field	Description
private static final int	CLASSFILE_VERSION
private static final String	COMPILED_EXPRESSION_CLASS
private static final String	COMPILED_EXPRESSION_INTERNAL
static final Map<String,MethodHandle>	DEFAULT_FUNCTIONS	The default set of functions available to expressions.
private static final org.objectweb.asm.commons.Method	DOUBLE_VAL_METHOD
private static final org.objectweb.asm.Handle	DYNAMIC_CONSTANT_BOOTSTRAP_HANDLE
private static final org.objectweb.asm.Type[]	EVALUATE_EXCEPTIONS
private static final org.objectweb.asm.commons.Method	EVALUATE_METHOD
private static final org.objectweb.asm.commons.Method	EXPRESSION_CTOR
private static final org.objectweb.asm.Type	EXPRESSION_TYPE
private static final org.objectweb.asm.Type	FUNCTION_VALUES_TYPE
(package private) final Map<String,MethodHandle>	functions
private static final org.objectweb.asm.Type	JAVASCRIPT_COMPILER_TYPE
private static final MethodHandles.Lookup	LOOKUP
private static final org.objectweb.asm.Type	METHOD_HANDLE_TYPE
private static final MethodType	MT_EXPRESSION_CTOR_LOOKUP
private static final org.objectweb.asm.commons.Method	PATCH_STACK_METHOD
(package private) final boolean	picky
(package private) final String	sourceText
private static final org.objectweb.asm.Type	THROWABLE_TYPE

Constructor Summary

Constructors

Modifier	Constructor	Description
private	JavascriptCompiler(String sourceText, Map<String,MethodHandle> functions, boolean picky)	Constructs a compiler for expressions with specific set of functions

Method Summary

Modifier and Type	Method	Description
private static void	checkFunction(MethodHandle method)	Check Method signature for compatibility.
static Expression	compile(String sourceText)	Compiles the given expression using default compiler settings.
static Expression	compile(String sourceText, Map<String,MethodHandle> functions)	Compiles the given expression with the supplied custom functions using default compiler settings.
(package private) static Expression	compile(String sourceText, Map<String,MethodHandle> functions, boolean picky)	Compiles the given expression with the supplied custom functions.
private Expression	compileExpression()	Compiles the given expression as hidden class.
static Map<String,MethodHandle>	convertLegacyFunctions(Map<String,Method> functions)	Deprecated. Only use this to convert Lucene 9.x or earlier legacy code.
(package private) static MethodHandle	dynamicConstantBootstrap(MethodHandles.Lookup lookup, String constantName, Class<?> type, String functionName)	Bootstrap method for dynamic constants.
(package private) static int	findSingleQuoteStringEnd(String text, int start)
private void	generateClass(org.antlr.v4.runtime.tree.ParseTree parseTree, org.objectweb.asm.ClassWriter classWriter, Map<String,Integer> externalsMap)	Sends the bytecode of class file to ClassWriter.
private org.antlr.v4.runtime.tree.ParseTree	getAntlrParseTree()	Parses the sourceText into an ANTLR 4 parse tree
private static org.objectweb.asm.commons.Method	getAsmMethod(Class<?> rtype, String name, Class<?>... ptypes)	create an ASM Method object from return type, method name, and parameters.
private Expression	invokeConstructor(MethodHandles.Lookup lookup, Class<?> expressionClass, Map<String,Integer> externalsMap)
private static Map<String,MethodHandle>	loadDefaultFunctions()
(package private) static String	normalizeQuotes(String text)
(package private) static Throwable	patchStackTrace(Throwable t, Expression impl)	Method called from try/catch handler in compiled expression.
private void	setupPicky(JavascriptParser parser)

Methods inherited from class java.lang.Object

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

Field Details

LOOKUP

private static final MethodHandles.Lookup LOOKUP

CLASSFILE_VERSION

private static final int CLASSFILE_VERSION

See Also:

• Constant Field Values

MT_EXPRESSION_CTOR_LOOKUP

private static final MethodType MT_EXPRESSION_CTOR_LOOKUP

COMPILED_EXPRESSION_CLASS

private static final String COMPILED_EXPRESSION_CLASS

COMPILED_EXPRESSION_INTERNAL

private static final String COMPILED_EXPRESSION_INTERNAL

EXPRESSION_TYPE

private static final org.objectweb.asm.Type EXPRESSION_TYPE

FUNCTION_VALUES_TYPE

private static final org.objectweb.asm.Type FUNCTION_VALUES_TYPE

METHOD_HANDLE_TYPE

private static final org.objectweb.asm.Type METHOD_HANDLE_TYPE

JAVASCRIPT_COMPILER_TYPE

private static final org.objectweb.asm.Type JAVASCRIPT_COMPILER_TYPE

THROWABLE_TYPE

private static final org.objectweb.asm.Type THROWABLE_TYPE

EXPRESSION_CTOR

private static final org.objectweb.asm.commons.Method EXPRESSION_CTOR

EVALUATE_METHOD

private static final org.objectweb.asm.commons.Method EVALUATE_METHOD

DOUBLE_VAL_METHOD

private static final org.objectweb.asm.commons.Method DOUBLE_VAL_METHOD

PATCH_STACK_METHOD

private static final org.objectweb.asm.commons.Method PATCH_STACK_METHOD

EVALUATE_EXCEPTIONS

private static final org.objectweb.asm.Type[] EVALUATE_EXCEPTIONS

DYNAMIC_CONSTANT_BOOTSTRAP_HANDLE

private static final org.objectweb.asm.Handle DYNAMIC_CONSTANT_BOOTSTRAP_HANDLE

sourceText

final String sourceText

functions

final Map<String,MethodHandle> functions

picky

final boolean picky

DEFAULT_FUNCTIONS

public static final Map<String,MethodHandle> DEFAULT_FUNCTIONS

The default set of functions available to expressions.

See the package documentation for a list.

Constructor Details

JavascriptCompiler

private JavascriptCompiler(String sourceText,
 Map<String,MethodHandle> functions,
 boolean picky)

Constructs a compiler for expressions with specific set of functions

Parameters:

sourceText - The expression to compile

Method Details

getAsmMethod

private static org.objectweb.asm.commons.Method getAsmMethod(Class<?> rtype,
 String name,
 Class<?>... ptypes)

create an ASM Method object from return type, method name, and parameters.

compile

public static Expression compile(String sourceText)
                          throws ParseException

Compiles the given expression using default compiler settings.

Parameters:

sourceText - The expression to compile

Returns:

A new compiled expression

Throws:

ParseException - on failure to compile

compile

public static Expression compile(String sourceText,
 Map<String,MethodHandle> functions)
                          throws ParseException

Compiles the given expression with the supplied custom functions using default compiler settings.

Functions must be public static, return double and can take from zero to 256 double parameters.

Parameters:

sourceText - The expression to compile

functions - map of String names to MethodHandles

Returns:

A new compiled expression

Throws:

ParseException - on failure to compile

convertLegacyFunctions

@Deprecated
public static Map<String,MethodHandle> convertLegacyFunctions(Map<String,Method> functions)
                                                       throws IllegalAccessException

Deprecated.

Only use this to convert Lucene 9.x or earlier legacy code. For new code use MethodHandle.

Converts a legacy map with reflective Method functions to Map<String,MethodHandle for use with compile(String, Map).

Parameters:

functions - a map with only public and accessible reflective methods

Returns:

a new (modifiable) map with the same function declarations, but converted to MethodHandle

Throws:

IllegalAccessException - if any of the methods in functions are not accessible by the public MethodHandles.Lookup.

compile

static Expression compile(String sourceText,
 Map<String,MethodHandle> functions,
 boolean picky)
                   throws ParseException

Compiles the given expression with the supplied custom functions.

Functions must be public static, return double and can take from zero to 256 double parameters.

Parameters:

sourceText - The expression to compile

functions - map of String names to MethodHandles

picky - whether to throw exception on ambiguity or other internal parsing issues (this option makes things slower too, it is only for debugging).

Returns:

A new compiled expression

Throws:

ParseException - on failure to compile

compileExpression

private Expression compileExpression()
                              throws ParseException

Compiles the given expression as hidden class.

Returns:

A new compiled expression

Throws:

ParseException - on failure to compile

invokeConstructor

private Expression invokeConstructor(MethodHandles.Lookup lookup,
 Class<?> expressionClass,
 Map<String,Integer> externalsMap)
                              throws ReflectiveOperationException

Throws:

ReflectiveOperationException

getAntlrParseTree

private org.antlr.v4.runtime.tree.ParseTree getAntlrParseTree()
                                                       throws ParseException

Parses the sourceText into an ANTLR 4 parse tree

Returns:

The ANTLR parse tree

Throws:

ParseException - on failure to parse

setupPicky

private void setupPicky(JavascriptParser parser)

generateClass

private void generateClass(org.antlr.v4.runtime.tree.ParseTree parseTree,
 org.objectweb.asm.ClassWriter classWriter,
 Map<String,Integer> externalsMap)
                    throws ParseException

Sends the bytecode of class file to ClassWriter.

Throws:

ParseException

normalizeQuotes

static String normalizeQuotes(String text)

findSingleQuoteStringEnd

static int findSingleQuoteStringEnd(String text,
 int start)

loadDefaultFunctions

private static Map<String,MethodHandle> loadDefaultFunctions()

checkFunction

private static void checkFunction(MethodHandle method)

Check Method signature for compatibility.

dynamicConstantBootstrap

static MethodHandle dynamicConstantBootstrap(MethodHandles.Lookup lookup,
 String constantName,
 Class<?> type,
 String functionName)
                                      throws IllegalAccessException

Bootstrap method for dynamic constants. This returns a MethodHandle for the functionName from the class data passed via MethodHandles.Lookup.defineHiddenClassWithClassData(byte[], java.lang.Object, boolean, java.lang.invoke.MethodHandles.Lookup.ClassOption...). The constantName is ignored.

Throws:

IllegalAccessException

patchStackTrace

static Throwable patchStackTrace(Throwable t,
 Expression impl)

Method called from try/catch handler in compiled expression. This patches the stack trace and adds back a hidden frame (including the source code of script as filename).