com.ugos.jiprolog.engine

Class JIPEngine

java.lang.Object

com.ugos.jiprolog.engine.JIPEngine

All Implemented Interfaces:

Serializable

public class JIPEngine
extends Object
implements Serializable

JIPEngine implements the JIProlog interpeter.
See the section "How to call JIProlog interpreter from Java" in the Reference Manual.

Version:

3.2

Author:

Ugo Chirico
Home Page: http://www.ugochirico.com

See Also:

JIPQuery, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	build
static int	major
static int	minor
static int	revision

Constructor Summary

Constructors

Constructor and Description
JIPEngine() Constructs a new instance of JIPEngine with default values search path, input and output stream.

Method Summary

Methods

Modifier and Type	Method and Description
void	abolish(JIPTerm term) It is equivalent to abolish/1 predicate.
void	addEventListener(JIPEventListener listener) Adds the specified JIPEventListener object
void	addTraceListener(JIPTraceListener traceListener) Adds the specified JIPTraceListener object
void	asserta(JIPTerm term) It is equivalent to asserta/1 predicate.
void	assertz(JIPTerm term) It is equivalent to assert/1 predicate.
void	closeAllQueries() Closes all pending queries
void	closeQuery(int nQueryHandle) Closes a query.
void	compileFile(String strFileName) Compile the specified file.
void	consultFile(String strFileName) Consults a file.
void	consultStream(InputStream ins, String strStreamName) Consults a Stream.
protected void	finalize() Releases the resources used by JIProlog Developers should not call it directly.
static String	getCopyrightInfo() Returns Copyright
InputStream	getCurrentInputStream() Gets current InputStream
String	getCurrentInputStreamName() Gets current InputStream Name
OutputStream	getCurrentOutputStream() Gets current OutputStream
String	getCurrentOutputStreamName() Gets current OutputStream Name
boolean	getDebug() gets debug flag.
String	getEncoding() Gets current encoding
Object	getEnvVariable(String varName) Gets the value of a custom environment variable.
Enumeration<String>	getEnvVariableNames() Gets the enumeration of all custom environment variable name.
Vector	getEventListeners() Gets the list of JIPEventListeners
boolean	getImmediateUpdateSemantics() Gets the update semantics
static String	getInfo() Returns JIProlog info
static String	getLicenseInfo() Returns JIProlog license info
String	getSearchPath() returns the search path of this instance of JIPEngine.
JIPTermParser	getTermParser() Returns the instance of JIPTermParser attached to this JIPEngine object Use JIPTermParser to parse prolog terms
boolean	getTrace() Returns the trace flag.
Vector	getTraceListeners() Gets the list of JIPTraceListener
InputStream	getUserInputStream() Gets user InputStream
OutputStream	getUserOutputStream() Gets user OutputStream
static String	getVersion() Returns the JIProlog version
boolean	hasMoreChoicePoints(int nQueryHandle) Returns true if the query has more choice points on backtracking.
boolean	isInternal(JIPFunctor funct) Returns true if the given functor is an internal predicate.
boolean	isInternal(String strName) Returns true if the given functor is an internal predicate.
boolean	isSystem(JIPFunctor funct) Returns true if the given functor is a system predicate.
boolean	isSystem(String strName) Returns true if the given functor is a system predicate.
void	loadFile(String strFileName) Loads a file.
void	loadLibrary(String strPath) Load an extensions library.
void	loadStream(InputStream ins, String strStreamName) Loads a stream.
void	nextSolution(int nQueryHandle) Searches for another soution.
void	notifyEvent(int nID, JIPTerm term, int nQueryHandle) Notifies a JIPEvent.
int	openQuery(JIPTerm jipquery) Opens a query.
int	openQuery(String strQuery) Opens a query.
JIPQuery	openSynchronousQuery(JIPTerm jipquery) Returns a reference to a synchronous query.
JIPQuery	openSynchronousQuery(String strQuery) Returns a reference to a synchronous query.
void	releaseAllResources() Closes all pending queries and release all threads and resources.
Object	removeEnvVariable(String varName) Removes a custom environment variable.
void	removeEventListener(JIPEventListener listener) Removes the specified JIPEventListener object
void	removeTraceListener(JIPTraceListener traceListener) Removes the specified JIPTraceListener object
void	reset() Closes all pending queries, reset the prolog interpreter and clear the database
boolean	retract(JIPTerm term) It is equivalent to retract/1 predicate.
void	setCurrentInputStream(InputStream ins, String strStreamName) Sets current InputStream
void	setCurrentOutputStream(OutputStream outs, String strStreamName) Sets current OutputStream
void	setDebug(boolean debug) Sets debug flag.
void	setEncoding(String encoding) Sets current encoding
void	setEnvVariable(String varName, Object value) Sets the value of a custom environment variable.
void	setImmediateUpdateSemantics(boolean immediate) Sets the update semantics ISO Prolog specifies that a prolog system should implement 'logical update semantics' on the internal database.
void	setSearchPath(String strSearchPath) Sets the search path of this instance of JIPEngine.
void	setTrace(boolean bTrace) Sets the trace flag.
void	setUserInputStream(InputStream ins) Sets user InputStream
void	setUserOutputStream(OutputStream outs) Sets user OutputStream
void	unconsultFile(String strFileName) Unconsults/unloads a file.
void	unconsultStream(String strStreamName) Unconsults/unloads a stream.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

major

public static final int major

See Also:

Constant Field Values

minor

public static final int minor

See Also:

Constant Field Values

build

public static final int build

See Also:

Constant Field Values

revision

public static final int revision

See Also:

Constant Field Values

Constructor Detail

JIPEngine

public JIPEngine()

Constructs a new instance of JIPEngine with default values search path, input and output stream. Search path is the path where this instance of JIPEngine searches for files. The default value is the value of the environment variable user.dir
Input and Output stream are the streams where this instance of JIPEngine reads and writes. The default values are respectively System.in and System.out.

Method Detail

getVersion

public static final String getVersion()

Returns the JIProlog version

getInfo

public static final String getInfo()

Returns JIProlog info

getCopyrightInfo

public static final String getCopyrightInfo()

Returns Copyright

getLicenseInfo

public static final String getLicenseInfo()

Returns JIProlog license info

setImmediateUpdateSemantics

public void setImmediateUpdateSemantics(boolean immediate)

Sets the update semantics ISO Prolog specifies that a prolog system should implement 'logical update semantics' on the internal database. The ISO standard imposes a static state of the database at and during the time of a query/goal. By 'static' it means that new clauses/entries to the database are not visible in back-tracking. The following example illustrates the difference between the two semantics: :- dynamic a/1. JIP:- assert(a(1)). JIP:- retract(a(X)), X1 is X + 1, assertz(a(X)). With 'immediate update semantics', the first calls to retract/1 and assertz/1 will succeed. On back-tracking, the system will retry retract/1 and the newly asserted goal, which is visible to retract/1, can be retracted from the database. (This example will continue generating integers forever.) On back-tracking with 'logical update semantics' the call to retract/1 will not see the update performed by the assertz/1 and the query will have a single solution.

Parameters:

immediate - true - immediate update semantics, false - logical update semantics (default)

getImmediateUpdateSemantics

public boolean getImmediateUpdateSemantics()

Gets the update semantics

Returns:

true if immediate update semantics, false if logical update semantics (default)

setDebug

public void setDebug(boolean debug)

Sets debug flag.

getDebug

public boolean getDebug()

gets debug flag.

isSystem

public final boolean isSystem(String strName)

Returns true if the given functor is a system predicate.

isSystem

public final boolean isSystem(JIPFunctor funct)

Returns true if the given functor is a system predicate.

isInternal

public final boolean isInternal(String strName)

Returns true if the given functor is an internal predicate.

isInternal

public final boolean isInternal(JIPFunctor funct)

Returns true if the given functor is an internal predicate.

loadLibrary

public final void loadLibrary(String strPath)
                       throws IOException

Load an extensions library.
The library should be a valid .jar file containing a set of extension classes.
If in the .jar there is a file named init.pl it is consulted as any other prolog file. For more information see the section "Load an extension library" in the Reference Manual.

Throws:

IOException

addEventListener

public void addEventListener(JIPEventListener listener)

Adds the specified JIPEventListener object

Parameters:

listener - JIPEventListener object to add

See Also:

JIPEventListener

removeEventListener

public void removeEventListener(JIPEventListener listener)

Removes the specified JIPEventListener object

Parameters:

listener - JIPEventListener object to remove

See Also:

JIPEventListener

getEventListeners

public Vector getEventListeners()

Gets the list of JIPEventListeners

Returns:

Vector containing the registered JIPEventListener objects

See Also:

JIPEventListener

addTraceListener

public void addTraceListener(JIPTraceListener traceListener)

Adds the specified JIPTraceListener object

Parameters:

traceListener - JIPTraceListener object to add

See Also:

JIPTraceListener

removeTraceListener

public void removeTraceListener(JIPTraceListener traceListener)

Removes the specified JIPTraceListener object

Parameters:

traceListener - JIPTraceListener object to remove

See Also:

JIPTraceListener

getTraceListeners

public Vector getTraceListeners()

Gets the list of JIPTraceListener

Returns:

Vector of listeners

See Also:

JIPTraceListener

setSearchPath

public final void setSearchPath(String strSearchPath)
                         throws IOException

Sets the search path of this instance of JIPEngine. The Search path is the path where this instance of JIPEngine searches for files.
It can refer to:
- a directory on hard disk (d:\myapp, file:/user/myapp)
- an URL (http://www.mysite.com)
- a jar file (jar://user/myprologfile.jar)

Parameters:

strSearchPath - Search path

Throws:

IOException

See Also:

getSearchPath()

getSearchPath

public final String getSearchPath()

returns the search path of this instance of JIPEngine. The Search path is the path where this instance of JIPEngine searches for files.

Returns:

the search path of this JIPEngine object.

See Also:

setSearchPath(java.lang.String)

setTrace

public final void setTrace(boolean bTrace)

Sets the trace flag. If the flag is set all JIPTraceListeners are notified during execution.

Parameters:

bTrace - Trace flag

See Also:

getTrace()

getTrace

public final boolean getTrace()

Returns the trace flag.

See Also:

setTrace(boolean)

setUserOutputStream

public final void setUserOutputStream(OutputStream outs)

Sets user OutputStream

Parameters:

outs - the user output stream to set.

See Also:

getUserOutputStream()

getUserOutputStream

public final OutputStream getUserOutputStream()

Gets user OutputStream

Returns:

The user output stream.

See Also:

setUserOutputStream(java.io.OutputStream)

setUserInputStream

public final void setUserInputStream(InputStream ins)

Sets user InputStream

Parameters:

ins - the user input stream to set

See Also:

getUserInputStream()

getUserInputStream

public final InputStream getUserInputStream()

Gets user InputStream

Returns:

The user input stream

See Also:

setUserInputStream(java.io.InputStream)

getCurrentOutputStream

public final OutputStream getCurrentOutputStream()

Gets current OutputStream

Returns:

The current output stream

See Also:

setCurrentOutputStream(java.io.OutputStream, java.lang.String)

setCurrentOutputStream

public final void setCurrentOutputStream(OutputStream outs,
                          String strStreamName)

Sets current OutputStream

Parameters:

outs - the current output stream to set

See Also:

getUserOutputStream()

setCurrentInputStream

public final void setCurrentInputStream(InputStream ins,
                         String strStreamName)

Sets current InputStream

Parameters:

ins - the current input stream to set

strStreamName - the name of the input stream

See Also:

getUserInputStream()

getCurrentInputStream

public final InputStream getCurrentInputStream()

Gets current InputStream

Returns:

The current input stream

See Also:

setCurrentInputStream(java.io.InputStream, java.lang.String)

getCurrentInputStreamName

public final String getCurrentInputStreamName()

Gets current InputStream Name

Returns:

The current input stream name.

getCurrentOutputStreamName

public final String getCurrentOutputStreamName()

Gets current OutputStream Name

Returns:

The current output stream name.

getEncoding

public final String getEncoding()

Gets current encoding

Returns:

The current encoding.

setEncoding

public final void setEncoding(String encoding)

Sets current encoding

Parameters:

encoding - the encoding

reset

public void reset()

Closes all pending queries, reset the prolog interpreter and clear the database

releaseAllResources

public void releaseAllResources()

Closes all pending queries and release all threads and resources.

consultFile

public final void consultFile(String strFileName)
                       throws JIPSyntaxErrorException,
                              IOException

Consults a file. If in the file there are some no multifile predicates already consulted/loaded in another file file/stream the interpreter raises an exception.

Parameters:

strFileName - the name of the file to consult. It can refer to:
- a file on hard disk (d:\myapp/myfile.pl, file:/user/myapp/myfile.pl)
- an URL (http://www.mysite.com/myfile.pl)
- a file contained in a jar file (jar://user/myprologfile.jar#myfile.pl)
- a path relative to the search path.

Throws:

com.ugos.jiprolog.engine.JIPSyntaxErrorException, - java.io.IOException

JIPSyntaxErrorException

IOException

See Also:

loadFile(java.lang.String), setSearchPath(java.lang.String)

consultStream

public final void consultStream(InputStream ins,
                 String strStreamName)
                         throws JIPSyntaxErrorException

Consults a Stream. If in the stream there are some no multifile predicates already consulted/loaded in another file/stream the interpreter raises an exception.

Parameters:

ins - is the stream to consult

strStreamName - is the symbolic name of the stream

Throws:

com.ugos.jiprolog.engine.JIPSyntaxErrorException, - java.io.IOException

JIPSyntaxErrorException

See Also:

loadStream(java.io.InputStream, java.lang.String), setSearchPath(java.lang.String)

unconsultFile

public final void unconsultFile(String strFileName)

Unconsults/unloads a file. Deletes from the prolog database all clauses previously consulted or loaded with to the specified file. Note: If in the file consulted/loaded there was nested consult/load the predicates defined in the other files are not deleted.

Parameters:

strFileName - the name of the file to unconsult.

See Also:

loadFile(java.lang.String), consultFile(java.lang.String)

unconsultStream

public final void unconsultStream(String strStreamName)

Unconsults/unloads a stream. Deletes from the prolog database all clauses previously consulted or loaded with to the specified stream. Note: If in the file consulted/loaded there was nested consult/load the predicates defined in the other files are not deleted.

Parameters:

strStreamName - the name of the stream to unconsult.

See Also:

loadStream(java.io.InputStream, java.lang.String), consultStream(java.io.InputStream, java.lang.String)

compileFile

public final void compileFile(String strFileName)
                       throws JIPSyntaxErrorException

Compile the specified file. As result a file with .cpl extension is produced

Parameters:

strFileName - the name of the file to compile. It can refer to:
- a file on hard disk (d:\myapp/myfile.pl, file:/user/myapp/myfile.pl)
- a path relative to the search path.

Throws:

com.ugos.jiprolog.engine.JIPSyntaxErrorException, - java.io.IOException

JIPSyntaxErrorException

See Also:

loadFile(java.lang.String), setSearchPath(java.lang.String)

loadFile

public final void loadFile(String strFileName)
                    throws IOException

Loads a file. The file must contain a valid JIProlog compiled code If in the file there are some no multifile predicates already consulted/loaded in another file the interpreter raises an exception.

Parameters:

strFileName - the name of the file to load. It can refer to:
- a file on hard disk (d:\myapp/myfile.pl, file:/user/myapp/myfile.pl)
- an URL (http://www.mysite.com/myfile.pl)
- a file contained in a jar file (jar://user/myprologfile.jar#myfile.pl)
- a path relative to the search path.

Throws:

IOException

See Also:

consultFile(java.lang.String), setSearchPath(java.lang.String)

loadStream

public final void loadStream(InputStream ins,
              String strStreamName)
                      throws IOException

Loads a stream. The stream must contain a valid JIProlog compiled code If in the stream there are some no multifile predicates already consulted/loaded in another file the interpreter raises an exception.

Parameters:

ins - the inpustream to load

strStreamName - the name of the file to load. It can refer to:
- a file on hard disk (d:\myapp/myfile.pl, file:/user/myapp/myfile.pl)
- an URL (http://www.mysite.com/myfile.pl)
- a file contained in a jar file (jar://user/myprologfile.jar#myfile.pl)
- a path relative to the search path.

Throws:

IOException

See Also:

loadFile(java.lang.String), setSearchPath(java.lang.String)

asserta

public final void asserta(JIPTerm term)

It is equivalent to asserta/1 predicate. Add a clause to the interpreter database at the beginning of the clauses associated to the given one.

Parameters:

term - the term to assert.

retract

public final boolean retract(JIPTerm term)

It is equivalent to retract/1 predicate. Retracts a fact or a clause that unifies with the given term from the interpreter database and, as side-effect, unifies the given term the the one retracted.

Parameters:

term - the term to retract.

assertz

public final void assertz(JIPTerm term)

It is equivalent to assert/1 predicate. Add a term to the interpreter database

Parameters:

term - the term to assert.

abolish

public final void abolish(JIPTerm term)

It is equivalent to abolish/1 predicate. abolish a term in the interpreter database

Parameters:

term - the term to abolish.

openSynchronousQuery

public JIPQuery openSynchronousQuery(String strQuery)
                              throws JIPSyntaxErrorException

Returns a reference to a synchronous query.

Parameters:

strQuery - Query as a text string

Returns:

an instantiated JIPQuery object

Throws:

JIPSyntaxErrorException

See Also:

JIPQuery, openQuery(String)

openSynchronousQuery

public JIPQuery openSynchronousQuery(JIPTerm jipquery)

Returns a reference to a synchronous query.

Parameters:

jipquery - Query to open

Returns:

an instantiated JIPQuery object

See Also:

JIPQuery, openQuery(JIPTerm)

openQuery

public int openQuery(String strQuery)
              throws JIPSyntaxErrorException

Opens a query.
The registered JIPEventListeners will be notified in the openNotified method.
When a solution is found the JIPEventListeners will be notified in solutionNotified.
If an error occurs the JIPEventListeners will be notified in errorNotified.

Parameters:

strQuery - Query as a text string

Returns:

The handle of the opened query

Throws:

JIPSyntaxErrorException

See Also:

nextSolution(int), closeQuery(int), JIPEventListener.openNotified(com.ugos.jiprolog.engine.JIPEvent)

openQuery

public int openQuery(JIPTerm jipquery)

Opens a query.
The registered JIPEventListeners will be notified in the openNotified method.
When an event occurs in the interpreter the registered JIPEventListeners will be notified in the corresponding notified method.
If an error occurs the registered JIPEventListeners will be notified in errorNotified.

Parameters:

jipquery - Query as a JIPTerm

Returns:

The handle of the opened query

See Also:

JIPTermParser.parseTerm(java.lang.String), nextSolution(int), closeQuery(int), JIPEventListener

nextSolution

public void nextSolution(int nQueryHandle)

Searches for another soution. The registered JIPEventListeners will be notified in the openNotified method.
When an event occurs in the interpreter the registered JIPEventListeners will be notified in the corresponding notified method.
If an error occurs the registered JIPEventListeners will be notified in errorNotified.
If the query specified in the parameter is still running it raises a JIPIsRunningException If the query specified in the parameter is not found it raises a JIPInvalidHandleException

Parameters:

nQueryHandle - the handle of the query

See Also:

openQuery(JIPTerm), closeQuery(int), JIPEventListener

closeQuery

public void closeQuery(int nQueryHandle)

Closes a query. If the query is still running it is closed.
The registered JIPEventListeners will be notified in closeNotify. If the query specified in the parameter is not found it raises a JIPInvalidHandleException

Parameters:

nQueryHandle - the handle of the query to close

See Also:

nextSolution(int), closeQuery(int), JIPEventListener.closeNotified(com.ugos.jiprolog.engine.JIPEvent)

hasMoreChoicePoints

public boolean hasMoreChoicePoints(int nQueryHandle)

Returns true if the query has more choice points on backtracking.
If the query specified in nQueryHandle is not found it raised a JIPInvalidHandleException.
If the query specified in nQueryHandle is still running it raises a JIPIsRunningException.
Note: You should not call isDeterministic until the query has no reached the goal.

Parameters:

nQueryHandle - the handle of the query

Returns:

true if the query has more choice points, false otherwise.

See Also:

openQuery(JIPTerm), nextSolution(int), closeQuery(int)

closeAllQueries

public void closeAllQueries()

Closes all pending queries

See Also:

openQuery(JIPTerm), nextSolution(int), closeQuery(int)

setEnvVariable

public void setEnvVariable(String varName,
                  Object value)

Sets the value of a custom environment variable.
Environment variables may be useful in custom predicates.

Parameters:

varName - the name of the variable

value - the value of the variable

See Also:

getEnvVariable(java.lang.String), removeEnvVariable(java.lang.String)

getEnvVariable

public Object getEnvVariable(String varName)

Gets the value of a custom environment variable.
Environment variables may be useful in custom predicates

Parameters:

varName - the name of the variable

See Also:

setEnvVariable(java.lang.String, java.lang.Object), removeEnvVariable(java.lang.String)

removeEnvVariable

public final Object removeEnvVariable(String varName)

Removes a custom environment variable.
Environment variables may be useful in custom predicates

Parameters:

varName - the name of the variable to remove

See Also:

setEnvVariable(java.lang.String, java.lang.Object), getEnvVariable(java.lang.String)

getEnvVariableNames

public Enumeration<String> getEnvVariableNames()

Gets the enumeration of all custom environment variable name.

See Also:

setEnvVariable(java.lang.String, java.lang.Object), removeEnvVariable(java.lang.String)

notifyEvent

public final void notifyEvent(int nID,
               JIPTerm term,
               int nQueryHandle)

Notifies a JIPEvent.

Parameters:

nID - the ID of the event to notify

term - the term attached to the event

nQueryHandle - the handle of the query which notifies the event

See Also:

JIPEvent, JIPTraceEvent

getTermParser

public final JIPTermParser getTermParser()

Returns the instance of JIPTermParser attached to this JIPEngine object
Use JIPTermParser to parse prolog terms

See Also:

JIPTermParser

finalize

protected void finalize()

Releases the resources used by JIProlog Developers should not call it directly.

Overrides:

finalize in class Object