Changeset 13626


Ignore:
Timestamp:
10/12/11 21:13:12 (10 years ago)
Author:
astalla
Message:

Manual: documented the JSR-223 implementation.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/abcl/doc/manual/abcl.tex

    r13625 r13626  
    444444    }
    445445\end{listing-java}
    446    
     446
    447447A more Lispy way to iterated down a list is to use the `cdr()` access
    448448function just as like one would traverse a list in Lisp:;
     
    456456\end{listing-java}
    457457
     458\subsection{Java Scripting API (JSR-223)}
     459
     460ABCL can be built with support for JSR-223, which offers a language-agnostic
     461API to invoke other languages from Java. The binary distribution downloadable
     462from ABCL's common-lisp.net home is built with JSR-223 support. If you're building
     463ABCL from source on a pre-1.6 JVM, you need to have a JSR-223 implementation in your
     464CLASSPATH (such as Apache Commons BSF 3.x or greater) in order to build ABCL
     465with JSR-223 support; otherwise, this feature will not be built.
     466
     467This section 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/jsr-223 for example usage.
     468
     469\subsubsection{Conversions}
     470
     471In general, ABCL's implementation of the JSR-223 API performs implicit conversion from Java objects to Lisp objects when invoking Lisp from Java, and the opposite when returning values from Java to Lisp. This potentially reduces coupling between user code and ABCL. To avoid such conversions, wrap the relevant objects in \code{JavaObject} instances.
     472
     473\subsubsection{Implemented JSR-223 interfaces}
     474
     475JSR-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. While the JSR-223 API is not specific to a single scripting language, it 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.
     476
     477\subsubsection{The ScriptEngine}
     478
     479The main interface defined by JSR-223, javax.script.ScriptEngine, is implemented by the class \code{org.armedbear.lisp.scripting.AbclScriptEngine}. AbclScriptEngine is a singleton, reflecting the fact that ABCL is a singleton as well. 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).
     480
     481\subsubsection{Startup and configuration file}
     482
     483At 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:
     484
     485\begin{itemize}
     486\item *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.
     487  \begin{itemize}
     488  \item Default value: T
     489  \item 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.
     490  \item 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.
     491  \end{itemize}
     492\item *launch-swank-at-startup* If true, Swank will be launched at startup. See *swank-dir* and *swank-port*.
     493  \begin{itemize}
     494  \item Default value: NIL
     495  \end{itemize}
     496\item *swank-dir* The directory where Swank is installed. Must be set if *launch-swank-at-startup* is true.
     497\item *swank-port* The port where Swank will listen for connections. Must be set if *launch-swank-at-startup* is true.
     498  \begin{itemize}
     499  \item Default value: 4005
     500  \end{itemize}
     501\end{itemize}
     502
     503Additionally, at startup the AbclScriptEngine will \code{(require 'asdf)} - in fact, it uses asdf to load Swank.
     504
     505\subsubsection{Evaluation}
     506
     507Code is read and evaluated in the package ABCL-SCRIPT-USER. This packages USEs the COMMON-LISP, JAVA and ABCL-SCRIPT packages. Future versions of the script engine might make this default package configurable. The \code{CL:LOAD} function is used under the hood for evaluating code, and thus the same behavior of LOAD is guaranteed. This allows, among other things, \code{IN-PACKAGE} forms to change the package in which the loaded code is read.
     508
     509It is possible to evaluate code in what JSR-223 calls a "ScriptContext" (basically a flat environment of name->value pairs). This context is used to establish special bindings for all the variables defined in it; since variable names are strings from Java's point of view, they are first interned using READ-FROM-STRING with, as usual, ABCL-SCRIPT-USER as the default package. Variables are declared special because CL's \code{LOAD}, \code{EVAL} and \code{COMPILE} functions work in a null lexical environment and would ignore non-special bindings.
     510
     511Contrary to what the function \code{LOAD} does, evaluation of a series of forms returns the value of the last form instead of T, so the evaluation of short scripts does the Right Thing.
     512
     513\subsubsection{Compilation}
     514
     515AbclScriptEngine implements the javax.script.Compilable interface. Currently it only supports compilation using temporary files. Compiled code, returned as an instance of javax.script.CompiledScript, is read, compiled and executed by default in the ABCL-SCRIPT-USER package, just like evaluated code. Differently from evaluated code, though, due to the way the ABCL compiler works, compiled code contains no reference to top-level self-evaluating objects (like numbers or strings). Thus, when evaluated, a piece of compiled code will return the value of the last non-self-evaluating form: for example the code "(do-something) 42" will return 42 when interpreted, but will return the result of (do-something) when compiled and later evaluated. To ensure consistency of behavior between interpreted and compiled code, make sure the last form is always a compound form - at least (identity some-literal-object). Note that this issue should not matter in real code, where it is unlikely a top-level self-evaluating form will appear as the last form in a file (in fact, the Common Lisp load function always returns T upon success; with JSR-223 this policy has been changed to make evaluation of small code snippets work as intended).
     516
     517\subsubsection{Invocation of functions and methods}
     518
     519AbclScriptEngine implements the \code{javax.script.Invocable} interface, which allows to directly call Lisp functions and methods, and to obtain Lisp implementations of Java interfaces. This is only partially possible with Lisp since it has functions, but not methods - not in the traditional OO sense, at least, since Lisp methods are not attached to objects but belong to generic functions. Thus, the method \code{invokeMethod()} is not implemented and throws an UnsupportedOperationException when called. The \code{invokeFunction()} method should be used to call both regular and generic functions.
     520
     521\subsubsection{Implementation of Java interfaces in Lisp}
     522
     523ABCL can use the Java reflection-based proxy feature to implement Java interfaces in Lisp. It has several built-in ways to implement an interface, and supports definition of new ones. The \code{JAVA:JMAKE-PROXY} generic function is used to make such proxies. It has the following signature:
     524
     525\code{jmake-proxy interface implementation \&optional lisp-this ==> proxy}
     526
     527\code{interface} is a Java interface metaobject (e.g. obtained by invoking \code{jclass}) or a string naming a Java interface. \code{implementation} is the object used to implement the interface - several built-in methods of jmake-proxy exist for various types of implementations. \code{lisp-this} is an object passed to the closures implementing the Lisp "methods" of the interface, and defaults to \code{NIL}.
     528
     529The returned proxy is an instance of the interface, with methods implemented with Lisp functions.
     530
     531Built-in interface-implementation types include:
     532
     533\begin{itemize}
     534\item a single Lisp function which upon invocation of any method in the interface will be passed the method name, the Lisp-this object, and all the parameters. Useful for interfaces with a single method, or to implement custom interface-implementation strategies.
     535\item a hash-map of method-name -> Lisp function mappings. Function signature is \code{(lisp-this \&rest args)}.
     536\item a Lisp package. The name of the Java method to invoke is first transformed in an idiomatic Lisp name (\code{javaMethodName} becomes \code{JAVA-METHOD-NAME}) and a symbol with that name is searched in the package. If it exists and is fbound, the corresponding function will be called. Function signature is as the hash-table case.
     537\end{itemize}
     538
     539This functionality is exposed by the AbclScriptEngine with the two methods getInterface(Class) and getInterface(Object, Class). The former returns an interface implemented with the current Lisp package, the latter allows the programmer to pass an interface-implementation object which will in turn be passed to the jmake-proxy generic function.
     540
    458541\chapter{Implementation Dependent Extensions}
    459542
     
    468551
    469552The JAVA:ADD-TO-CLASSPATH generic functions allows one to add the
    470 specified pathname or list of pathnames to the current JVM classpath
    471 allowing the dynamic loading of JVM objects:
     553specified pathname or list of pathnames to the current classpath
     554used by ABCL, allowing the dynamic loading of JVM objects:
    472555
    473556\begin{listing-lisp}
    474557CL-USER> (add-to-classpath "/path/to/some.jar")
    475558\end{listing-lisp}
     559
     560NB \code{add-to-classpath} only affects the classloader used by ABCL
     561(the value of the special variable \code{JAVA:*CLASSLOADER*}. It has
     562no effect on Java code outside ABCL.
    476563
    477564\subsection{API}
     
    571658
    572659\begin{listing-lisp}
     660CL-USER> (require 'java-collections)
     661\end{listing-lisp}
     662
     663if both extensible sequences and their application to Java collections
     664is required, or
     665
     666\begin{listing-lisp}
    573667CL-USER> (require 'extensible-sequences)
    574668\end{listing-lisp}
     669
     670if only the extensible sequences API as specified in \ref{RHODES2007} is
     671required.
     672
     673Note that \code{(require 'java-collections)} must be issued before
     674\code{java.util.List} or any subclass is used as a specializer in a CLOS
     675method definition (see the section below).
    575676
    576677\section{Extensions to CLOS}
     
    632733\chapter{Contrib}
    633734
    634 \section{abcl-asdf} 
     735\section{abcl-asdf}
    635736
    636737Allow ASDF system definition which dynamically loads JVM artifacts
     
    662763lot of code that had previously not been released publically was
    663764suddenly committed that enabled ABCL to be plausibly termed an ANSI
    664 Common Lisp implementation. 
     765Common Lisp implementation.
    665766
    666767In 2006, the implementation was transferred to the current
Note: See TracChangeset for help on using the changeset viewer.