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.

WARNING: This API is experimental and might change in incompatible ways in the next release.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Map<String,MethodHandle>`
`DEFAULT_FUNCTIONS`
The default set of functions available to expressions.

## Method Summary

Modifier and Type
Method
Description
`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.
`static Map<String,MethodHandle>`
`convertLegacyFunctions(Map<String,Method> functions)`
Deprecated.
Only use this to convert Lucene 9.x or earlier legacy code.

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

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

## Field Details

### 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.

## Method Details

### 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 `MethodHandle`s
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`.