Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.declarativa.interprolog
Interface PrologEngine

All Known Implementing Classes:
  AbstractPrologEngine

public interface PrologEngine

The heart of InterProlog; a PrologEngine represents a Prolog machine instance.

Field Summary
`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
`boolean` | `command(String s)` Execute a Prolog "command".
`boolean` | `consultAbsolute(File f)` Consults a Prolog file
`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 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.
`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).
`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. ipIsDebugging/0
`boolean` | `isIdle()` This method returns true if this engine is idle (doing nothing: no pending Prolog goals nor Java callbacks), false otherwise.
`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.
`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. ipIsDebugging/0.
`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.
`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

    public static final String version

  InterProlog version

  See Also:
    Constant Field Values

### MAX_INT_VALUE

    public 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

    public static final int MIN_INT_VALUE

  Minimum integer value.

  See Also:
    Constant Field Values

Method Detail

### getPrologVersion

    public String getPrologVersion()

  Returns the Prolog system version for this engine

### shutdown

    public void shutdown()

  Release Prolog engine resources, making it unusable

### 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 Prolog process to consult 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)`

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

    public boolean isDebug()

  Debug messages are being written, both Java and Prolog side, cf. ipIsDebugging/0

### setDebug

    public 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

    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,"[]")

### deterministicGoal

    public 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)

### 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
  Returns:
    Integer denoting the object. In Prolog one can then refer to it by using the InvisibleObject class.
  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
  Returns:
    InvisibleObject denoting the object. In Prolog one can then refer to it by using the InvisibleObject class.
  See Also:
    `InvisibleObject`

### getRealJavaObject

    public 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

    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

### unregisterJavaObject

    public 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

    public 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

    public 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

    public boolean isAvailable()

  Returns a boolean value indicating whether the engine is available (that is, ready to accept requests).

### waitUntilAvailable

    public void waitUntilAvailable()

  This method blocks until `isAvailable()` returns true.

### isIdle

    public boolean isIdle()

  This method returns true if this engine is idle (doing nothing: no pending Prolog goals nor Java callbacks), false otherwise.

### waitUntilIdle

    public void waitUntilIdle()

  This method blocks until `isIdle()` returns true.

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

### consultAbsolute

    public boolean consultAbsolute(File f)

  Consults a Prolog file

### 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 a path it should use '/' as the separator, independently of the OS
    `requester` - Defines where the Prolog file resides

### load_dynRelative

    public void load_dynRelative(String filename,
                                 Object requester)

### getImplementationPeer

    public PrologImplementationPeer getImplementationPeer()

### getPrologBaseDirectory

    public String getPrologBaseDirectory()

  Returns the installation directory for the Prolog system, without the trailing separator char

### setThreadedCallbacks

    public 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD