JSR-223 support in ABCL

ABCL is integrated with the Java Scripting API (JSR-223, package javax.script) which is built-in in Java 6.

This page describes the design decisions behind the ABCL JSR-223 support. It is not a description of what JSR-223 is or a tutorial on how to use it. See ​http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples/abcl/jsr-223 for example usage.

Implemented interfaces

JSR-223 defines three main interfaces, of which two (Invocable and Compilable) are optional. ABCL implements all the three interfaces - ScriptEngine and the two optional ones - almost completely. The JSR-223 API is not specific to a single scripting language, however was designed with languages with a more or less Java-like object model in mind: languages such as Javascript, Python, Ruby, which have a concept of "class" or "object" with "fields" and "methods". Lisp is a bit different, so certain adaptations were made, and in one case a method has been left unimplemented since it does not map at all to Lisp.

ScriptEngine

The main interface defined by JSR-223, javax.script.ScriptEngine, is implemented by the class ​org.armedbear.lisp.scripting.AbclScriptEngine. AbclScriptEngine is intended to be a singleton, even if it has a public constructor - which will probably be made protected in future versions of the engine. You can obtain an instance of AbclScriptEngine using the ​AbclScriptEngineFactory or by using the service provider mechanism through ScriptEngineManager (refer to the javax.script documentation).

Configuration file

At startup (i.e. when its constructor is invoked, as part of the static initialization phase of AbclScriptEngineFactory) the ABCL script engine attempts to load an "init file" from the classpath (/abcl-script-config.lisp). If present, this file can be used to customize the behaviour of the engine, by setting a number of variables in the ABCL-SCRIPT package. Here is a list of the available variables:

• *use-throwing-debugger* Controls whether ABCL uses a non-standard debugging hook function to throw a Java exception instead of dropping into the debugger in case of unhandled error conditions.
  • Default value: T.
  • Rationale: it is more convenient for Java programmers using Lisp as a scripting language to have it return exceptions to Java instead of handling them in the Lisp world.
  • Known Issues: the non-standard debugger hook has been reported to misbehave in certain circumstances, so consider disabling it if it doesn't work for you.

TBD