|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjpl.Query
A Query instance is created by an application in order to query the Prolog engine. It is initialised with a Compound (or Atom) denoting the goal which is to be called, and also contains assorted private state relating to solutions. In some future version, it will contain details of the module in which the goal is to be called.
A Query is either open or closed: when closed, it has no connection to the Prolog engine; when open, it is linked to an active goal within the Prolog engine. Only one Query can be open at any one time
The Query class implements the Enumeration interface, and it is through this interface that one obtains successive solutions. The Enumeration hasMoreElements() method returns true if the call or redo succeeded (otherwise false), and if the call or redo did succeed, the nextElement() method returns a Hashtable representing variable bindings; the elements in the Hashtable are Terms, indexed by the Variables with which they are associated. For example, if p(a) and p(b) are facts in the Prolog database, then the following is equivalent to printing all the solutions to the Prolog query p(X):
Variable X = new Variable(); Term arg[] = { X }; Query q = new Query( "p", arg ); while ( q.hasMoreElements() ){ Term bound_to_x = ((Hashtable)q.nextElement()).get( X ); System.out.println( bound_to_x ); }Make sure to close the Query (using the rewind() method) if you do not need any further solutions which it may have. It is safe (although redundant) to close a Query whose solutions are already exhausted, or which is already closed. To obtain just one solution from a Query, use the oneSolution() method. To obtain all solutions, use the allSolutions() method. To determine merely whether the Query is provable, use the query() method (soon to be deprecated in favour of hasSolution()). (i.e. has at least one solution).
Copyright (C) 1998 Fred Dushin
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library Public License for more details.
Constructor Summary | |
Query(java.lang.String text)
This constructor builds a Query from the given Prolog source text |
|
Query(java.lang.String text,
Term arg)
|
|
Query(java.lang.String text,
Term[] args)
If text denotes an atom, this constructor is shorthand for new Query(new Compound(name,args)), but if text denotes a term containing N query symbols and there are N args, each query is replaced by its corresponding arg to provide the new Query's goal. |
|
Query(Term t)
This constructor creates a Query whose goal is the specified Term. |
Method Summary | |
int |
abort()
|
java.util.Hashtable[] |
allSolutions()
calls the Query's goal to exhaustion and returns an array containing every solution (in the order in which they were found). |
Term[] |
args()
Deprecated. Use .goal().args() instead. |
void |
close()
This method is used to close an open query so that the query may be re-run, even if the Query's Enumeration has more elements. |
java.lang.String |
debugString()
Deprecated. |
java.util.Hashtable |
getSolution()
This method returns a java.util.Hashtable, which represents a set of bindings from the names of query variables to terms within the solution. |
java.util.Hashtable |
getSubstWithNameVars()
|
Compound |
goal()
Returns the Compound (hence perhaps an Atom) which is the goal of this Query |
boolean |
hasMoreElements()
This method is completes the java.util.Enumeration interface. |
boolean |
hasMoreSolutions()
This method returns true if JPL was able to initiate a "call" of this Query within the Prolog engine. |
boolean |
hasSolution()
JPL will attempt to call this Query's goal within the attached Prolog engine. |
java.lang.String |
name()
Deprecated. Use .goal().name() instead. |
java.lang.Object |
nextElement()
This method completes the java.util.Enumeration interface. |
java.util.Hashtable |
nextSolution()
This method returns a java.util.Hashtable, which represents a binding from the names of query variables to terms within the solution. |
java.util.Hashtable |
oneSolution()
Returns the first solution, if any, as a (possibly empty) Hashtable. |
void |
open()
This method returns true if JPL was able to initiate a "call" of this Query within the Prolog engine. |
boolean |
query()
Deprecated. Use .hasSolution() instead. JPL will attempt to call this Query's goal within the attached Prolog engine. |
void |
rewind()
|
java.lang.String |
toString()
Returns the String representation of a Query. |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
public Query(Term t)
t
- the goal of this Querypublic Query(java.lang.String text, Term[] args)
text
- the name of the principal functor of this Query's goalargs
- the arguments of this Query's goalpublic Query(java.lang.String text, Term arg)
public Query(java.lang.String text)
text
- the Prolog source text of this QueryMethod Detail |
public final java.lang.String name()
public final Term[] args()
public final Compound goal()
public final boolean hasMoreSolutions()
Query q = // obtain Query reference while ( q.hasMoreSolutions() ){ Hashtable solution = q.nextSolution(); // process solution... }To ensure thread-safety, you should wrap sequential calls to this method in a synchronized block, using the static lock method to obtain the monitor.
Query q = // obtain Query reference synchronized ( jpl.Query.lock() ){ while ( q.hasMoreElements() ){ Hashtable solution = q.nextSolution(); // process solution... } }
If this method is called on an already-open Query, or while another Query is open, then a QueryInProgressException will be thrown, containing a reference to the currently open Query.
public final void open()
Query q = // obtain Query reference synchronized ( jpl.Query.lock() ){ while ( q.hasMoreElements() ){ Hashtable solution = q.nextSolution(); // process solution... } }
If this method is called on an already-open Query, or if the query cannot be set up for whatever reason, then a JPLException will be thrown.
public final java.util.Hashtable getSolution()
For example, if a Query has an occurrence of a jpl.Variable, say, named X, one can obtain the Term bound to X in the solution by looking up X in the Hashtable.
Variable X = new Variable(); Query q = // obtain Query reference (with X in the Term array) while ( q.hasMoreSolutions() ){ Hashtable solution = q.nextSolution(); // make t the Term bound to X in the solution Term t = (Term)solution.get( X ); // ... }Programmers should obey the following rules when using this method. This method will throw a JPLException if no query is in progress. It will throw a QueryInProgressException if another Query (besides this one) is in progress while this method is called.
public final java.util.Hashtable getSubstWithNameVars()
public final java.util.Hashtable nextSolution()
For example, if a Query has an occurrence of a jpl.Variable, say, named X, one can obtain the Term bound to X in the solution by looking up X in the Hashtable.
Variable X = new Variable(); Query q = // obtain Query reference (with X in the Term array) while ( q.hasMoreSolutions() ){ Hashtable solution = q.nextSolution(); // make t the Term bound to X in the solution Term t = (Term)solution.get( X ); // ... }Programmers should obey the following rules when using this method. This method will throw a JPLException if no query is in progress. It will throw a QueryInProgressException if another Query (besides this one) is in progress while this method is called.
public final boolean hasMoreElements()
hasMoreElements
in interface java.util.Enumeration
public final java.lang.Object nextElement()
This method will throw a QueryInProgressException if another Query (besides this one) is in progress while this method is called.
nextElement
in interface java.util.Enumeration
public final void rewind()
public final void close()
Here is a way to get the first three solutions to a Query, while subsequently being able to use the same Query object to obtain new solutions:
Query q = new Query( predicate, args ); int i = 0; for ( int i = 0; i < 3 && q.hasMoreSolutions(); ++i ){ Hasthable sub = (Hashtable) q.nextSolution(); ... } q.close();
public final java.util.Hashtable[] allSolutions()
This method will throw a QueryInProgressException if this or another Query is already open.
hasMoreElements()
,
nextElement()
,
hasMoreSolutions()
,
nextSolution()
,
rewind()
,
oneSolution()
,
allSolutions()
,
query()
public final java.util.Hashtable oneSolution()
hasMoreElements()
,
nextElement()
,
hasMoreSolutions()
,
nextSolution()
,
rewind()
,
oneSolution()
,
allSolutions()
,
query()
public final boolean query()
Only the first solution (if there is one) will be found; any bindings will be discarded, and the Query will be closed.
This method will throw a QueryInProgressException if this or another Query is already open.
hasMoreElements()
,
nextElement()
,
hasMoreSolutions()
,
nextSolution()
,
rewind()
,
oneSolution()
,
allSolutions()
,
query()
public final boolean hasSolution()
Only the first solution (if there is one) will be found; any bindings will be discarded, and the Query will be closed.
This method will throw a QueryInProgressException if this or another Query is already open.
hasMoreElements()
,
nextElement()
,
hasMoreSolutions()
,
nextSolution()
,
rewind()
,
oneSolution()
,
allSolutions()
,
query()
public final int abort()
public java.lang.String toString()
public java.lang.String debugString()
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |