ubc.cs.JLog.Foundation
Class jPrologAPI

java.lang.Object
  extended by ubc.cs.JLog.Foundation.jPrologAPI

public class jPrologAPI
extends java.lang.Object

This class is encapsulates the Prolog Engine into a single, simple class, suitable for programmatic access.

Author:
Glendon Holst

Nested Class Summary
protected  class jPrologAPI.KeyPairs
           
 
Field Summary
protected  jPrologServices prolog
           
protected  int query_state
           
protected static int QUERY_STATE_FINISHED
           
protected static int QUERY_STATE_SUCCEEDED
           
protected static int QUERY_STATE_WAITING
           
protected  jAPIQueryThread thread
           
protected  jTermTranslation translations
           
protected  java.util.Hashtable var_translation_keys
           
 
Constructor Summary
jPrologAPI(java.io.InputStream source)
          Basic constructor instantiates a bare-bones Prolog engine, and consults the given source input stream.
jPrologAPI(java.io.InputStream source, iPrologFileServices fs, java.io.PrintWriter output, java.io.BufferedReader input, java.lang.Object ae)
          Complete constructor instantiates a bare-bones Prolog engine, sets the external services to those provided, and consults the given source input stream.
jPrologAPI(java.lang.String source)
          Basic constructor instantiates a bare-bones Prolog engine, and consults the given source string.
jPrologAPI(java.lang.String source, iPrologFileServices fs, java.io.PrintWriter output, java.io.BufferedReader input, java.lang.Object ae)
          Complete constructor instantiates a bare-bones Prolog engine, sets the external services to those provided, and consults the given source string.
 
Method Summary
 void consultSource(java.lang.String source)
          Consult a source string.
 boolean getFailUnknownPredicate()
          Get the behaviour for unknown predicates.
 java.lang.String getRequiredCreditInfo()
          This function returns the credit assignment and copyright informaiton string.
 jTermTranslation getTranslation()
          Get the current translation unit used to convert queries and results between Prolog terms and Java objects.
protected  void initConsultSource(java.lang.String source)
           
protected  void initPrologListeners()
           
protected  void initTranslation()
           
protected  void joinForcedQueryCompletion()
           
 java.util.Hashtable query(java.lang.String query)
          Initiates a query.
 java.util.Hashtable query(java.lang.String query, java.util.Hashtable bindings)
          Initiates a query, pre-binding variables based on the key:value pairs in the given hashtable.
 java.util.Hashtable queryOnce(java.lang.String query)
          Initiates a query, and stops the query after the first result.
 java.util.Hashtable queryOnce(java.lang.String query, java.util.Hashtable bindings)
          Initiates a query, pre-binding variables based on the key:value pairs in the given hashtable, but stops the query after the first result.
 java.util.Hashtable retry()
          Retries the previous query.
 void setFailUnknownPredicate(boolean fp)
          Set the behaviour for unknown predicates.
protected  void setQueryResultState(boolean result)
           
 void setTranslation(jTermTranslation tt)
          Sets the translation unit used to convert queries and results between Prolog terms and Java objects.
 void setVariableTranslationKeys(java.lang.String v, java.lang.Object tkey, java.lang.Object okey)
          Associates a variable with translation keys.
 void stop()
           
protected  java.util.Hashtable waitForCompletion()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

QUERY_STATE_WAITING

protected static final int QUERY_STATE_WAITING
See Also:
Constant Field Values

QUERY_STATE_SUCCEEDED

protected static final int QUERY_STATE_SUCCEEDED
See Also:
Constant Field Values

QUERY_STATE_FINISHED

protected static final int QUERY_STATE_FINISHED
See Also:
Constant Field Values

prolog

protected jPrologServices prolog

thread

protected jAPIQueryThread thread

var_translation_keys

protected java.util.Hashtable var_translation_keys

translations

protected jTermTranslation translations

query_state

protected int query_state
Constructor Detail

jPrologAPI

public jPrologAPI(java.lang.String source)
Basic constructor instantiates a bare-bones Prolog engine, and consults the given source string. All the external facilities, except for file services, that the Prolog engine may require are null. This is fine for basic Prolog KBs which do not use output (e.g., write/1, writeln/1, nl/0), do not use input (e.g., read/1), and do not use the animation environment (e.g., animate/2). A jPrologFileServices instance provides the file services.

Parameters:
source - The source string to consult (i.e., the initial KB).

jPrologAPI

public jPrologAPI(java.io.InputStream source)
           throws java.io.IOException
Basic constructor instantiates a bare-bones Prolog engine, and consults the given source input stream. All the external facilities, except for file services, that the Prolog engine may require are null. This is fine for basic Prolog KBs which do not use output (e.g., write/1, writeln/1, nl/0), do not use input (e.g., read/1), and do not use the animation environment (e.g., animate/2). A jPrologFileServices instance provides the file services.

Parameters:
source - The source input stream to consult (i.e., the initial KB).
Throws:
java.io.IOException

jPrologAPI

public jPrologAPI(java.lang.String source,
                  iPrologFileServices fs,
                  java.io.PrintWriter output,
                  java.io.BufferedReader input,
                  java.lang.Object ae)
Complete constructor instantiates a bare-bones Prolog engine, sets the external services to those provided, and consults the given source string. If any external facilities are null, then the Prolog source should not use any predicates which require those facilities.

Parameters:
source - The source string to consult (i.e., the initial KB).
fs - External file services facilities (e.g., used for load_library/1 etc.) If null, an instance of jPrologFileServices is used by default.
output - External text ouput facilities (e.g., used for writeln/1 etc.)
input - External text input facilities (e.g., used for read/1 etc.)
ae - External animation display facilities (e.g., used for animation/2 etc.) Must be of type aAnimationEnvironment, else an exception will be thrown when proving animation/2.

jPrologAPI

public jPrologAPI(java.io.InputStream source,
                  iPrologFileServices fs,
                  java.io.PrintWriter output,
                  java.io.BufferedReader input,
                  java.lang.Object ae)
           throws java.io.IOException
Complete constructor instantiates a bare-bones Prolog engine, sets the external services to those provided, and consults the given source input stream. If any external facilities are null, then the Prolog source should not use any predicates which require those facilities.

Parameters:
source - The source input stream to consult (i.e., the initial KB).
fs - External file services facilities (e.g., used for load_library/1 etc.) If null, an instance of jPrologFileServices is used by default.
output - External text ouput facilities (e.g., used for writeln/1 etc.)
input - External text input facilities (e.g., used for read/1 etc.)
ae - External animation display facilities (e.g., used for animation/2 etc.) Must be of type aAnimationEnvironment, else an exception will be thrown when proving animation/2.
Throws:
java.io.IOException
Method Detail

initTranslation

protected void initTranslation()

initPrologListeners

protected void initPrologListeners()

initConsultSource

protected void initConsultSource(java.lang.String source)

getRequiredCreditInfo

public java.lang.String getRequiredCreditInfo()
This function returns the credit assignment and copyright informaiton string. It must be preserved by authors of derivative works. If the derivative work displays credit information, use this method to get the JLog specific information.

Returns:
The credit and information string.

setFailUnknownPredicate

public void setFailUnknownPredicate(boolean fp)
Set the behaviour for unknown predicates. By default the behaviour is that missing predicates throw an exception.

Parameters:
fp - If fail (default) then missing predicates generate a failing exception (i.e., exception thrown), if false then the query for that predicate fails (i.e., no exception is thrown).

getFailUnknownPredicate

public boolean getFailUnknownPredicate()
Get the behaviour for unknown predicates.

Returns:
If false, then exceptions are thrown for missing predicates, otherwise the query for that predicate fails (no exception thrown).

setVariableTranslationKeys

public void setVariableTranslationKeys(java.lang.String v,
                                       java.lang.Object tkey,
                                       java.lang.Object okey)
Associates a variable with translation keys. When the variable binding hashtable is passed to the query method, the default behaviour is to translate the bound values according to their type, but if a special translation is preferred, then the key value is used to determine the mapping. These keys are used to find the preferred iObjectToTerm or iTermToObject conversion in the TermTranslation object, .

Parameters:
v - The name of the variable.
tkey - The translation lookup key to use for translating the value bound to this variable to a prolog term. Set to null to use the default translation.
okey - The translation lookup key to use for translating the value bound to this variable back to a Java object. Set to null for the default translation.

getTranslation

public jTermTranslation getTranslation()
Get the current translation unit used to convert queries and results between Prolog terms and Java objects. Modifying the conversion units associated with the returned translation object will affect how the API processes query input and results.

Returns:
The jTermTranslation object used for translating between objects and terms.

setTranslation

public void setTranslation(jTermTranslation tt)
Sets the translation unit used to convert queries and results between Prolog terms and Java objects.

Parameters:
tt - The jTermTranslation object to use for translating between objects and terms.

consultSource

public void consultSource(java.lang.String source)
Consult a source string.

Parameters:
source - The KB source string to consult.

query

public java.util.Hashtable query(java.lang.String query)
Initiates a query.

Parameters:
query - The query string (must be non-empty).
Returns:
Returns a hashtable with all the variables in the query, and their bindings. Each key in the hashtable is a named variable, and the object type of the associated value is translated using the jTermTranslation object associated with this API object (to translate from Object to jTerm). Returns null if the query fails.

queryOnce

public java.util.Hashtable queryOnce(java.lang.String query)
Initiates a query, and stops the query after the first result.

Parameters:
query - The query string (must be non-empty).
Returns:
Returns a hashtable with all the variables in the query, just as the query method does. Returns null if the query fails.

query

public java.util.Hashtable query(java.lang.String query,
                                 java.util.Hashtable bindings)
Initiates a query, pre-binding variables based on the key:value pairs in the given hashtable. For each entry (Var:Value) in values, a variable named Var is created and the variable instance is bound to the translated jTerm of Value. See jTermTranslation for more information about how translation between Java objects and Prolog terms is performed. By default, the jPrologAPI class uses the default translation, but the user may set the preferred jTermTranslation object.

Parameters:
query - The query string (must be non-empty).
bindings - A hashtable mapping variable names (key) to their values (value). If null, then performs the same as query(String) above.
Returns:
Returns a hashtable of variable bindings (just like query(String) above). The values are translated using the translation object associated with this API object (to translate from jTerm to Object). Returns null if the query fails.

queryOnce

public java.util.Hashtable queryOnce(java.lang.String query,
                                     java.util.Hashtable bindings)
Initiates a query, pre-binding variables based on the key:value pairs in the given hashtable, but stops the query after the first result.

Parameters:
query - The query string (must be non-empty).
bindings - A hashtable mapping variable names (key) to their values (value). Just as the corresponding query method.
Returns:
Returns a hashtable of variable bindings (just like query method above. Returns null if the query fails.

retry

public java.util.Hashtable retry()
Retries the previous query.

Returns:
Returns a hashtable of variable bindings (just like query(String) above). Returns null if the query retry fails.

stop

public void stop()

waitForCompletion

protected java.util.Hashtable waitForCompletion()

setQueryResultState

protected void setQueryResultState(boolean result)

joinForcedQueryCompletion

protected void joinForcedQueryCompletion()