Calling Prolog Code from Java

Overview

PrologJ includes an API which allows Java code to access the Prolog database and to call code written in Prolog. Java objects are converted to the classes used internally by the PrologJ implementation. This API resides in the class prologj.PrologJ, and also makes use of the classes prologj.PrologBoundTerm, prologj.PrologContinuation, prologj.PrologException, prologj.PrologCompound and prologj.PrologList. Complete javadoc documentation is available for the class PrologJ and all the other classes it uses.

1. The PrologJ API contains multiple versions of each of the following methods, which correspond to the standard Prolog predicates of the same name:
    
   
   • asserta()
   • assertz()
   • call()
   • retract()
   • retractall()
    
   Each of these methods takes a parameter that specifies the term to be operated upon. Different versions of these methods allow the term to be specified by an object that implements the PrologBoundTerm interface, or by a string that represents the term in standard Prolog textual form.
    
   Two of these correspond to operations that can bind variables and that can succeed multiple times (call and retract). The methods that correspond to these include versions that take a second parameter that implements the PrologContinuation interface. This parameter provides a mechanism for accessing the bindings of variables that made an operation succeed, and for redoing an operation. The one-parameter versions of these methods only succeed once and don't provide any mechanism for accessing the bindings of variables.
    
   
2. The PrologJ API contains a method which converts the textual representation of a Prolog term into a bound term object that can be used as a parameter to the above methods.
    
   
   • makeBoundTerm()
      
     If multiple operations are going to be performed on the same term - especially in the body of the loop - it is more efficient to perform the conversion once and then use the bound term object repeatedly, rather than performing the conversion repeatedly, since the conversion entails a fair amount of overhead due to the need to parse text.
      
     On the other hand, if an operation is going to be performed on a given term just once or a very small number of times during the execution of a program, it may be more convenient to use the form of the above methods which takes a string as a parameter, rather than first converting the string to a bound term object and then passing it to the appropriate method. (In fact, the "string version" of the method performs this conversion for the caller.)
    
   
3. The PrologJ API contains methods which allow a text stream (encapsulated in any BufferedReader object) to be treated as a collection of clauses to be asserted into the database. These correspond to the "clause IO" predicates of the same name.
    
   
   • consult()
   • reconsult()
    
   
4. The PrologJ API contains a method which allows a text stream (encapsulated in any BufferedReader object) to be treated as a collection of goals to be executed.
    
   
   • interpret()
    
   
5. The PrologJ API contains methods which prints out a listing of the current contents of the database to any text stream (encapsulated in a PrintWriter object). This corresponds to the "clause IO" predicate of the same name.
    
   
   • listing()
    
   
6. The PrologJ API contains methods which allow a BufferedReader to be established as current_input or a PrintWriter to be established as current_output for future all input or output operations, until another stream replaces it. These methods are analogous to the standard Prolog predicates of the same name.
    
   
   • set_input()
   • set_output()
    
   
7. The PrologJ API contains a method which makes it possible to control which category(s) of built-in predicates are visible to the call() method.
    
   
   • setBuiltinPredicateCategories()

Bound Term Objects

The PrologJ API defines the concept of a bound term object, which encapsulates a Prolog term, together with information about the bindings of variables occurring within it. A bound term object is constructed from the textual representation of a Prolog term, either by explicit use of the makeBoundTerm() method of class PrologJ, or implicitly by using the textual representation of a Prolog term (represented by a String as a parameter to one of the methods of the API). Also, when a method that can bind variables (call or retract) succeeds , information about the variable bindings is encapsulated in a bound term object that is passed as a parameter to the succeed() method of the continuation object passed to the method call.

The capabilities of a bound term object are specified by the interface PrologBoundTerm.

• Two methods are available to allow "setting" a variable to some value (before the bound term is used as a parameter to asserta, assertz, call, retract or retractall).
   
  • This makes it possible to gain the efficiencies of creating a bound term in cases where the actual term passed to the relevant API method will differ slightly from call to call (similar to the mechanism used with java.sql.PreparedStatement).
     
  • This makes it possible to create a term in which some argument of a compound term is an object that does not have a Prolog representation - e.g. a Java object that is to be stored in the database and later retrieved. Of course, if it is necessary to do this, the program must expicitly create the bound term object with a variable in the place where a value will be supplied, must then set the variable to the appropriate value, and can then pass the bound term to the desired API method.
   
  
• Several methods allow obtaining information about the bindings of variables encapsulated in it after a method like call or retract has succeeded - i.e. when the bound term object is received as a parameter to the succeed method of some continuation.

Continuations

The PrologJ API defines the concept of a continuation, which allows operations to succeed multiple times. The API includes versions of the methods call and retract which take a continuation parameter.

The capabilities of a continuation object are specified by the interface PrologContinuation.

This interface specifies a single method of return type boolean which is called each time the operation succeeds. This method takes a single parameter which fulfills the BoundPrologTerm interface, and thus allows access to the bindings of variables that resulted in success. It returns false if it wants the implementation to try to find another way of satisfying the original goal, and true if to request no further attempts at re-doing the goal (in which case the original call or retract method returns true to its original caller.

Copyright © 2005 - Russell C. Bjork. See the file See file COPYING in the root directory for copyright information.