| Allegro CL version 8.2 The object described on this page has been modified in the 8.2 release; see the Release Notes. 8.1 version | ||||||||||
This function was modified in a patch released in April 2011 but that patch has been withdrawn. The changes will be reintroduced in version 9.0.
The new keyword argument, end-function, was added in a patch (for both versions 8.2 and 9.0) on May 1, 2013.
Arguments: &optional mode &key lisp-port lisp-host lisp-file java-port java-host java-file local-dist timeout java-args preload debug verbose error-p library java-home classpath jar report end-function
This function initializes a connection between Lisp and Java. The
argument list supplied is combined with the value of *jlinker-init* in
order to form the actual initialization arguments. Supplied arguments
override any items in the value of *jlinker-init*.
The optional mode argument may be one of the following keywords (keywords in a single bullet are synonyms).
The mode argument specifies the way in which Lisp and Java will
communicate. If the mode is not specified or is nil, the default :start-java mode is used.
You must specify a mode if you wish to supply values for any keyword
argument.
When mode is :start (or the synonym :start-java), the Lisp process starts a new Java VM in a separate operating system process. See here below for more details.
When mode is :lisp-advertises, the Lisp process waits for a separate Java application to make contact. See here below for more details.
When mode is :java-advertises, the Lisp process attempts to connect to a separate Java process. See here below for more details.
In all the above cases, the Lisp and Java parts of the application reside in separate address spaces, and communication takes place through sockets.
When mode is :native (or the synonym :jni), the Java VM is loaded into the address space of the Lisp process. The Lisp and Java parts of the application share one address space and one operating system process. Communication takes place through foreign calls. See here below for more details.
At the application level, there is no difference between the socket (all except :native/:jni) and foreign call (:native/:jni) modes. The mode selection only affects how the interface is initialized.
If jlinker is not initialized and the call to jlinker-init succeeds, the return value is the keyword :jlinker-init.
If jlinker is not initialized and the call to jlinker-init, the result (returning a value or signaling an error) depends on the error-p argument, as describes in the discussion of arguments below.
It is not an error to call jlinker-init when jlinker is already initialized. In that case the function ignores any arguments supplied and simply returns a keyword indicating the type of connection, based on the mode in which it was started:
The meaning of many keyword arguments to jlinker-init is determined by the mode but the following keyword arguments have a common meaning:
| Keyword argument | Default value | Comment |
:error-p
|
The value of *jlinker-error-p*. Note starting
in version 8.0, the initial value of *jlinker-error-p* is t. In earlier releases the initial value was nil.
|
When this argument is non-nil, errors
detected by jlinker-init are signaled as Lisp
errors. When this argument is nil, jlinker-init does not
signal errors; if errors are detected, the value returned is a list of
tokens that describe the error; if the operation succeeds, the value
is the symbol :jlinker-init.
|
:verbose
|
nil
|
When this argument is non-nil, jlinker prints
progress messages. The content of the messages depends on the
mode argument.
|
:debug
|
The default is the value of *jlinker-debug*.
|
If this argument is non-nil, the Java VM
prints progress and status messages to the java.lang.System.out
stream.
|
:java-home
|
The default is taken from the special variable *jlinker-java-home*.
|
This argument specifies the directory where the Java executable may be
found. Jlinker looks in the bin/ sub-directory for a Java
executable. If the value is nil, then we
assume that the Java executable will be found by the operating system
if it is simply mentioned by name (ie, on Unix systems, it may be
found on the default PATH). Otherwise, the value must be a suitable
directory. If the value is :find (MS Windows only), the Windows
registry is examined to find the Java location.
|
:classpath and
:jar
|
nil (for both)
|
These arguments specify how the Java classpath should be modified (in those cases where a modification is relevant). See below for more information. |
:lisp-port
|
If unspecified, the system asks the OS to assign a port number, and this default is normally sufficient. | This argument specifies the socket port used by Lisp to communicate with Java. The default is to ask the OS to assign a port number, and this default is normally sufficient. If a value is specified, it must be a positive number greater than zero, and the given port number must be available. |
:java-port
|
If unspecified, the system asks the OS to assign a port number, and this default is normally sufficient. |
This argument specifies the socket port used by Java to communicate
with Lisp. If the specified value is greater than zero, than Java
listens at that port number and Lisp connects.
If the specified value is less than zero, the absolute value is a port number. Lisp listens at the port and Java connects; this option is useful when the Java application is unable to listen at a socket port. If a value is specified, its absolute value must be greater than zero and identify an available post. |
:local-dist
|
The default value is "Lisp". | This argument specifies an alternate label for the Lisp server in a jlinker connection. If multiple copies of jlinker are running in the same image, this may help in some debugging situations. |
:preload
|
nil
|
This argument specifies a file that is loaded during the initalization
of a socket connection. The file is generated by a call of the form
(jlookup :gen-preload [filename]) (see jlookup).
|
:report
|
nil
|
This argument is in effect in modes
:start-java and
:lisp-advertises. If specified, this argument must
be a function of one argument. The function is called as soon as a
listening socket is created. The argument is the port number of the
listening socket.
|
:end-function
|
nil
|
If non-nil,. should be a functions object or
function name. This function will be called when a jlinker connection
is terminated. The function gets a single argument, the jlinker
connection instance. The argument was implemented but un-documented in
earlier current versions. The earlier implementations allowed the
function to be called more than once but no longer.
|
If either argument is specified, then the Java classpath value is the concatenation of the following three values:
nil or no value specified means use the string ".".
If a jar argument was specified, it is used as the resolved jar file path. Otherwise a default resolved jar file path is determined in 2 steps:
If the value of jar is specified to be nil, then we assume that the jlinker.jar file
is visible to the Java VM for reasons outside our control; for
example, it may have been installed in the Java library directory
along with the built-in Java libraries. In this case, the resolved jar
file path is the empty string.
If neither jar nor classpath
are given values, then the behavior is compatible with older versions
of jlinker - the behavior is determined entirely by the value of the
*jlinker-java-home*
variable. Jlinker adds "." and "jlinker.jar" to the classpath on the
assumption that the jlinker.jar file is in the current
directory.
When mode is :start-java (or
the synonym :start), the Lisp process starts a new
Java VM in a separate operating system process.
The arguments java-home, classpath, jar, java-args, and debug determine how the Java VM is started from the Lisp process.
The lisp-port and java-port arguments may be specified if the default is not sufficient. The arguments library, load, lisp-file, and java-file are ignored. The arguments lisp-host, and java-host should not be specified.
The debug argument: on Microsoft Windows,
the debug argument also determines the Java
executable. If debug is nil, we use the executable "javaw.exe"; if debug is
non-nil, we use the executable "java.exe"
which opens a console window where Java output may be seen.
The java-args argument: the value should
be a list of string arguments passed to Java.These are added after the
ones passed by jLinker. If the first item in this list is a sub-list
starting with the keyword :options, then the
remainder of the sub-list is passed to Java in front of any options
passed by jLinker.
When mode is :lisp-advertises,
the Lisp process waits for a separate Java application to make
contact. The Java application uses static methods in the
LispConnector class to make the connection.
The lisp-file argument: this argument
specifies a file in which Lisp advertises the host and port where Java
must connect. The default is "JavaToLisp.trp". If this argument is
nil, Lisp simply listens at the specified
port and does not advertise in a file. In that case it is necessary to
specify lisp-port as a non-zero value.
The lisp-host argument: this argument is used when the file specified by the lisp-file argument is written. The Java application needs to know the lisp-host value if it is running on a different host. The default value is "localhost".
The timeout argument: if non-nil, this argument specifies the number of seconds
Lisp will wait for a connection from Java.
When mode is :java-advertises,
the Lisp process attempts to connect to a separate Java process. The
Java application uses the LispConnector class to make the connection.
The java-file argument: this argument
specifies a file in which Java advertises the host and port where Lisp
must connect. The default is "LispToJava.trp". If this argument is
nil, Java is assumed to listen at the
specified port and does not advertise in a file.
The java-host argument: this argument must
specifiy the host where Java is advertising when
java-file is nil. The
default value is "localhost".
The java-port argument: this argument must
specifiy the port where Java is advertising when
java-file is nil. When
java-file is nil, this
argument must be specified as positive number greater than zero.
When mode is :native (or the
synonym :jni), the Java VM is loaded into the
address space of the Lisp process. The Lisp and Java parts of the
application share one address space and one operating system process.
Calls between Lisp and Java are equivalent to foreign library calls
and data is transmitted in registers or in memory-to-memory copies.
The arguments java-home, library, classpath, jar, java-args, and debug determine how the Java VM is started from the Lisp process.
The lisp-port, lisp-host, lisp-file, java-port, java-host, java-file, and timeout arguments are ignored.
The library argument: this argument
specifies the pathname of the shared library where the Java VM is
implemented. The default value is taken from the special variable
*jni-library*. On MS Windows,
the initial value is :find to specify that the
Windows Registry should be searched for the location of the Java
Library. Otherwise, the value must be a path string. A relative path
is merged with the value of the java-home
argument.
The java-args argument: this argument may be a list of strings that specify additional arguments passed to the Java VM. Some of these are described in the Java documentation and in the file Xusage.txt in the Java runtime.
For example, the argument "-Xmx256m" specifies 256 megabytes for the Java heap while the argument "-Dfoo=bar" specifes the value "bar" for the Java System.property.
The load argument: this argument forces a re-load of the Java shared library.
If a Lisp image is saved with dumplisp while a jlinker native connections is running, the saved image must re-initialize the Lisp-Java connection when the saved image is re-started. This is done by calling
(jlinker-init :native :load t :library "xxx" ...)
The library argument must be specified in this case.
See jlinker.htm for more information on the jLinker facility.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 The object described on this page has been modified in the 8.2 release; see the Release Notes. 8.1 version | ||||||||||