LiquidCore as a Native Javascript Engine

JavaScript API

LiquidCore is built on top of Node.js, which is in turn built on V8. So, the V8 API is natively available to any app which includes the LiquidCore library. In addition to directly interacting with V8 (a powerful, but incredibly complex API), LiquidCore provides two additional APIs: a Java Native Interface (JNI) API for Android, and a JavaScriptCore API for iOS and React Native.

Java Native Interface (JNI) for Android

The JNI is a near drop-in replacement for AndroidJSCore. In fact, development on AndroidJSCore has ceased and is superseded by LiquidCore. See the Javadocs for complete documentation of the API. If you have been using AndroidJSCore, the interface will look familiar. To migrate from AndroidJSCore, you must:

1. Replace the AndroidJSCore library with the LiquidCore library in build.gradle
2. Change the package name from org.liquidplayer.webkit.javascriptcore to org.liquidplayer.javascript in all of your source files
3. Fix any inconsistencies between the versions. There aren't many. It is 99% the same.

Otherwise, to get started, you need to create a JavaScript JSContext. The execution of JS code occurs within this context, and separate contexts are isolated virtual machines which do not interact with each other.

JSContext context = new JSContext();

This context is itself a JavaScript object. And as such, you can get and set its properties. Since this is the global JavaScript object, these properties will be in the top-level context for all subsequent code in the environment.

context.property("a", 5);
JSValue aValue = context.property("a");
double a = aValue.toNumber();
DecimalFormat df = new DecimalFormat(".#");
System.out.println(df.format(a)); // 5.0

You can also run JavaScript code in the context:

context.evaluateScript("a = 10");
JSValue newAValue = context.property("a");
System.out.println(df.format(newAValue.toNumber())); // 10.0
String script =
  "function factorial(x) { var f = 1; for(; x > 1; x--) f *= x; return f; }\n" +
  "var fact_a = factorial(a);\n";
context.evaluateScript(script);
JSValue fact_a = context.property("fact_a");
System.out.println(df.format(fact_a.toNumber())); // 3628800.0

You can also write functions in Java, but expose them to JavaScript:

JSFunction factorial = new JSFunction(context,"factorial") {
    public Integer factorial(Integer x) {
        int factorial = 1;
        for (; x > 1; x--) {
        	   factorial *= x;
        }
        return factorial;
    }
};

This creates a JavaScript function that will call the Java method factorial when called from JavaScript. It can then be passed to the JavaScript VM:

context.property("factorial", factorial);
context.evaluateScript("var f = factorial(10);")
JSValue f = context.property("f");
System.out.println(df.format(f.toNumber())); // 3628800.0

JavaScriptCore API

There are two major open source JavaScript implementations: V8, which is popularized by Google Chrome, and JavaScriptCore, which is part of WebKit, backed by Apple's Safari. LiquidCore uses V8, simply because it is built on Node.js, which is difficult to decouple from V8. However, the JavaScriptCore API has a few advantages: (1) it is far simpler to use than V8, (2) it is a familiar interface to iOS developers as the JavaScriptCore framework has been available since iOS 7, and (3) other very useful projects, like React Native require the library. So, to take advantage of this, LiquidCore provides a JavaScriptCore -> V8 bridge, where projects that require the JavaScriptCore API can use the V8 backend with little or no modification.

To use the JSC->V8 bridge, the setup is a bit complicated. This is because there is no JNI support for it, and instead is only supported at the native (NDK) level. Your NDK project must use the JSC header files in deps/JavaScriptCore/include and compile and link the file deps/jscshim/JSCShim.cpp. Then, prior to using the library, call JSCShim.staticInit() from Java. This will get the two libraries talking to each other at the C/C++ level.