jlinker-init

Arguments: &optional mode &key lisp-port lisp-host lisp-file java-port java-host java-file timeout java-args preload debug verbose

Definition

This function establishes communication with a Java server. The value returned is a keyword identifying the last step that was performed. The result is a list if an error is detected.

The mode argument is one of the keywords

:start-java or :start
:lisp-advertises or :lisp
:java-advertises or :java

When mode is :start-java (the default), Lisp starts the Java VM as a dedicated server. The following keywords may be used to modify the default values:

:lisp-port      nil
:lisp-host      "localhost"
:java-port      nil
:java-host      "localhost"

NOTE: If :java-host is not the default value, the user must supply a function that starts Java at the desired host. The name of this function is stored in the variable *jlinker-run-java*.

When mode is :lisp-advertises, Lisp advertises a server and assumes Java will start independently and connect to the server. The following keywords may be used to modify the default values:

:lisp-file      "JavaToLisp.trp"
:lisp-port      nil
:lisp-host      "localhost"
:timeout        nil

If :lisp-file is specified as 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. If :timeout is a number greater than 0, then it is the number of seconds Lisp will wait for Java to respond.

When mode is :java-advertises, Lisp expects the Java server to start independently and advertise its server. The following keywords may be used to modify the default values:

:java-file      "LispToJava.trp"
:java-port      nil
:java-host      "localhost"
:lisp-port      nil
:lisp-host      "localhost"

When :java-file is non-nil, :java-port and :java-host are ignored. When :java-file is nil, Java is not expected to write a file; Lisp simply tries to connect to the :java-port socket at :java-host; in this case :java-port must be non-zero. If Java is not ready when Lisp tries to connect, an error message (list) is returned.

When the java-port argument is specified as a negative number, Lisp opens a passive socket for both the Lisp server and the Java server. Thus, the Java application connects to a listening socket for the Lisp server connection and also for the Java server connection. This feature is useful if the Java application is prevented from listening at sockets because of security restrictions.

The following keywords alter the behavior of the init program:

• :java-args: A list of arguments passed to Java if Java is started by Lisp. These are added after the ones passed by jLinker.
• :debug: When t, start the Java server in debug mode. The default is nil.
• :verbose: When T, emit status and warning messages. The default is T.

When Lisp and Java are on different hosts

When Lisp and Java are on different network hosts, host names must be specified because in many cases a program cannot determine the host name or address of the current machine.

If Lisp advertises:

If Lisp advertises in a file, the lisp-host to jlinker-init must be other than nil, "", or "localhost".

If Lisp advertises at a port number, the lisp-host argument is not needed.

On the Java side the Java host name must be specified and different from "" or "localhost" or "127.0.0.1" in the call to JavaLinkDist.connect(), or in the setting of LispConnector.javaHost.

If Java advertises:

If Java advertises in a file, the host argument to JavaLinkDist.advertise() must be specified and different from "" or "localhost" or "127.0.0.1" or LispConnector.javaHost must be set similarly.

If Java advertises at a port number the Java host is not needed.

On the Lisp side, the lisp-host argument to jlinker-init must be other than nil, "", or "localhost".

See jlinker.htm for more information on the jLinker facility.

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.