Changeset 13623


Ignore:
Timestamp:
10/09/11 20:05:57 (10 years ago)
Author:
ehuelsmann
Message:

Add some documentation to the Java->Lisp and Lisp->Java sections.

File:
1 edited

Legend:

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

    r13622 r13623  
    124124\section{Lisp to Java}
    125125
    126 ABCL offers a number of mechanisms to manipulate Java libraries from
    127 Lisp.
     126ABCL offers a number of mechanisms to interact with Java from
     127its lisp environment. It allows calling methods (and static methods) of
     128Java objects, manipulation of fields and static fields and construction
     129of new Java objects.
     130
     131When calling Java routines, some values will automatically be converted
     132by the FFI from Lisp values to Java values. These conversions typically
     133apply to strings, integers and floats. Other values need to be converted
     134to their Java equivalents by the programmer before calling the Java
     135object method.
     136
     137\subsection{Lowlevel Java API}
     138
     139There's a higher level Java API defined in the
     140\ref{topic:Higher level Java API: JSS}(JSS package) which is available
     141in the contrib/ directory. This package is described later in this
     142document.  This section covers the lower level API directly available
     143after evaluating \code{(require 'JAVA)}.
     144
     145\subsubsection{Calling Java object methods}
     146
     147There are two ways to call a Java object method in the basic API:
    128148
    129149\begin{itemize}
    130 \item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
    131 \item The Java FFI presents a Lisp package (JAVA) with many useful
    132   symbols for manipulating the artifacts of expectation on the JVM,
    133   including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
    134   introspection of values \ref{JAVA:JFIELD}, the execution of methods
    135   (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
    136 \item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
    137   syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
    138   methods, and additional convenience functions.
    139 \item Java classes and libraries may be dynamically added to the
    140   classpath at runtime (JAVA:ADD-TO-CLASSPATH).
     150\item Call a specific method reference (pre-acquired)
     151\item Dynamic dispatch using the method name and
     152  the call-specific arguments provided by finding the
     153  \ref{section:Parameter matching for FFI dynamic dispatch}{best match}.
    141154\end{itemize}
    142155
     156The dynamic dispatch variant is discussed in the next section.
     157
     158\code{JAVA:JMETHOD} is used to acquire a specific method reference.
     159The function takes at two or more arguments. The first is Java class designator
     160(a \code{JAVA:JAVA-CLASS} object returned by \code{JAVA:JCLASS} or a string naming
     161a Java class). The second is a string naming the method.
     162
     163Any arguments beyond the first two should be strings naming Java classes with
     164one exception as listed in the next paragraph. These
     165classes specify the types of the arguments for the method to be returned.
     166
     167There's additional calling convention to the \code{JAVA:JMETHOD} function:
     168When the method is called with three parameters and the last parameter is an
     169integer, the first method by that name and matching number of parameters is
     170returned.
     171
     172Once you have a reference to the method, you can call it using \code{JAVA:JCALL},
     173which takes the method as the first argument. The second argument is the
     174object instance to call the method on. Any remaining parameters are used
     175as the remaining arguments for the call.
     176
     177\subsubsection{Calling Java object methods: dynamic dispatch}
     178
     179The second way of calling Java object methods is by using dynamic dispatch.
     180In this case \code{JAVA:JCALL} is used directly without acquiring a method
     181reference first. In this case, the first argument provided to \code{JAVA:JCALL}
     182is a string naming the method to be called. The second argument is the instance
     183on which the method should be called and any further arguments are used to
     184select the best matching method and dispatch the call.
     185
     186% ###TODO document ``intended class''
     187
     188% \begin{itemize}
     189% \item Java values are accessible as objects of type JAVA:JAVA-OBJECT.
     190% \item The Java FFI presents a Lisp package (JAVA) with many useful
     191%   symbols for manipulating the artifacts of expectation on the JVM,
     192%   including creation of new objects \ref{JAVA:JNEW}, \ref{JAVA:JMETHOD}), the
     193%   introspection of values \ref{JAVA:JFIELD}, the execution of methods
     194%   (\ref{JAVA:JCALL}, \ref{JAVA:JCALL-RAW}, \ref{JAVA:JSTATIC})
     195% \item The JSS package (\ref{JSS}) in contrib introduces a convenient macro
     196%   syntax \ref{JSS:SHARPSIGN_DOUBLEQUOTE_MACRO} for accessing Java
     197%   methods, and additional convenience functions.
     198% \item Java classes and libraries may be dynamically added to the
     199%   classpath at runtime (JAVA:ADD-TO-CLASSPATH).
     200% \end{itemize}
     201
     202\subsubsection{Parameter matching for FFI dynamic dispatch}
     203
     204
     205...
     206
    143207\section{Lisp from Java}
    144208
    145 Manipulation of the Lisp API is currently lacking a stable interface,
    146 so the following documented interfaces are subject to change with
    147 notice:
     209In order to access the Lisp world from Java, one needs to be aware
     210of a few things. The most important ones are listed below.
    148211
    149212\begin{itemize}
    150213\item All Lisp values are descendants of LispObject.java
     214\item In order to
    151215\item Lisp symbols are accessible via either directly referencing the
    152216  Symbol.java instance or by dynamically introspecting the
Note: See TracChangeset for help on using the changeset viewer.