Author(s): Jesús Correas.
Version: 1.11#222 (2004/5/24, 13:8:7 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.
This interface is made up of two parts: a Prolog part and a Java part, running in separate processes. The Prolog part receives requests from a Prolog program and sends them to the Java part through a socket. The Java part 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.
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.
The Java side of this layer is more complex than the Prolog side. The tasks this part have to deal to are the following:
library/javall/javadoc/ in your Ciao installation for details regarding Java representation of Prolog terms).
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 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 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.
javart):- use_module(library(javart)).
java_start/0,
java_start/1,
java_start/2,
java_stop/0,
java_connect/2,
java_disconnect/0,
java_use_module/1,
java_create_object/2,
java_delete_object/1,
java_invoke_method/2,
java_get_value/2,
java_set_value/2,
java_add_listener/3,
java_remove_listener/3.
machine_name/1,
java_constructor/1,
java_object/1,
java_event/1,
prolog_goal/1,
java_field/1,
java_method/1.
javart)Usage:
Usage: java_start(Classpath)
Classpath is a string (a list of character codes).
(basic_props:string/1)
Classpath is currently a term which is not a free variable.
(term_typing:nonvar/1)
Usage:
Arg1 is currently instantiated to an atom.
(term_typing:atom/1)
Arg2 is a string (a list of character codes).
(basic_props:string/1)
Arg1 is the network name of a machine.
(javart:machine_name/1)
undefined:classpath(Arg2)
(undefined property)
Usage:
Usage:
Arg1 is the network name of a machine.
(javart:machine_name/1)
Arg2 is an integer.
(basic_props:int/1)
Arg1 is the network name of a machine.
(javart:machine_name/1)
undefined:port_number(Arg2)
(undefined property)
Usage:
Usage: machine_name(X)
X is the network name of a machine.
Usage: java_constructor(X)
X is a java constructor (structure with functor as constructor full name, and arguments as constructor arguments).
Usage: java_object(X)
X is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
Usage: java_event(X)
X is a java event represented as an atom with the full event constructor name (e.g., 'java.awt.event.ActionListener').
Usage: prolog_goal(X)
X is a prolog predicate. Prolog term that represents the goal that must be invoked when the event raises on the object. The predicate arguments can be java objects, or even the result of java methods. These java objects will be evaluated when the event raises (instead of when the listener is added). The arguments that represent java objects must be instantiated to already created objects. The variables will be kept uninstantiated when the event raises and the predicate is called.
Usage: java_field(X)
X is a java field (structure on which the functor name is the field name, and the single argument is the field value).
Usage: java_use_module(Module)
Module is any term.
(basic_props:term/1)
Module is currently a term which is not a free variable.
(term_typing:nonvar/1)
Usage:
Arg1 is a java constructor (structure with functor as constructor full name, and arguments as constructor arguments).
(javart:java_constructor/1)
Arg2 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg1 is a java constructor (structure with functor as constructor full name, and arguments as constructor arguments).
(javart:java_constructor/1)
Arg2 is a free variable.
(term_typing:var/1)
Arg2 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Usage:
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Usage:
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java method (structure with functor as method name, and arguments as method ones, plus a result argument. This result argument is unified with the atom 'Yes' if the java method returns void).
(javart:java_method/1)
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java method (structure with functor as method name, and arguments as method ones, plus a result argument. This result argument is unified with the atom 'Yes' if the java method returns void).
(javart:java_method/1)
Usage: java_method(X)
X is a java method (structure with functor as method name, and arguments as method ones, plus a result argument. This result argument is unified with the atom 'Yes' if the java method returns void).
Usage:
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java field (structure on which the functor name is the field name, and the single argument is the field value).
(javart:java_field/1)
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java field (structure on which the functor name is the field name, and the single argument is the field value).
(javart:java_field/1)
Usage:
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java field (structure on which the functor name is the field name, and the single argument is the field value).
(javart:java_field/1)
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java field (structure on which the functor name is the field name, and the single argument is the field value).
(javart:java_field/1)
Meta-predicate with arguments: java_add_listener(?,?,goal).
Usage:
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java event represented as an atom with the full event constructor name (e.g., 'java.awt.event.ActionListener').
(javart:java_event/1)
Arg3 is a prolog predicate. Prolog term that represents the goal that must be invoked when the event raises on the object. The predicate arguments can be java objects, or even the result of java methods. These java objects will be evaluated when the event raises (instead of when the listener is added). The arguments that represent java objects must be instantiated to already created objects. The variables will be kept uninstantiated when the event raises and the predicate is called.
(javart:prolog_goal/1)
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java event represented as an atom with the full event constructor name (e.g., 'java.awt.event.ActionListener').
(javart:java_event/1)
Arg3 is a prolog predicate. Prolog term that represents the goal that must be invoked when the event raises on the object. The predicate arguments can be java objects, or even the result of java methods. These java objects will be evaluated when the event raises (instead of when the listener is added). The arguments that represent java objects must be instantiated to already created objects. The variables will be kept uninstantiated when the event raises and the predicate is called.
(javart:prolog_goal/1)
Usage:
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java event represented as an atom with the full event constructor name (e.g., 'java.awt.event.ActionListener').
(javart:java_event/1)
Arg3 is a prolog predicate. Prolog term that represents the goal that must be invoked when the event raises on the object. The predicate arguments can be java objects, or even the result of java methods. These java objects will be evaluated when the event raises (instead of when the listener is added). The arguments that represent java objects must be instantiated to already created objects. The variables will be kept uninstantiated when the event raises and the predicate is called.
(javart:prolog_goal/1)
Arg1 is a java object (a structure with functor '$java_object', and argument an integer given by the java side).
(javart:java_object/1)
Arg2 is a java event represented as an atom with the full event constructor name (e.g., 'java.awt.event.ActionListener').
(javart:java_event/1)
Arg3 is a prolog predicate. Prolog term that represents the goal that must be invoked when the event raises on the object. The predicate arguments can be java objects, or even the result of java methods. These java objects will be evaluated when the event raises (instead of when the listener is added). The arguments that represent java objects must be instantiated to already created objects. The variables will be kept uninstantiated when the event raises and the predicate is called.
(javart:prolog_goal/1)
Go to the first, previous, next, last section, table of contents.