| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version | ||||||||||
Arguments: &optional mode &key port host file local-dist timeout java-args preload debug verbose error-p library java-home classpath jar report end-function poll-count poll-interval connection-pool preserve-client-calls jave-out
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. |
: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 to communicate
between Lisp and 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.
In earlier releases, two ports were used, one for Lisp and one for
Java, and they were specified with
arguments lisp-port
and java-port. Now only one port is used. For
backward compatibility, when mode is
Starting with Version 7.1, multiple jlinker-init invocations can listen at
the same port number. This is the default behavior
if port is specified
as |
: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.
|
:poll-count
|
3 |
When mode is :java-advertises, this argument
specifies how many times Lisp will attempt to connect.
|
:poll-interval
|
5 |
When mode is :java-advertises, this argument
specifies how many seconds Lisp will wait between connection attempts.
|
:connection-pool
|
*jlinker-default-connection-pool*
|
This argument specifies the connection pool
parameters. When nil, no connection pool is
created and jlinker functions as in earlier versions with one port
from Lisp to Java and one from Java to Lisp. When the value
is :delay, the connection pool will be created
later when jstart-connection-pool is called. Other
non-nil values specify the connection pool
parameters. See the description of *jlinker-default-connection-pool* for
more information.
|
:preserve-client-calls
|
nil
|
This argument specifies what happens to calls from Java in progress
when jlinker-end is
called. A value of nil specifies the behavior
of earlier versions of jlinker. Any running synchronous client calls
are killed. A positive number specifies the number of seconds to allow
after jlinker-end
exits. When the time runs out, the processes are killed. Any other
non-nil value allows the client calls to run
to completion.
|
nil
|
nil
|
This argument can be used to assist in diagnosing some Java problems.
When debug is non-nil,
this argument can be a string that is used to make two file names of
the form javaout.log and javaoute.log. The standard
output and error output from the Java VM is collected in these files,
and printed to the Lisp console when jlinker-end
is run.
|
Logical pathnames may be specified as values in place of regular pathnames. 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 port argument may be specified if the default is not sufficient (you may also use the obsolete lisp-port argument but you may not use the obsolete java-port argument). The arguments library, load, and file are ignored. The argument 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 jlinker starts the JVM, a command string is composed with a class
name and some arguments to the jlinker startup class. An application
can pass additional arguments by listing them in
the java-args argument. Arguments to the
JVM must be inserted before the class name in the command string. If
the first item in the java-args list is itself a
list beginning with :options, then the items
following :options are inserted as JVM arguments.
For example, to specify a large memory for the JVM, use the argument
:java-args '((:options "-Xmx2048m"))
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 LispCall
class to make the connection.
The file argument (you may also use the
obsolete 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 port as a non-zero value.
The host argument (you may also use the obsolete lisp-host argument): this argument is used when the file specified by the 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. If the timeout
is a negative number -v, signal a continuable error
after v seconds. If continued, wait
another v seconds.
When mode is :java-advertises,
the Lisp process attempts to connect to a separate Java process. The
Java application uses static methods in the LispCall class to make the
connection.
The file argument (you may also use the
obsolete 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 host argument (you may also use the
obsolete java-host argument): this argument must
specifiy the host where Java is advertising when
file is nil. The
default value is "localhost".
The port argument (you may also use the
obsolete java-port argument): this argument must
specifiy the port where Java is advertising when
file is nil. When
file is nil, this
argument must be specified as positive number greater than zero.
Lisp will attempt to connect poll-count times, with poll-interval seconds between attempts.
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 port, file, host, 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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version | ||||||||||