PrologEngine (InterProlog Java Bridge)

All Known Implementing Classes:

AbstractNativeEngine, AbstractPrologEngine, FloraSubprocessEngine, GNUSubprocessEngine, LPSEngine, NativeEngine, RemoteXSBSubprocessEngine, SubprocessEngine, SWISubprocessEngine, XSBSubprocessEngine, YAPSubprocessEngine
```
public interface PrologEngine
```
The heart of InterProlog; a PrologEngine represents a Prolog machine instance.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`MAX_INT_VALUE` Maximum integer value in any supported Prolog.
`static int`	`MIN_INT_VALUE` Minimum integer value.
`static String`	`version` InterProlog version

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`command(String s)` Execute a Prolog "command".
`boolean`	`consultAbsolute(File f)` Consults a Prolog file
`String`	`consultFromPackage(String filename, Object requester)` Extracts a Prolog file from the jar file or directory where the requester's class came from, and asks Prolog process to reconsult it.
`String`	`consultFromPackage(String filename, Object requester, boolean firstTimeOnly)` Subsequent calls will be ignored
`String`	`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.
`TermModel`	`deterministicGoal(TermModel G)` Useful for inter-Prolog goal calling through Java.
`PrologImplementationPeer`	`getImplementationPeer()`
`String`	`getPrologBaseDirectory()` Returns the installation directory for the Prolog system, without the trailing separator char
`String`	`getPrologVersion()` Returns the Prolog system version for this engine
`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).
`SolutionIterator`	`goal(String G, String RVars)`
`SolutionIterator`	`goal(String G, String OVar, Object[] objectsP, String RVars)` Similar to deterministicGoal, but rather than just the first solution returns an Iterator which lazily returns bindings for solutions.
`boolean`	`inPrologShell()`
`void`	`interrupt()` Interrupt Prolog and make it return to its top level.
`boolean`	`isAvailable()` Returns a boolean value indicating whether the engine is available (that is, ready to accept requests).
`boolean`	`isDebug()` Debug messages are being written, both Java and Prolog side, cf.
`boolean`	`isIdle()` This method returns true if this engine is idle (doing nothing: no pending Prolog goals nor Java callbacks), false otherwise.
`boolean`	`lastSolutionUndefined()`
`boolean`	`load_dynAbsolute(File f)`
`String`	`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.
`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)` Show (or hide) debug messages, both Java and Prolog side, cf.
`void`	`setThreadedCallbacks(boolean yes)` If true, the Java execution of javaMessage predicates will happen in new threads (default); if false, execution will be under the thread of the deterministicGoal currently executing in Prolog
`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.
`String`	`unescapedFilePath(String p)`
`boolean`	`unregisterJavaObject(int ID)` Removes reference to the object from the registry.
`boolean`	`unregisterJavaObject(Object obj)` Removes reference to the object from the registry.
`boolean`	`unregisterJavaObjects(Class<?> cls)` Removes references to objects of class `cls` from the registry.
`void`	`waitUntilAvailable()` This method blocks until `isAvailable()` returns true.
`void`	`waitUntilIdle()` This method blocks until `isIdle()` returns true.

- Field Detail
  - version
```
static final String version
```
    InterProlog version
    
    See Also:
    
    Constant Field Values
  - MAX_INT_VALUE
```
static final int MAX_INT_VALUE
```
    Maximum integer value in any supported Prolog. XSB Prolog uses 28 bits. Unfortunately, it is pointless to intercept writeInt in ObjectOutputStream, because
    1. the method is invoked in several situations, not just to serialize int values, and
    2. some classes may serialize in very weird ways
    so in general it is not possible to detect int values beyond these boundaries
    See Also:
    
    Constant Field Values
  - MIN_INT_VALUE
```
static final int MIN_INT_VALUE
```
    Minimum integer value.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getPrologVersion
```
String getPrologVersion()
```
    Returns the Prolog system version for this engine
  - shutdown
```
void shutdown()
```
    Release Prolog engine resources, making it unusable
  - consultFromPackage
```
String consultFromPackage(String filename,
                          Object requester)
```
    Extracts a Prolog file from the jar file or directory where the requester's class came from, and asks Prolog process to reconsult it. You should use this method only after your program is stable. The Prolog file is extracted into a temporary file, that is automatically deleted on exiting the application.
    
    Parameters:
    
    filename - The Prolog file name, including extension; if it has no extension, the Prolog file extensions are appended in turn until a file is found
    
    requester - Defines where the Prolog file resides
    
    See Also:
    
    consultRelative(String, Object), load_dynRelative(String, Object)
  - consultFromPackage
```
String consultFromPackage(String filename,
                          Object requester,
                          boolean firstTimeOnly)
```
    Subsequent calls will be ignored
  - interrupt
```
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
```
boolean command(String s)
```
    Execute a Prolog "command". This is the simplest way to call a Prolog goal, but it's also the less reliable under error conditions; unless you have a good reason for using it, use deterministicGoal(String) instead. @see #deterministicGoal(String)
  - isDebug
```
boolean isDebug()
```
    Debug messages are being written, both Java and Prolog side, cf. ipIsDebugging/0
  - setDebug
```
void setDebug(boolean d)
```
    Show (or hide) debug messages, both Java and Prolog side, cf. ipIsDebugging/0. Beware that this may try to assert/retract a flag (ipIsDebugging/0) on the Prolog side, be sure to invoke this method sooner rather than later as it may get "stuck" if there are problems communicating with the Prolog engine
  - deterministicGoal
```
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
```
boolean deterministicGoal(String G)
```
    A parameterless goal with no result other than success/failure. Same as deterministicGoal(G, null,null,"[]")
  - deterministicGoal
```
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
```
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,"[]")
  - deterministicGoal
```
TermModel deterministicGoal(TermModel G)
```
    Useful for inter-Prolog goal calling through Java. For example, to call a goal G in another PrologEngine E:
```
    buildTermModel(G,GM),
    javaMessage(E,SM,deterministicGoal(GM)),
    recoverTermModel(SM,Solution)
   
```
  - goal
```
SolutionIterator goal(String G,
                      String OVar,
                      Object[] objectsP,
                      String RVars)
```
    Similar to deterministicGoal, but rather than just the first solution returns an Iterator which lazily returns bindings for solutions. This method returns immediately, because the actual Prolog execution will happen during the messages sent to the iterator. If G fails, the Iterator will have no elements.
  - goal
```
SolutionIterator goal(String G,
                      String RVars)
```
  - lastSolutionUndefined
```
boolean lastSolutionUndefined()
```
  - registerJavaObject
```
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
    
    Returns:
    
    Integer denoting the object. In Prolog one can then refer to it by using the InvisibleObject class.
    
    See Also:
    
    InvisibleObject
  - makeInvisible
```
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
    
    Returns:
    
    InvisibleObject denoting the object. In Prolog one can then refer to it by using the InvisibleObject class.
    
    See Also:
    
    InvisibleObject
  - getRealJavaObject
```
Object getRealJavaObject(InvisibleObject o)
```
    Get the object referred by the integer in a InvisibleObject wrapper.
    
    Parameters:
    
    o - An InvisibleObject
    
    Returns:
    
    The real object denoted by o in the context of this engine
    
    See Also:
    
    InvisibleObject
  - getRealJavaObject
```
Object getRealJavaObject(int ID)
```
    Same as getRealJavaObject(InvisibleObject), but accepts an integer ID as argument instead
  - getRealJavaObject
```
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
  - unregisterJavaObject
```
boolean unregisterJavaObject(int ID)
```
    Removes reference to the object from the registry. This method should be used with extreme caution since any further prolog calls to the object by means of reference to it in the registry might result in unpredictable behaviour.
  - unregisterJavaObject
```
boolean unregisterJavaObject(Object obj)
```
    Removes reference to the object from the registry. This method should be used with extreme caution since any further prolog calls to the object by means of reference to it in the registry might result in unpredictable behaviour.
  - unregisterJavaObjects
```
boolean unregisterJavaObjects(Class<?> cls)
```
    Removes references to objects of class cls from the registry. This method should be used with extreme caution since any further prolog calls to the unregistered objects by means of reference to them in the registry might result in unpredictable behaviour.
  - isAvailable
```
boolean isAvailable()
```
    Returns a boolean value indicating whether the engine is available (that is, ready to accept requests).
  - waitUntilAvailable
```
void waitUntilAvailable()
```
    This method blocks until isAvailable() returns true.
  - isIdle
```
boolean isIdle()
```
    This method returns true if this engine is idle (doing nothing: no pending Prolog goals nor Java callbacks), false otherwise.
  - waitUntilIdle
```
void waitUntilIdle()
```
    This method blocks until isIdle() returns true.
  - teachOneObject
```
boolean teachOneObject(Object example)
```
    Same as #teachMoreObjects(ObjectExamplePair[]), but the single example pair is constructed repeating the object.
    
    See Also:
    
    teachMoreObjects(ObjectExamplePair[])
  - teachMoreObjects
```
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
```
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
  - consultAbsolute
```
boolean consultAbsolute(File f)
```
    Consults a Prolog file
  - load_dynAbsolute
```
boolean load_dynAbsolute(File f)
```
  - consultRelative
```
String 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 a path it should use '/' as the separator, independently of the OS
    
    requester - Defines where the Prolog file resides
  - load_dynRelative
```
String load_dynRelative(String filename,
                        Object requester)
```
  - getImplementationPeer
```
PrologImplementationPeer getImplementationPeer()
```
  - getPrologBaseDirectory
```
String getPrologBaseDirectory()
```
    Returns the installation directory for the Prolog system, without the trailing separator char
  - setThreadedCallbacks
```
void setThreadedCallbacks(boolean yes)
```
    If true, the Java execution of javaMessage predicates will happen in new threads (default); if false, execution will be under the thread of the deterministicGoal currently executing in Prolog
  - inPrologShell
```
boolean inPrologShell()
```
  - unescapedFilePath
```
String unescapedFilePath(String p)
```

Interface PrologEngine

Field Summary

Method Summary

Field Detail

version

MAX_INT_VALUE

MIN_INT_VALUE

Method Detail

getPrologVersion

shutdown

consultFromPackage

consultFromPackage

interrupt

command

isDebug

setDebug

deterministicGoal

deterministicGoal

deterministicGoal

deterministicGoal

deterministicGoal

goal

goal

lastSolutionUndefined

registerJavaObject

makeInvisible

getRealJavaObject

getRealJavaObject

getRealJavaObject

unregisterJavaObject

unregisterJavaObject

unregisterJavaObjects

isAvailable

waitUntilAvailable

isIdle

waitUntilIdle

teachOneObject

teachMoreObjects

teachMoreObjects

consultAbsolute

load_dynAbsolute

consultRelative

load_dynRelative

getImplementationPeer

getPrologBaseDirectory

setThreadedCallbacks

inPrologShell

unescapedFilePath