com.declarativa.interprolog
Class PrologEngine

java.lang.Object
  |
  +--com.declarativa.interprolog.PrologEngine
Direct Known Subclasses:
NativeEngine, SubprocessEngine

public abstract class PrologEngine
extends Object

The heart of InterProlog; a PrologEngine represents a Prolog abstract machine instance. This is an abstract class; you should use it just to declare variables, but must instantiate only a subclass.


Field Summary
 String firstJavaMessageName
          Name of first message sent to Java
 boolean interrupting
          Prolog is handling an interrupt
static int MAX_INT_VALUE
          Maximum integer value.
static int MIN_INT_VALUE
          Minimum integer value.
static String nl
          Convenience for newline
 String startPrologCommand
          File path to Prolog machine
static String version
          InterProlog version
 
Constructor Summary
PrologEngine(String startPrologCommand, boolean debug)
          Create a Prolog executor, possibly spawning it in a different process or loading it into memory, depending on the implementation by our subclass.
 
Method Summary
 void abortTasks()
          Do not invoke this
static boolean assignableType(Class left, Class right)
          It is OK to assign an expression typed right to a variable typed left.
 boolean command(String s)
          Execute a Prolog "command"
 void consultFromPackage(String filename, Object requester)
          Extracts a Prolog file from the jar file or directory where the requester's class came from, and asks the background Prolog process to consult it.
 void consultRelative(String filename, Object requester)
          Consults a Prolog file from the directory where the requester's class would come from if it did not come from a jar file.
 boolean deterministicGoal(String G)
          A parameterless goal with no result other than success/failure.
 Object[] deterministicGoal(String G, String RVars)
          Useful when you're constructing objects from Prolog, but don't need to pass any from Java.
 boolean deterministicGoal(String G, String OVar, Object[] objectsP)
          Useful when you want to pass objects to Prolog but don't need objects returned.
 Object[] deterministicGoal(String G, String OVar, Object[] objectsP, String RVars)
          Synchronously calls a Prolog goal.
 ResultFromJava doCallback(Object x)
          Execute a Prolog->Java call
static Constructor findConstructor(Class targetClass, Class[] formalArguments)
          Similar to findMethod(), but for constructors rather than regular methods
static Method findMethod(Class targetClass, String name, Class[] formalArguments)
          An utility building on the functionality of getMethod(), to provide the javaMessage predicate with method argument polimorphism.
 void firstJavaMessage()
          Dummy method, whose name is used to start the callback thread
 File getJarDirectory()
          Returns the directory containing the jar with the engine class
static File getJarDirectory(Class aClass)
          Returns the directory containing the jar with the given class
 Object getRealJavaObject(int ID)
          Same as getRealJavaObject(InvisibleObject), but accepts an integer ID as argument instead
 Object getRealJavaObject(InvisibleObject o)
          Get the object referred by the integer in a InvisibleObject wrapper.
 Object getRealJavaObject(Object o)
          Just returns the object, untouched (but "dereferenced" if called from Prolog).
 Object handleCallback(Object x)
          Handling of javaMessages and deterministicGoals.
 void interrupt()
          Interrupt Prolog and make it return to its top level.
 void interruptTasks()
          Do not invoke this
 boolean isAvailable()
          Present implementation is always available, so this always returns true
 boolean isDebug()
          Debug messages are being written
 boolean isIdle()
          The engine is doing nothing
 void load_dynRelative(String filename, Object requester)
           
 Object makeInvisible(Object x)
          Register an object with this Engine, so it later can be referred from Prolog without serializing it, and returns an InvisibleObject encapsulating the reference.
static void printBindings(Object[] b)
          Convenience for debugging
 void progressMessage(String s)
          Debugging aid
 int registerJavaObject(Object x)
          Register an object with this Engine, so it later can be referred from Prolog without serializing it.
 void setDebug(boolean d)
           
static String shortClassName(Class c)
           
abstract  void shutdown()
          Release Prolog engine resources, making it unusable
 boolean teachMoreObjects(Object[] examples)
          Same as #teachMoreObjects(ObjectExamplePair[]), but example pairs are constructed with (2) repeated examples for each object
 boolean teachMoreObjects(ObjectExamplePair[] examples)
          Send an array of object example pairs to Prolog and generate ipObjectSpec facts.
 boolean teachOneObject(Object example)
          Same as #teachMoreObjects(ObjectExamplePair[]), but the single example pair is constructed repeating the object
 void waitUntilAvailable()
           
 void waitUntilIdle()
          Sleeps the current Java thread until this engine is available.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

version

public static final String version
InterProlog version

See Also:
Constant Field Values

startPrologCommand

public String startPrologCommand
File path to Prolog machine


nl

public static final String nl
Convenience for newline


interrupting

public boolean interrupting
Prolog is handling an interrupt


firstJavaMessageName

public final String firstJavaMessageName
Name of first message sent to Java

See Also:
Constant Field Values

MAX_INT_VALUE

public static final int MAX_INT_VALUE
Maximum integer value. 28 bits is all we got on XSB Prolog

See Also:
Constant Field Values

MIN_INT_VALUE

public static final int MIN_INT_VALUE
Minimum integer value.

See Also:
Constant Field Values
Constructor Detail

PrologEngine

public PrologEngine(String startPrologCommand,
                    boolean debug)
Create a Prolog executor, possibly spawning it in a different process or loading it into memory, depending on the implementation by our subclass.

Parameters:
startPrologCommand - File path to Prolog machine, see subclass docs for precise semantics
debug - if true, print progress messages to aid debugging
Method Detail

shutdown

public abstract void shutdown()
Release Prolog engine resources, making it unusable


getJarDirectory

public File getJarDirectory()
Returns the directory containing the jar with the engine class


getJarDirectory

public static File getJarDirectory(Class aClass)
Returns the directory containing the jar with the given class


consultFromPackage

public void consultFromPackage(String filename,
                               Object requester)
Extracts a Prolog file from the jar file or directory where the requester's class came from, and asks the background Prolog process to consult it. You should use this method only after your program is stable. The Prolog file is extracted to a temporary file, and automatically deleted on exiting the application.

Parameters:
filename - The Prolog file name, including suffix; if absent ".P" is appended
requester - Defines where the Prolog file resides
See Also:
consultRelative(String, Object), load_dynRelative(String, Object)

consultRelative

public void consultRelative(String filename,
                            Object requester)
Consults a Prolog file from the directory where the requester's class would come from if it did not come from a jar file. Adds that directory to the library_directory relation, so modules can be found there

Parameters:
filename - The Prolog file name, including suffix; if absent ".P" is appended
requester - Defines where the Prolog file resides

load_dynRelative

public void load_dynRelative(String filename,
                             Object requester)

interrupt

public void interrupt()
Interrupt Prolog and make it return to its top level. This is the equivalent to performing a ctrl+c or similar command when using Prolog under a standard console shell.


command

public boolean command(String s)
Execute a Prolog "command"


progressMessage

public void progressMessage(String s)
Debugging aid


isDebug

public boolean isDebug()
Debug messages are being written


setDebug

public void setDebug(boolean d)

printBindings

public static void printBindings(Object[] b)
Convenience for debugging


teachOneObject

public boolean teachOneObject(Object example)
Same as #teachMoreObjects(ObjectExamplePair[]), but the single example pair is constructed repeating the object

See Also:
teachMoreObjects(ObjectExamplePair[])

teachMoreObjects

public boolean teachMoreObjects(Object[] examples)
Same as #teachMoreObjects(ObjectExamplePair[]), but example pairs are constructed with (2) repeated examples for each object

See Also:
teachMoreObjects(ObjectExamplePair[])

teachMoreObjects

public boolean teachMoreObjects(ObjectExamplePair[] examples)
Send an array of object example pairs to Prolog and generate ipObjectSpec facts. Returns true if this succeeds, false otherwise.

Parameters:
examples - The examples
See Also:
ObjectExamplePair

deterministicGoal

public Object[] deterministicGoal(String G,
                                  String OVar,
                                  Object[] objectsP,
                                  String RVars)
Synchronously calls a Prolog goal. Only the first solution is considered. G should contain a syntactically correct Prolog term, without the trailing dot (.). Throws an IPAbortedException if a Prolog abort happens, and an IPInterruptedException if the interrupt() method was invoked.

Parameters:
G - Prolog goal term
OVar - Prolog variable that will be bound to objectsP array
objectsP - Array of Java objects to pass to Prolog goal
RVars - Prolog list with object specifications, typically containing variables occurring in g. If null a single binding will be returned, containing a TermModel object representing the goal term solution
Returns:
a new array containing an object for each term in the rVars list, or null if goal fails
See Also:
deterministicGoal(String), deterministicGoal(String,String), deterministicGoal(String,String,Object[])

deterministicGoal

public boolean deterministicGoal(String G)
A parameterless goal with no result other than success/failure. Same as deterministicGoal(G, null,null,"[]")


deterministicGoal

public Object[] deterministicGoal(String G,
                                  String RVars)
Useful when you're constructing objects from Prolog, but don't need to pass any from Java. Same as deterministicGoal(G,null,null,RVars)


deterministicGoal

public boolean deterministicGoal(String G,
                                 String OVar,
                                 Object[] objectsP)
Useful when you want to pass objects to Prolog but don't need objects returned. Same as deterministicGoal(G, OVar,objectsP,"[]")


isIdle

public boolean isIdle()
The engine is doing nothing


abortTasks

public void abortTasks()
Do not invoke this


interruptTasks

public void interruptTasks()
Do not invoke this


isAvailable

public boolean isAvailable()
Present implementation is always available, so this always returns true


waitUntilAvailable

public void waitUntilAvailable()

waitUntilIdle

public void waitUntilIdle()
Sleeps the current Java thread until this engine is available. If this never happens, we're in trouble.


handleCallback

public Object handleCallback(Object x)
Handling of javaMessages and deterministicGoals. This is where most things happen.

Parameters:
x - Argument of the callback predicate

firstJavaMessage

public final void firstJavaMessage()
Dummy method, whose name is used to start the callback thread


doCallback

public ResultFromJava doCallback(Object x)
Execute a Prolog->Java call


findMethod

public static Method findMethod(Class targetClass,
                                String name,
                                Class[] formalArguments)
                         throws NoSuchMethodException
An utility building on the functionality of getMethod(), to provide the javaMessage predicate with method argument polimorphism. If the type signatures do not match exactly, searches all method signatures to see if their arguments are type-compatible.

NoSuchMethodException

findConstructor

public static Constructor findConstructor(Class targetClass,
                                          Class[] formalArguments)
                                   throws NoSuchMethodException
Similar to findMethod(), but for constructors rather than regular methods

NoSuchMethodException

assignableType

public static boolean assignableType(Class left,
                                     Class right)
It is OK to assign an expression typed right to a variable typed left. Delegates on isAssignableFrom


shortClassName

public static String shortClassName(Class c)

registerJavaObject

public int registerJavaObject(Object x)
Register an object with this Engine, so it later can be referred from Prolog without serializing it.

Parameters:
x - Object to be registered
See Also:
InvisibleObject

makeInvisible

public Object makeInvisible(Object x)
Register an object with this Engine, so it later can be referred from Prolog without serializing it, and returns an InvisibleObject encapsulating the reference.

Parameters:
x - Object to be registered
See Also:
InvisibleObject

getRealJavaObject

public Object getRealJavaObject(InvisibleObject o)
Get the object referred by the integer in a InvisibleObject wrapper.

Parameters:
o - An InvisibleObject
See Also:
InvisibleObject

getRealJavaObject

public Object getRealJavaObject(int ID)
Same as getRealJavaObject(InvisibleObject), but accepts an integer ID as argument instead


getRealJavaObject

public Object getRealJavaObject(Object o)
Just returns the object, untouched (but "dereferenced" if called from Prolog). This serves the need to get objects in javaMessage because of the way CallbackHandler.doCallback works. For example: ipPrologEngine(_E), stringArraytoList(_O,[miguel,calejo]), javaMessage(_E,_R,getRealJavaObject(_O)),stringArraytoList(_R,List). ... will bind List to [miguel,calejo] and not to an InvisibleObject specification as ordinarly would happen