abcl.tex 66.4 KB
 mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 1 % -*- mode: latex; -*-  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 2 % http://en.wikibooks.org/wiki/LaTeX/  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 3 \documentclass[10pt]{book}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 08, 2017 4 5 % also need to have cm-super installed for high quality rendering \usepackage[T1]{fontenc}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 6 \usepackage{abcl}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 7   8 9 \usepackage{hyperref} % Put this one last, it redefines lots of internals  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 10 \begin{document}  11 \title{Armed Bear Common Lisp User Manual}  12 \date{Version 1.5.0-rc-1\\  13 \smallskip  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 07, 2017 14 June 2017}  15 16 \author{Mark Evenson \and Erik H\"{u}lsmann \and Rudolf Schlatte \and Alessio Stalla \and Ville Voutilainen}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 17   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 18 19 \maketitle  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 22, 2011 20 \tableofcontents  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 07, 2017 21 22 23 24 25 26 27 %%Preface to the Sixth edition, abcl-1.5.0 \subsection{Preface to the Sixth Edition} With the sixth major release of the implementation, we make the following explicit revision of our compatibility to the underlying JVM. Since we are an open source implementation, we insist on possible open access to the sources from with an JDK may both be built  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 08, 2017 28 and run upon. This requirement is no longer met by Java 5, so  29 henceforth with the release of \textsc{ABCL} 1.5, we will support  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 08, 2017 30 Java 6, Java 7 and Java 8 runtimes.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 07, 2017 31 32 33  %% We should probably not release a 1.5.0, go straight for abcl-1.6.0? %% Not worth the effort: Java 9 is the current abcl-1.6.0 release driver.  34 35 36 37 38  %%Preface to the Fifth edition, abcl-1.4.0 \subsection{Preface to the Fifth Edition} \textsc{ABCL} 1.4 consolidates eighteen months of production bugfixes,  39 and substantially improves the support for invoking external  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 07, 2017 40 processes via \code{SYS:RUN-PROGRAM}.  41   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 15, 2014 42 %%Preface to the Fourth edition, abcl-1.3.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jan 27, 2014 43 \subsection{Preface to the Fourth Edition}  44   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jan 27, 2014 45 \textsc{ABCL} 1.3 now implements an optimized implementation of the  46 \code{org.armedbear.lisp.LispStack} abstraction thanks to Dmitry  47 Nadezhin which runs on ORCL JVMs from 1.[5-8] conformantly.  48 49 50 51 52 53  %%Preface to the Third edition, abcl-1.2. \subsection{Preface to the Third Edition} The implementation now contains a performant and conformant implementation of (A)MOP to the point of inclusion in CLOSER-MOP's test suite.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 22, 2011 54   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 55 %%Preface to the second edition, abcl-1.1.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 15, 2012 56   57 58 \subsection{Preface to the Second Edition}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 59 \textsc{ABCL} 1.1 now contains \textsc{(A)MOP}. We hope you enjoy! --The Mgmt.  60   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 61 \chapter{Introduction}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 62   63 64 65 66 67 68 69 Armed Bear Common Lisp (\textsc{ABCL}) is an implementation of \textsc{Common Lisp} that runs on the Java Virtual Machine (\textsc{JVM}). \textsc{ABCL} compiles \textsc{Common Lisp} to \textsc{Java} bytecode\footnote{The class file version is 49.0''.}, with an efficiency that varies on the hosting JVM implementation. \textsc{ABCL} supports running on the Java 6, Java 7, and Java 8 \textsc{JVM} implementations.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 08, 2017 70 71 72  Armed Bear provides the following integration methods for interfacing with Java code and libraries:  73 74 75 76 77 78 79 80 81 82 83 \begin{itemize} \item Lisp code can create Java objects and call their methods (see Section~\ref{sec:lisp-java}, page~\pageref{sec:lisp-java}). \item Java code can call Lisp functions and generic functions, either directly (Section~\ref{sec:calling-lisp-from-java}, page~\pageref{sec:calling-lisp-from-java}) or via \texttt{JSR-223} (Section~\ref{sec:java-scripting-api}, page~\pageref{sec:java-scripting-api}). \item \code{jinterface-implementation} creates Lisp-side implementations of Java interfaces that can be used as listeners for Swing classes and similar.  84 85 \item \code{java:jnew-runtime-class} can inject fully synthetic Java classes--and their objects-- into the current JVM process whose  86 87 88 89  behavior is specified via closures expressed in \textsc{Common Lisp}. \footnote{Parts of the current implementation are not fully finished, so the status of some interfaces here should be treated with skepticism if you run into problems.}  90   91 \end{itemize}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 92 93 \textsc{ABCL} is supported by the Lisp library manager \textsc{QuickLisp}\footnote{\url{http://quicklisp.org/}} and can run many of the  94 95 96 97 programs and libraries provided therein out-of-the-box. \section{Conformance} \label{section:conformance}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 98   99 \subsection{ANSI Common Lisp}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 100 \textsc{ABCL} is currently a (non)-conforming \textsc{ANSI} Common Lisp  101 implementation due to the following known issues:  102   103 \begin{itemize}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 104 \item The generic function signatures of the \code{CL:DOCUMENTATION} symbol  105  do not match the specification.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 106 \item The \code{CL:TIME} form does not return a proper \code{CL:VALUES}  107  environment to its caller.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 108 \item When merging pathnames and the defaults point to a \code{EXT:JAR-PATHNAME},  109 110 111 112 113  we set the \code{DEVICE} of the result to \code{:UNSPECIFIC} if the pathname to be be merged does not contain a specified \code{DEVICE}, does not contain a specified \code{HOST}, does contain a relative \code{DIRECTORY}, and we are not running on a \textsc{MSFT} Windows platform.\footnote{The intent of this rather arcane sounding deviation from conformance is so that the  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 114  result of a merge won't fill in a \code{DEVICE} with the wrong "default  115  device for the host" in the sense of the fourth paragraph in the  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 116  \textsc{CLHS} description of MERGE-PATHNAMES (see in \cite{CLHS} the paragraph beginning  117 118 119 120 121  "If the PATHNAME explicitly specifies a host and not a device…"). A future version of the implementation may return to conformance by using the \code{HOST} value to reflect the type explicitly. }  122 \end{itemize}  123   124 125 126 127 128 Somewhat confusingly, this statement of non-conformance in the accompanying user documentation fulfills the requirements that \textsc{ABCL} is a conforming ANSI Common Lisp implementation according to the Common Lisp HyperSpec~\cite{CLHS}. Clarifications to this point are solicited.  129   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 130 \textsc{ABCL} aims to be be a fully conforming \textsc{ANSI} Common Lisp implementation.  131 Any other behavior should be reported as a bug.  132   133 \subsection{Contemporary Common Lisp}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 134 In addition to \textsc{ANSI} conformance, \textsc{ABCL} strives to implement  135 features expected of a contemporary \textsc{Common Lisp}, i.e. a Lisp of the  136 post-2005 Renaissance.  137   138 139 The following known problems detract from \textsc{ABCL} being a proper contemporary Common Lisp.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jan 10, 2012 140 \begin{itemize}  141 142 143 144 145 \item An incomplete implementation of interactive debugging mechanisms, namely a no-op version of \code{STEP}\footnote{Somewhat surprisingly allowed by \textsc{ANSI}}, the inability to inspect local variables in a given call frame, and the inability to resume a halted computation at an arbitrarily selected call frame.  146 147 148 \item Incomplete streams abstraction, in that \textsc{ABCL} needs a suitable abstraction between \textsc{ANSI} and \textsc{Gray streams} with a runtime switch for the beyond conforming  149  behavior\footnote{The streams could be optimized to the  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 150  \textsc{JVM} NIO \cite{nio} abstractions at great profit for  151  binary byte-level manipulations.}.  152 153 154 155 \item Incomplete documentation: source code is missing docstrings from all exported symbols from the \code{EXTENSIONS}, \code{SYSTEM}, \code{JAVA}, \code{MOP}, and \code{THREADS} packages. This user manual is currently in draft status.  156 157 158 159 160 \end{itemize} \section{License}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jan 10, 2012 161   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 162 \textsc{ABCL} is licensed under the terms of the \textsc{GPL} v2 of  163 164 165 166 167 168 169 170 June 1991 with an added classpath-exception'' clause (see the file \texttt{COPYING} in the source distribution\footnote{See \url{http://abcl.org/svn/trunk/tags/1.5.0/COPYING}} for the license, term 13 in the same file for the classpath exception). This license broadly means that you must distribute the sources to \textsc{ABCL}, including any changes you make, together with a program that includes \textsc{ABCL}, but that you are not required to distribute the sources of the whole program. Submitting your changes upstream to the \textsc{ABCL}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 171 172 development team is actively encouraged and very much appreciated, of course.  173   174 \section{Contributors}  175   176 \begin{itemize}  177 \item Philipp Marek \texttt{Thanks for the markup, and review of the Manual}  178 179 180 \item Douglas Miles \texttt{Thanks for the whacky IKVM stuff and keeping the flame alive in the dark years.} \item Alan Ruttenberg \texttt{Thanks for JSS.}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 08, 2017 181 182 \item Olof-Joachim Frahm \item piso  183 \item and of course \emph{Peter Graves}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jan 10, 2012 184 \end{itemize}  185   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 186   187 \chapter{Running ABCL}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 188   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 189   190 \textsc{ABCL} is packaged as a single jar file usually named either  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 07, 2017 191 \texttt{abcl.jar} or possibly something like \texttt{abcl-1.5.0.jar} if  192 193 using a versioned package on the local filesystem from your system vendor. This jar file can be executed from the command line to obtain a  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 194 195 196 \textsc{REPL}\footnote{Read-Eval Print Loop, a Lisp command-line}, viz: \index{REPL}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 197 198  \begin{listing-shell}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 01, 2011 199  cmd$java -jar abcl.jar  200 \end{listing-shell} %$ unconfuse Emacs syntax highlighting  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 201   202 203 \emph{N.b.} for the proceeding command to work, the \texttt{java} executable needs to be in your path.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 204   205 206 207 208 209 To facilitate the use of ABCL in tool chains such as SLIME~\cite{slime} (the Superior Lisp Interaction Mode for Emacs), we provide both a Bourne shell script and a \textsc{DOS} batch file. If you or your administrator adjusted the path properly, ABCL may be executed simply as:  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 210 211  \begin{listing-shell}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 01, 2011 212  cmd$abcl  213 214 215 \end{listing-shell}%$ Probably the easiest way of setting up an editing environment using the  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 216 \textsc{Emacs} editor is to use \textsc{Quicklisp} and follow the instructions at  217 \url{http://www.quicklisp.org/beta/#slime}.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 218 219 220  \section{Options}  221 ABCL supports the following command line options:  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 222   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 223 224 \index{Command Line Options}  225 \begin{description}  226 227 228 229 230 231 232 233 234 \item[\texttt{ --help}] displays a help message. \item[\texttt{ --noinform}] Suppresses the printing of startup information and banner. \item[\texttt{ --noinit}] suppresses the loading of the \verb+~/.abclrc+ startup file. \item[\texttt{ --nosystem}] suppresses loading the \texttt{system.lisp} customization file. \item[\texttt{ --eval FORM}] evaluates FORM before initializing the REPL. \item[\texttt{ --load FILE}] loads the file FILE before initializing the REPL. \item[\texttt{ --load-system-file FILE}] loads the system file FILE before initializing the REPL. \item[\texttt{ --batch}] evaluates forms specified by arguments and in the initialization file \verb+~/.abclrc+, and then exits without  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Mar 02, 2013 235  starting a \textsc{REPL}.  236 237 238 239 240 \end{description} All of the command line arguments following the occurrence of \verb+--+ are passed unprocessed into a list of strings accessible via the variable \code{EXT:*COMMAND-LINE-ARGUMENT-LIST*} from within ABCL.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 241 242 243  \section{Initialization}  244 245 246 If the \textsc{ABCL} process is started without the \code{--noinit} flag, it attempts to load a file named \code{.abclrc} in the user's home directory and then interpret its contents.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 11, 2011 247 248  The user's home directory is determined by the value of the JVM system  249 250 251 252 property \texttt{user.home}. This value may or may not correspond to the value of the \texttt{HOME} system environment variable, at the discretion of the JVM implementation that \textsc{ABCL} finds itself hosted upon.  253   254 \chapter{Interaction with the Hosting JVM}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 255   256 257 % Plan of Attack %  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 258 259 260 261 262 % describe calling Java from Lisp, and calling Lisp from Java, % probably in two separate sections. Presumably, we can partition our % audience into those who are more comfortable with Java, and those % that are more comforable with Lisp  263 264 265 266 The Armed Bear Common Lisp implementation is hosted on a Java Virtual Machine. This chapter describes the mechanisms by which the implementation interacts with that hosting mechanism.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 267 \section{Lisp to Java}  268 \label{sec:lisp-java}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 269   270 271 272 273 274 \textsc{ABCL} offers a number of mechanisms to interact with Java from its Lisp environment. It allows calling both instance and static methods of Java objects, manipulation of instance and static fields on Java objects, and construction of new Java objects.  275 276 When calling Java routines, some values will automatically be converted by the FFI\footnote{Foreign Function Interface, is the term  277  of art for the part of a \textsc{Lisp} implementation which implements  278  calling code written in other languages, typically normalized to the  279  local C compiler calling conventions.} from \textsc{Lisp} values to Java  280 values. These conversions typically apply to strings, integers and  281 floats. Other values need to be converted to their \textsc{Java} equivalents by  282 the programmer before calling the Java object method. Java values  283 returned to \textsc{Lisp} are also generally converted back to their Lisp  284 285 286 287 counterparts. Some operators make an exception to this rule and do not perform any conversion; those are the raw'' counterparts of certain FFI functions and are recognizable by their name ending with \code{-RAW}.  288   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 289 \subsection{Low-level Java API}  290   291 This subsection covers the low-level API available after evaluating  292 \code{(require :java)}. A higher level \textsc{Java} API, developed by Alan  293 294 295 Ruttenberg, is available in the \code{contrib/} directory and described later in this document, see Section~\ref{section:jss} on page \pageref{section:jss}.  296   297 \subsubsection{Calling Java Object Methods}  298   299 There are two ways to call a Java object method in the low-level (basic) API:  300 301  \begin{itemize}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 302 \item Call a specific method reference (which was previously acquired)  303 304 305 \item Dynamic dispatch using the method name and the call-specific arguments provided by finding the best match (see Section~\ref{sec:param-matching-for-ffi}).  306 307 \end{itemize}  308 309 310 311 312 \code{JAVA:JMETHOD} is used to acquire a specific method reference. The function takes two or more arguments. The first is a Java class designator (a \code{JAVA:JAVA-CLASS} object returned by \code{JAVA:JCLASS} or a string naming a Java class). The second is a string naming the method.  313   314 315 316 Any arguments beyond the first two should be strings naming Java classes, with one exception as listed in the next paragraph. These classes specify the types of the arguments for the method.  317   318 319 320 When \code{JAVA:JMETHOD} is called with three parameters and the last parameter is an integer, the first method by that name and matching number of parameters is returned.  321   322 Once a method reference has been acquired, it can be invoked using  323 324 325 326 \code{JAVA:JCALL}, which takes the method as the first argument. The second argument is the object instance to call the method on, or \code{NIL} in case of a static method. Any remaining parameters are used as the remaining arguments for the call.  327 328 329 330 331 332 333 334 335 336  \subsubsection{Calling Java object methods: dynamic dispatch} The second way of calling Java object methods is by using dynamic dispatch. In this case \code{JAVA:JCALL} is used directly without acquiring a method reference first. In this case, the first argument provided to \code{JAVA:JCALL} is a string naming the method to be called. The second argument is the instance on which the method should be called and any further arguments are used to select the best matching method and dispatch the call.  337 \subsubsection{Dynamic dispatch: Caveats}  338   339 Dynamic dispatch is performed by using the Java reflection  340 API\footnote{The Java reflection API is found in the  341 342 343 344  \code{java.lang.reflect} package}. Generally the dispatch works fine, but there are corner cases where the API does not correctly reflect all the details involved in calling a Java method. An example is the following Java code:  345 346 347 348 349 350 351 352  \begin{listing-java} ZipFile jar = new ZipFile("/path/to/some.jar"); Object els = jar.entries(); Method method = els.getClass().getMethod("hasMoreElements"); method.invoke(els); \end{listing-java}  353 354 Even though the method \code{hasMoreElements()} is public in \code{Enumeration}, the above code fails with  355 356 357  \begin{listing-java} java.lang.IllegalAccessException: Class ... can  358 not access a member of class java.util.zip.ZipFile\$2 with modifiers  359 360 361 362 363 364 "public" at sun.reflect.Reflection.ensureMemberAccess(Reflection.java:65) at java.lang.reflect.Method.invoke(Method.java:583) at ... \end{listing-java}  365 366 This is because the method has been overridden by a non-public class and the reflection API, unlike \texttt{javac}, is not able to handle such a case.  367 368 369 370 371 372 373 374 375 376 377 378  While code like that is uncommon in Java, it is typical of ABCL's FFI calls. The code above corresponds to the following Lisp code: \begin{listing-lisp} (let ((jar (jnew "java.util.zip.ZipFile" "/path/to/some.jar"))) (let ((els (jcall "entries" jar))) (jcall "hasMoreElements" els))) \end{listing-lisp} except that the dynamic dispatch part is not shown.  379 To avoid such pitfalls, all Java objects in \textsc{ABCL} carry an extra  380 381 382 383 384 385 386 387 388 field representing the intended class'' of the object. That class is used first by \code{JAVA:JCALL} and similar to resolve methods; the actual class of the object is only tried if the method is not found in the intended class. Of course, the intended class is always a super-class of the actual class -- in the worst case, they coincide. The intended class is deduced by the return type of the method that originally returned the Java object; in the case above, the intended class of \code{ELS} is \code{java.util.Enumeration} because that is the return type of the \code{entries} method.  389 390 391 392 393 394 395  While this strategy is generally effective, there are cases where the intended class becomes too broad to be useful. The typical example is the extraction of an element from a collection, since methods in the collection API erase all types to \code{Object}. The user can always force a more specific intended class by using the \code{JAVA:JCOERCE} operator.  396 397 398 399 400 401 402 403 404 405 406 407 408 409 410  % \begin{itemize} % \item Java values are accessible as objects of type JAVA:JAVA-OBJECT. % \item The Java FFI presents a Lisp package (JAVA) with many useful % symbols for manipulating the artifacts of expectation on the JVM, % including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the % introspection of values \ref{JAVA:JFIELD}, the execution of methods % (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC}) % \item The JSS package (\ref{JSS}) in contrib introduces a convenient macro % syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java % methods, and additional convenience functions. % \item Java classes and libraries may be dynamically added to the % classpath at runtime (JAVA:ADD-TO-CLASSPATH). % \end{itemize}  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 10, 2011 411 412 \subsubsection{Calling Java class static methods}  413 414 415 Like non-static methods, references to static methods can be acquired by using the \code{JAVA:JMETHOD} primitive. Static methods are called with \code{JAVA:JSTATIC} instead of \code{JAVA:JCALL}.  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 10, 2011 416 417 418  Like \code{JAVA:JCALL}, \code{JAVA:JSTATIC} supports dynamic dispatch by passing the name of the method as a string instead of passing a method reference.  419 The parameters should be values to pass in the function call instead of  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 10, 2011 420 421 a specification of classes for each parameter.  422 \subsubsection{Parameter matching for FFI dynamic dispatch}  423 \label{sec:param-matching-for-ffi}  424   425 426 The algorithm used to resolve the best matching method given the name and the arguments' types is the same as described in the Java Language  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 10, 2011 427 Specification. Any deviation should be reported as a bug.  428   429 % ###TODO reference to correct JLS section  430   ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 10, 2011 431 432 \subsubsection{Instantiating Java objects}  433 \textsc{Java} objects can be instantiated (created) from \textsc{Lisp} by calling  434 435 a constructor from the class of the object to be created. The \code{JAVA:JCONSTRUCTOR} primitive is used to acquire a constructor  436 reference. Its arguments specify the types of arguments of the constructor  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 10, 2011 437 438 method the same way as with \code{JAVA:JMETHOD}.  439 440 441 The obtained constructor is passed as an argument to \code{JAVA:JNEW}, together with any arguments. \code{JAVA:JNEW} can also be invoked with a string naming the class as its first argument.  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 10, 2011 442   443 \subsubsection{Accessing Java object and class fields}  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 21, 2011 444   445 446 447 448 Fields in Java objects can be accessed using the getter and setter functions \code{JAVA:JFIELD} and \code{(SETF JAVA:JFIELD)}. Static (class) fields are accessed the same way, but with a class object or string naming a class as first argument.  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 21, 2011 449 450  Like \code{JAVA:JCALL} and friends, values returned from these accessors carry  451 an intended class around, and values which can be converted to Lisp values will  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 21, 2011 452 453 be converted.  454 \section{Java to Lisp}  ehuelsmann@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 21, 2011 455   456 457 This section describes the various ways that one interacts with \textsc{Lisp} from \textsc{Java} code. In order to access the \textsc{Lisp} world from \textsc{Java}, one needs  458 to be aware of a few things, the most important ones being listed below:  459 460  \begin{itemize}  461 462 463 464 \item All Lisp values are descendants of \code{LispObject}. \item Lisp symbols are accessible either via static members of the \code{Symbol} class, or by dynamically introspecting a \code{Package} object.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 465 \item The Lisp dynamic environment may be saved via  466 467  \code{LispThread.bindSpecial(Binding)} and restored via \code{LispThread.resetSpecialBindings(Mark)}.  468 469 \item Functions can be executed by invoking \code{LispObject.execute(args [...])}  470 471 \end{itemize}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 472 \subsection{Calling Lisp from Java}  473 \label{sec:calling-lisp-from-java}  474   475 476 477 478 479 Note: the entire \textsc{ABCL} \textsc{Lisp} system implementation in \textsc{Java} is resident in the \texttt{org.armedbear.lisp} package, but the following code snippets do not show the relevant import statements in the interest of brevity. An example of the import statement would be  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 480 \begin{listing-java}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 481  import org.armedbear.lisp.*;  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 482 \end{listing-java}  483 to potentially import all the JVM symbol from the \code{org.armedbear.lisp}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 484 namespace.  485   486 There can only ever be a single Lisp interpreter per \textsc{JVM} instance. A  487 488 reference to this interpreter is obtained by calling the static method \code{Interpreter.createInstance()}.  489   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 490 \begin{listing-java}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 491  Interpreter interpreter = Interpreter.createInstance();  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 492 \end{listing-java}  493 494  If this method has already been invoked in the lifetime of the current  495 496 Java process it will return \texttt{null}, so if you are writing \textsc{Java} whose life-cycle is a bit out of your control (like in a \textsc{Java} servlet),  497 a safer invocation pattern might be:  498   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 01, 2011 499 \begin{listing-java}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 500 501 502 503  Interpreter interpreter = Interpreter.getInstance(); if (interpreter == null) { interpreter = Interpreter.createInstance(); }  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 01, 2011 504 505 \end{listing-java}  506   507 The Lisp \code{eval} primitive may simply be passed strings for evaluation:  508   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 509 \begin{listing-java}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 510 511  String line = "(load \"file.lisp\")"; LispObject result = interpreter.eval(line);  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 512 \end{listing-java}  513 514 515  Notice that all possible return values from an arbitrary Lisp computation are collapsed into a single return value. Doing useful  516 517 further computation on the \code{LispObject} depends on knowing what the result of the computation might be. This usually involves some amount  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 518 of \code{instanceof} introspection, and forms a whole topic to itself  519 520 (see Section~\ref{topic:Introspecting a LispObject}, page~\pageref{topic:Introspecting a LispObject}).  521   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 522 Using \code{eval} involves the Lisp interpreter. Lisp functions may  523 524 525 526 also be directly invoked by Java method calls as follows. One simply locates the package containing the symbol, obtains a reference to the symbol, and then invokes the \code{execute()} method with the desired parameters.  527   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 528 \begin{listing-java}  529 530 531 532 533 534 535 536 537  interpreter.eval("(defun foo (msg)" + "(format nil \"You told me '~A'~%\" msg))"); Package pkg = Packages.findPackage("CL-USER"); Symbol foo = pkg.findAccessibleSymbol("FOO"); Function fooFunction = (Function)foo.getSymbolFunction(); JavaObject parameter = new JavaObject("Lisp is fun!"); LispObject result = fooFunction.execute(parameter); // How to get the "naked string value"? System.out.println("The result was " + result.writeToString());  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 538 \end{listing-java}  539   540 541 542 543 544 If one is calling a function in the CL package, the syntax can become considerably simpler. If we can locate the instance of definition in the ABCL Java source, we can invoke the symbol directly. For instance, to tell if a \code{LispObject} is (Lisp) \texttt{NIL}, we can invoke the CL function \code{NULL} in the following way:  545   546   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 547 \begin{listing-java}  548 549  boolean nullp(LispObject object) { LispObject result = Primitives.NULL.execute(object);  550  if (result == NIL) {  551 552 553 554  return false; } return true; }  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 555 \end{listing-java}  556   557 558 559 560 561 Note, that the symbol \code{nil} is explicitly named in the \textsc{Java} namespace as \code{Symbol.NIL} but is always present in the local namespace in its unadorned form for the convenience of the User.  562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 \subsubsection{Multiple Values} After a call to a function that returns Lisp multiple values, the values are associated with the executing \code{LispThread} until the next call into Lisp. One may access the values object as a list of \code{LispObject} instances via a call to \code{getValues()} on that thread reference as evidenced by the following code: \begin{listing-java} org.armedbear.lisp.Package cl = Packages.findPackage("CL"); Symbol valuesSymbol = cl.findAccessibleSymbol("VALUES"); LispObject[] valuesArgs = { LispInteger.getInstance(1), LispInteger.getInstance(2) }; // equivalent to (values 1 2)'' LispObject result = valuesSymbol.execute(valuesArgs); LispObject[] values = LispThread.currentThread().getValues(); for (LispObject value: values) { System.out.println("value ==> " + value.printObject()); } \end{listing-java}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 586 \subsubsection{Introspecting a LispObject}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 17, 2011 587 \label{topic:Introspecting a LispObject}  588   589 590 We present various patterns for introspecting an arbitrary \code{LispObject} which can hold the result of every Lisp evaluation  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Sep 07, 2011 591 into semantics that Java can meaningfully deal with.  592   593 \paragraph{LispObject as \code{boolean}}  594   595 596 If the \code{LispObject} is to be interpreted as a generalized boolean value, one can use \code{getBooleanValue()} to convert to Java:  597   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 598 \begin{listing-java}  599 600  LispObject object = Symbol.NIL; boolean javaValue = object.getBooleanValue();  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 601 \end{listing-java}  602   603 604 605 Since in Lisp any value other than \code{NIL} means "true", Java equality can also be used, which is a bit easier to type and better in terms of information it conveys to the compiler:  606   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 607 \begin{listing-java}  608  boolean javaValue = (object != Symbol.NIL);  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 609 \end{listing-java}  610   611 \paragraph{LispObject as a list}  612   613 614 615 If \code{LispObject} is a list, it will have the type \code{Cons}. One can then use the \code{copyToArray} method to make things a bit more suitable for Java iteration.  616   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 617 \begin{listing-java}  618 619 620 621 622  LispObject result = interpreter.eval("'(1 2 4 5)"); if (result instanceof Cons) { LispObject array[] = ((Cons)result.copyToArray()); ... }  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 623 \end{listing-java}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 624   625 A more Lispy way to iterate down a list is to use the cdr() access  626 627 function just as like one would traverse a list in Lisp:;  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 628 \begin{listing-java}  629 630 631 632 633  LispObject result = interpreter.eval("'(1 2 4 5)"); while (result != Symbol.NIL) { doSomething(result.car()); result = result.cdr(); }  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 634 \end{listing-java}  635   636 637 \section{Java Scripting API (JSR-223)} \label{sec:java-scripting-api}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 638   639 640 641 642 643 644 645 ABCL can be built with support for JSR-223~\cite{jsr-223}, which offers a language-agnostic API to invoke other languages from Java. The binary distribution download-able from ABCL's homepage is built with JSR-223 support. If you're building ABCL from source on a pre-1.6 JVM, you need to have a JSR-223 implementation in your classpath (such as Apache Commons BSF 3.x or greater) in order to build ABCL with JSR-223 support; otherwise, this feature will not be built.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 646   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 647 648 649 This 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  650 \url{http://abcl.org/trac/browser/trunk/abcl/examples/jsr-223}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 651 for example usage.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 652   653 \subsection{Conversions}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 654   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 655 656 657 658 659 In 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.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 660   661 \subsection{Implemented JSR-223 interfaces}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 662   663 664 665 666 667 668 669 670 671 JSR-223 defines three main interfaces, of which two (\code{Invocable} and \code{Compilable}) are optional. ABCL implements all the three interfaces - \code{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.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 672 673 674  \subsubsection{The ScriptEngine}  675 676 677 The main interface defined by JSR-223, \code{javax.script.ScriptEngine}, is implemented by the class \code{org.armedbear.lisp.scripting.AbclScriptEngine}. \code{AbclScriptEngine}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 678 is a singleton, reflecting the fact that ABCL is a singleton as  679 680 681 682 well. You can obtain an instance of \code{AbclScriptEngine} using the \code{AbclScriptEngineFactory} or by using the service provider mechanism through \code{ScriptEngineManager} (refer to the \texttt{javax.script} documentation).  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 683   684 \subsection{Start-up and configuration file}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 685   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jan 25, 2012 686 At start-up (i.e. when its constructor is invoked, as part of the  687 static initialization phase of \code{AbclScriptEngineFactory}) the ABCL  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 688 script engine attempts to load an "init file" from the classpath  689 (\texttt{/abcl-script-config.lisp}). If present, this file can be used to  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jan 25, 2012 690 customize the behavior of the engine, by setting a number of  691 variables in the \code{ABCL-SCRIPT} package. Here is a list of the available  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 692 variables:  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 693   694 695 \begin{description} \item[\texttt{*use-throwing-debugger*}] controls whether ABCL uses a  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 696 697 698  non-standard debugging hook function to throw a Java exception instead of dropping into the debugger in case of unhandled error conditions.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 699  \begin{itemize}  700  \item Default value: \texttt{T}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 701 702 703 704 705 706  \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. \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.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 707  \end{itemize}  708 709 \item[\texttt{*launch-swank-at-startup*}] If true, Swank will be launched at startup. See \texttt{*swank-dir*} and \texttt{*swank-port*}.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 710  \begin{itemize}  711  \item Default value: \texttt{NIL}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 712  \end{itemize}  713 714 715 716 717 \item[\texttt{*swank-dir*}] The directory where Swank is installed. Must be set if \texttt{*launch-swank-at-startup*} is true. \item[\texttt{*swank-port*}] The port where Swank will listen for connections. Must be set if \texttt{*launch-swank-at-startup*} is true.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 718 719 720  \begin{itemize} \item Default value: 4005 \end{itemize}  721 \end{description}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 722   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 723 724 Additionally, at startup the AbclScriptEngine will \code{(require 'asdf)} - in fact, it uses asdf to load Swank.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 725   726 \subsection{Evaluation}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 727   728 729 730 731 732 733 734 735 Code is read and evaluated in the package \code{ABCL-SCRIPT-USER}. This packages \texttt{USE}s the \code{COMMON-LISP}, \code{JAVA} and \code{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 behavior of \code{LOAD} is guaranteed. This allows, among other things, \code{IN-PACKAGE} forms to change the package in which the loaded code is read.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 736 737  It is possible to evaluate code in what JSR-223 calls a  738 ScriptContext'' (basically a flat environment of name$\rightarrow$value  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 739 740 pairs). This context is used to establish special bindings for all the variables defined in it; since variable names are strings from Java's  741 742 point of view, they are first interned using \code{READ-FROM-STRING} with, as usual, \code{ABCL-SCRIPT-USER} as the default package. Variables are declared  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 743 744 745 746 747 748 749 special because CL's \code{LOAD}, \code{EVAL} and \code{COMPILE} functions work in a null lexical environment and would ignore non-special bindings. Contrary 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.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 750   751 \subsection{Compilation}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 752   753 \code{AbclScriptEngine} implements the \code{javax.script.Compilable}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 754 755 interface. Currently it only supports compilation using temporary files. Compiled code, returned as an instance of  756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 \texttt{javax.script.CompiledScript}, is read, compiled and executed by default in the \code{abcl-script-user} package, just like evaluated code. In contrast to evaluated code, though, due to the way the \textsc{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 \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 \code{(identity some-literal-object)}. Note that this issue should not matter in real code, where it is unlikely that a top-level self-evaluating form will appear as the last form in a file (in fact, the Common Lisp load function always returns \code{t} upon success; with \textsc{JSR-223} this policy has been changed to make evaluation of small code snippets work as intended).  773 774  \subsection{Invocation of functions and methods}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 775   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 776 777 778 779 780 781 782 AbclScriptEngine 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  783 \texttt{UnsupportedOperationException} when called. The \code{invokeFunction()}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 784 method should be used to call both regular and generic functions.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 785   786 \subsection{Implementation of Java interfaces in Lisp}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 787   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 788 789 790 791 792 ABCL 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:  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 793 794 795  \code{jmake-proxy interface implementation \&optional lisp-this ==> proxy}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 796 797 798 799 800 801 802 \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}.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 803   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 804 805 The returned proxy is an instance of the interface, with methods implemented with Lisp functions.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 806 807 808 809  Built-in interface-implementation types include: \begin{itemize}  810 811 \item a single Lisp function which, upon invocation of any method in the interface, will be passed the method name, the Lisp-this object,  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 812 813  and all the parameters. Useful for interfaces with a single method, or to implement custom interface-implementation strategies.  814 \item a hash-map of method-name$\rightarrow\$ Lisp function mappings. Function  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 20, 2011 815 816 817 818 819 820  signature is \code{(lisp-this \&rest args)}. \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.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 821 822 \end{itemize}  823 824 825 826 827 828 This functionality is exposed by the class \code{AbclScriptEngine} via the two methods \code{getInterface(Class)} and \code{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 \code{jmake-proxy} generic function.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 829   830 831 \subsection{Implementation of Java classes in Lisp}  832 See \code{JAVA:JNEW-RUNTIME-CLASS} in \ref{JAVA:JNEW-RUNTIME-CLASS}.  833 834   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 02, 2011 835 \chapter{Implementation Dependent Extensions}  836   837 838 839 840 As outlined by the \textsc{CLHS} \textsc{ANSI} conformance guidelines, we document the extensions to the Armed Bear Common Lisp implementation made accessible to the user by virtue of being an exported symbol in the \code{java}, \code{threads}, or \code{extensions} packages.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 02, 2011 841 842 843 844 845  \section{JAVA} \subsection{Modifying the JVM CLASSPATH}  846 The \code{JAVA:ADD-TO-CLASSPATH} generic functions allows one to add the  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 847 specified pathname or list of pathnames to the current classpath  848 used by \textsc{ABCL}, allowing the dynamic loading of \textsc{JVM} objects:  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 02, 2011 849 850 851  \begin{listing-lisp} CL-USER> (add-to-classpath "/path/to/some.jar")  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 03, 2011 852 \end{listing-lisp}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 02, 2011 853   854 N.b \code{ADD-TO-CLASSPATH} only affects the classloader used by \textsc{ABCL}  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 855 (the value of the special variable \code{JAVA:*CLASSLOADER*}. It has  856 no effect on \textsc{Java} code outside \textsc{ABCL}.  astalla@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 12, 2011 857   858 859 860 861 \subsection{Creating a synthetic Java Class at Runtime} See \code{JAVA:JNEW-RUNTIME-CLASS} on \ref{JAVA:JNEW-RUNTIME-CLASS}.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 862 % include autogen docs for the JAVA package.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 863 \include{java}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 864   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 02, 2011 865 866 \section{THREADS}  867 868 869 The extensions for handling multithreaded execution are collected in the \code{THREADS} package. Most of the abstractions in Doug Lea's excellent \code{java.util.concurrent} packages may be manipulated  870 directly via the JSS contrib to great effect \cite{lea-1998}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 02, 2011 871   mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Oct 03, 2011 872 % include autogen docs for the THREADS package.  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Aug 05, 2011 873 \include{threads}  mevenson@1c010e3e-69d0-11dd-93a8-456734b0d56f committed Jun 15, 2011 874