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

Prolog to Java interface

Author(s): Jesús Correas.

Version: 1.10#6 (2004/8/7, 21:46:39 CEST)

Version of last change: 1.9#67 (2003/3/14, 12:48:36 CET)

This module defines the Ciao Prolog to Java interface. This interface allows a Prolog program to start a Java process, create Java objects, invoke methods, set/get attributes (fields), and handle Java events.

This interface only works with JDK version 1.2 or higher.

Although the Java side interface is explained in Javadoc format (it is available at library/javall/javadoc/ in your Ciao installation), the general interface structure is detailed here.

Prolog to Java Interface Structure

This interface is made up of two parts: a Prolog side and a Java side, running in separate processes. The Prolog side receives requests from a Prolog program and sends them to the Java side through a socket. The Java side receives requests from the socket and performs the actions included in the requests.

If an event is thrown in the Java side, an asynchronous message must be sent away to the Prolog side, in order to launch a Prolog goal to handle the event. This asynchronous communication is performed using a separate socket. The nature of this communication needs the use of threads both in Java and Prolog: to deal with the 'sequential program flow,' and other threads for event handling.

In both sides the threads are automatically created by the context of the objects we use. The user must be aware that different requests to the other side of the interface could run concurrently.

Prolog side of the Java interface

The Prolog side receives the actions to do in the Java side from the user program, and sends them to the Java process through the socket connection. When the action is done in the Java side, the result is returned to the user Prolog program, or the action fails if there is any problem in the Java side.

Prolog data representation of Java elements is very simple in this interface. Java primitive types such as integers and characters are translated into the Prolog corresponding terms, and even some Java objects are translated in the same way (e. g. Java strings). Java objects are represented in Prolog as compound terms with a reference id to identify the corresponding Java object. Data conversion is made automatically when the interface is used, so the Prolog user programs do not have to deal with the complexity of this tasks.

Java side

The Java side of this layer is more complex than the Prolog side. The tasks this part has to deal to are the following:

In the implementation of the Java side, two items must be carefully designed: the handling of Java objects, and the representation of prolog data structures. The last item is specially important because all the interactions between Prolog and Java are made using Prolog structures, an easy way to standardize the different data management in both sides. Even the requests themselves are encapsulated using Prolog structures. The overload of this encapsulation is not significant in terms of socket traffic, due to the optimal implementation of the prolog serialized term.

The java side must handle the objects created from the Prolog side dinamically, and these objects must be accessed as fast as possible from the set of objects. The Java API provides a powerful implementation of Hash tables that achieves all the requirements of our implementation.

On the other hand, the java representation of prolog terms is made using the inheritance of java classes. In the java side exists a representation of a generic prolog term, implemented as an abstract class in java. Variables, atoms, compound terms, lists, and numeric terms are classes in the java side which inherit from the term class. Java objects can be seen also under the prolog representation as compound terms, where the single argument corresponds to the Hash key of the actual java object in the Hash table referred to before. This behaviour makes the handling of mixed java and prolog elements easy. Prolog goals are represented in the java side as objects which contain a prolog compound term with the term representing the goal. This case will be seen more in depth next, when the java to prolog is explained.

Java event handling from Prolog

Java event handling is based on a delegation model since version 1.1.x. This approach to event handling is very powerful and elegant, but a user program cannot handle all the events that can arise on a given object: for each kind of event, a listener must be implemented and added specifically. However, the Java 2 API includes a special listener (AWTEventListener) that can manage the internal java event queue.

The prolog to java interface has been designed to emulate the java event handler, and is also based on event objects and listeners. The prolog to java interface implements its own event manager, to handle those events that have prolog listeners associated to the object that raises the event. From the prolog side can be added listeners to objects for specific events. The java side includes a list of goals to launch from the object and event type.

Due to the events nature, the event handler must work in a separate thread to manage the events asynchronously. The java side has its own mechanisms to work this way. The prolog side must be implemented specially for event handling using threads. The communication between java and prolog is also asynchronous, and an additional socket stream is used to avoid interferences with the main socket stream. The event stream will work in this implementation only in one way: from java to prolog. If an event handler needs to send back requests to java, it will use the main socket stream, just like the requests sent directly from a prolog program.

The internal process of register a Prolog event handler to a Java event is shown in the next figure:


When an event raises, the Prolog to Java interface has to send to the Prolog user program the goal to evaluate. Graphically, the complete process takes the tasks involved in the following figure:


Java exception handling from Prolog

Java exception handling is very similar to the peer prolog handling: it includes some specific statements to trap exceptions from user code. In the java side, the exceptions can be originated from an incorrect request, or can be originated in the code called from the request. Both exception types will be sent to prolog using the main socket stream, allowing the prolog program manage the exception. However, the first kind of exceptions are prefixed, so the user program can distinguish them from the second type of exceptions.

In order to handle exceptions properly using the prolog to java and java to prolog interfaces simultaneously, in both sides of the interface will be filtered those exceptions coming from their own side: this avoids an endless loop of exceptions bouncing from one side to another.

Usage and interface (javart)

Documentation on exports (javart)

PREDICATE: java_start/0:


PREDICATE: java_start/1:

Usage: java_start(+Classpath)

PREDICATE: java_start/2:

Usage: java_start(+machine_name, +classpath)

PREDICATE: java_stop/0:


PREDICATE: java_connect/2:

Usage: java_connect(+machine_name, +port_number)

PREDICATE: java_disconnect/0:


REGTYPE: machine_name/1:

Usage: machine_name(X)

REGTYPE: java_constructor/1:

Usage: java_constructor(X)

REGTYPE: java_object/1:

Usage: java_object(X)

REGTYPE: java_event/1:

Usage: java_event(X)

REGTYPE: prolog_goal/1:

Usage: prolog_goal(X)

REGTYPE: java_field/1:

Usage: java_field(X)

PREDICATE: java_use_module/1:

Usage: java_use_module(+Module)

PREDICATE: java_create_object/2:

Usage: java_create_object(+java_constructor, -java_object)

PREDICATE: java_delete_object/1:

Usage: java_delete_object(+java_object)

PREDICATE: java_invoke_method/2:

Usage: java_invoke_method(+java_object, +java_method)

REGTYPE: java_method/1:

Usage: java_method(X)

PREDICATE: java_get_value/2:

Usage: java_get_value(+java_object, +java_field)

PREDICATE: java_set_value/2:

Usage: java_set_value(+java_object, +java_field)

PREDICATE: java_add_listener/3:

Meta-predicate with arguments: java_add_listener(?,?,goal).

Usage: java_add_listener(+java_object, +java_event, +prolog_goal)

PREDICATE: java_remove_listener/3:

Usage: java_remove_listener(+java_object, +java_event, +prolog_goal)

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