## 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