Low-level Java to Prolog interface

Author(s): Jesús Correas.

Version: 1.5#118 (2000/4/19, 18:13:43 CEST)

Version of last change: 1.5#40 (2000/2/8, 16:32:42 CET)

This module defines a low level Java to Prolog interface. This Prolog side of the Java to Prolog interface only has one public predicate: a server that listens at the socket connection with Java, and executes the commands received from the Java side.

In order to evaluate the goals received from the Java side, this module can work in two ways: executing them in the same engine, or starting a thread for each goal. The easiest way is to launch them in the same engine, but the goals must be evaluated sequentially: once a goal provides the first solution, all the subsequent goals must be finished before this goal can backtrack to provide another solution. The Prolog side of this interface works as a top-level, and the goals partially evaluated are not independent.

The solution of this goal dependence is to evaluate the goals in a different prolog engine. Although Ciao includes a mechanism to evaluate goals in different engines, the approach used in this interface is to launch each goal in a different thread.

The decision of what kind of goal evaluation is selected is done by the Java side. Each evaluation type has its own command terms, so the Java side can choose the type it needs.

A Prolog server starts by calling the prolog_server/0 predicate. The user predicates and libraries to be called from Java must be included in the executable file, or be accesible using the built-in predicates dealing with code loading.

• Usage and interface (jtopl)
• Documentation on exports (jtopl)
• Documentation on internals (jtopl)

Usage and interface (jtopl)

Documentation on exports (jtopl)

PREDICATE: prolog_server/0:

Usage:

• Description: Prolog server entry point. Reads from the standard input the node name and port number where the java client resides, and starts the prolog server listening at the data socket. This predicate acts as a server: it includes an endless read-process loop until the prolog_exit command is received.

Documentation on internals (jtopl)

REGTYPE: command/1:

Usage: command(X)

• Description: X is a command received from the java client, to be executed by the Prolog process. The command is represented as an atom or a functor with arity 1. The command to be executed must be one of the following types:
  • prolog_launch_query(Q) Compound term to create a new query, received as single argument of this structure. A reference to the new query is returned to Java.
  • prolog_launch_query_on_thread(Q) Compound term to evaluate a new query using a separate thread. A reference to the new query is returned to Java.
  • prolog_next_solution(ID) Compound term to get the next solution of a goal identified by the single argument of the structure. A term representing the goal instantiated with the next solution is returned to Java.
  • prolog_terminate_query(ID) Compound term to terminate the goal identified by the argument. If the thread option is disabled, a cut is made in the goal search tree, and the goal is removed from the goal table; if the thread option is enabled, the thread evaluating the goal is terminated.
  • prolog_exit Atom to terminate the current Prolog process.

REGTYPE: answer/1:

Usage: answer(X)

• Description: X is a response sent from the prolog server. Is represented as an atom or a functor with arity 1 or 2, depending on the functor name.

REGTYPE: prolog_query/1:

Usage: prolog_query(X)

• Description: X is a query to be launched from the prolog server.

PREDICATE: shell_s/0:

Usage:

• Description: Command execution loop. This predicate is called when the connection to Java is established, and performs an endless loop dealing with the following tasks:
  • reads a command from the socket. All the commands are explained in the command type description,
  • processes the command using the process_first_command/1 and process_next_command/1 predicates, and
  • returns the results of the command execution.

PREDICATE: process_first_command/1:

Usage: process_first_command(+Command)

• Description: Processes the first command of a query. Using the threads option, it processes all the commands received from the prolog server.
• Call and exit should be compatible with: +Command is a command received from the java client, to be executed by the Prolog process. The command is represented as an atom or a functor with arity 1. The command to be executed must be one of the following types:
  • prolog_launch_query(Q) Compound term to create a new query, received as single argument of this structure. A reference to the new query is returned to Java.
  • prolog_launch_query_on_thread(Q) Compound term to evaluate a new query using a separate thread. A reference to the new query is returned to Java.
  • prolog_next_solution(ID) Compound term to get the next solution of a goal identified by the single argument of the structure. A term representing the goal instantiated with the next solution is returned to Java.
  • prolog_terminate_query(ID) Compound term to terminate the goal identified by the argument. If the thread option is disabled, a cut is made in the goal search tree, and the goal is removed from the goal table; if the thread option is enabled, the thread evaluating the goal is terminated.
  • prolog_exit Atom to terminate the current Prolog process.
  (jtopl:command/1)

PREDICATE: process_next_command/2:

Usage: process_next_command(+Id,+Command)

• Description: Process the commands received from the prolog server when a query is being handled.
• Call and exit should be compatible with: undefined:prolog_query_id(+Id) (undefined property) +Command is a command received from the java client, to be executed by the Prolog process. The command is represented as an atom or a functor with arity 1. The command to be executed must be one of the following types:
  • prolog_launch_query(Q) Compound term to create a new query, received as single argument of this structure. A reference to the new query is returned to Java.
  • prolog_launch_query_on_thread(Q) Compound term to evaluate a new query using a separate thread. A reference to the new query is returned to Java.
  • prolog_next_solution(ID) Compound term to get the next solution of a goal identified by the single argument of the structure. A term representing the goal instantiated with the next solution is returned to Java.
  • prolog_terminate_query(ID) Compound term to terminate the goal identified by the argument. If the thread option is disabled, a cut is made in the goal search tree, and the goal is removed from the goal table; if the thread option is enabled, the thread evaluating the goal is terminated.
  • prolog_exit Atom to terminate the current Prolog process.
  (jtopl:command/1)

PREDICATE: solve/1:

Usage: solve(+Query)

• Description: Runs the query processing the commands received from the java side, and handles query nesting. It is used only with the thread option disabled.
• Call and exit should be compatible with: +Query is a query to be launched from the prolog server. (jtopl:prolog_query/1)

PREDICATE: solve_on_thread/1:

Usage: solve_on_thread(+Query)

• Description: Runs the query on a separate thread and stores the solutions on the query_solutions/2 data predicate.
• Call and exit should be compatible with: +Query is a query to be launched from the prolog server. (jtopl:prolog_query/1)

PREDICATE: get_query_id/1:

Usage: get_query_id(-(Id))

• Description: Produces the query id for the next query, when is invoked the threads option disabled.
• Call and exit should be compatible with: undefined:prolog_query_id(-(Id)) (undefined property)

PREDICATE: prolog_parse/2:

Usage: prolog_parse(+String,-(Term))

• Description: Parses the string received as first argument and returns the prolog term as second argument. Important: This is a private predicate but could be called from java side, to parse strings to Prolog terms.
• Call and exit should be compatible with: +String is a string (a list of character codes). (basic_props:string/1) -(Term) is any term. (basic_props:term/1)

PREDICATE: read_command/1:

Usage: read_command(-(Command))

• Description: Reads from the input stream a new prolog server command.
• Call and exit should be compatible with: -(Command) is a command received from the java client, to be executed by the Prolog process. The command is represented as an atom or a functor with arity 1. The command to be executed must be one of the following types:
  • prolog_launch_query(Q) Compound term to create a new query, received as single argument of this structure. A reference to the new query is returned to Java.
  • prolog_launch_query_on_thread(Q) Compound term to evaluate a new query using a separate thread. A reference to the new query is returned to Java.
  • prolog_next_solution(ID) Compound term to get the next solution of a goal identified by the single argument of the structure. A term representing the goal instantiated with the next solution is returned to Java.
  • prolog_terminate_query(ID) Compound term to terminate the goal identified by the argument. If the thread option is disabled, a cut is made in the goal search tree, and the goal is removed from the goal table; if the thread option is enabled, the thread evaluating the goal is terminated.
  • prolog_exit Atom to terminate the current Prolog process.
  (jtopl:command/1)

PREDICATE: write_answer/1:

Usage: write_answer(+Answer)

• Description: writes to the output socket stream the given answer.
• Call and exit should be compatible with: +Answer is a response sent from the prolog server. Is represented as an atom or a functor with arity 1 or 2, depending on the functor name. (jtopl:answer/1)

Go to the first, previous, next, last section, table of contents.