jlinker-init

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

The function was modified (by the addition of the error-p keyword argument and the resulting changes in handling errors) in jlinker version 3.2.4 released as patch jlinker.001 around Dec. 6, 2002. The currently running version is returned by the function jlinker-version, with a call like (javatools.jlinker:jlinker-version). Get the patch for the new version with sys:update-allegro.

Definition

This function establishes communication with a Java server. The value returned is a keyword identifying the last step that was performed. If error-p is nil, 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 keyword arguments 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 the value of *jlinker-debug*.
• verbose: When t, emit status and warning messages. The default is the value of *jlinker-verbose*.
• error-p: this argument determines the behavior of jlinker-init when an error occurs. If the value of this argument is true, an error of type jlinker-error is signaled. If the value is nil, no error is signaled and jlinker-init returns a list containing information about the error (jlinker-init returns a keyword when no error occurs). This argument defaults to the value of *jlinker-error-p*.

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".

Avoid calling jlinker-init twice

It is not recommended to call jlinker-init when an active connection already exists. In many cases, jLinker can determine that the connection is there and the call to jlinker-init is in effect a no-op, but in some cases, jlinker-init may try to open another connection to Java with inconsistent parameters.

If it is possible for jlinker-init to be called from several places in an application, a form such as

(or (jlinker-query t) (jlinker-init ... ))

should be used to prevent a redundant call to jlinker-init (see also jlinker-query).

In some applications, the form

(progn (jlinker-end) (jlinker-init ... ))

may be appropriate. It forces an existing connection to be closed before jlinker-init is called again (see also jlinker-end).

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.