FunctionPackage: javatools.jlinkerToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
Unrevised from 8.0 to 8.1. Minimal update since 8.1 release.
8.0 version

jlinker-init

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

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 mode argument

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.

jlinker-init return value

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:

jlinker-init keyword arguments

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.

The classpath and jar keyword arguments

If either argument is specified, then the Java classpath value is the concatenation of the following three values:

  1. The classpath argument: A string is used verbatim; A list (of strings) is concatenated into a string where the list elements are separated by the classpath separator; nil or no value specified means use the string ".".
  2. The current value of the CLASSPATH environment variable.
  3. The resolved jar file path. This file must be visible to the Java VM for the correct operation of the jlinker interface.

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:

  1. If a file "jlinker.jar" exists in the current directory, it is the default.
  2. If the file with logical pathname "sys:jlinker;jlinker.jar" exists, it is the default.

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.

Mode :start-java

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.

Mode :lisp-advertises

When mode is :lisp-advertises, the Lisp process waits for a separate Java application to make contact. The Java application uses 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.

Mode :java-advertises

Mode :java-advertises

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.

Mode :native (new in Allegro CL 8.0)

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-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page was not revised from the 8.0 page.
Created 2009.7.29.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
Unrevised from 8.0 to 8.1. Minimal update since 8.1 release.
8.0 version