Public Member Functions | |
| final int | abort () |
| synchronized final Hashtable[] | allSolutions () |
| final Term[] | args () |
| synchronized final void | close () |
| String | debugString () |
| synchronized final Hashtable | getSolution () |
| synchronized final Hashtable | getSubstWithNameVars () |
| final Compound | goal () |
| synchronized final boolean | hasMoreElements () |
| synchronized final boolean | hasMoreSolutions () |
| synchronized final boolean | hasSolution () |
| synchronized final boolean | isOpen () |
| final String | name () |
| synchronized final Object | nextElement () |
| synchronized final Hashtable | nextSolution () |
| synchronized final Hashtable[] | nSolutions (long n) |
| synchronized final Hashtable | oneSolution () |
| synchronized final void | open () |
| synchronized final boolean | query () |
| Query (String text) | |
| Query (String text, Term arg) | |
| Query (String text, Term[] args) | |
| Query (Term t) | |
| synchronized final void | rewind () |
| String | toString () |
Static Public Member Functions | |
| static final Hashtable[] | allSolutions (String text, Term[] params) |
| static final Hashtable[] | allSolutions (String text) |
| static final Hashtable[] | allSolutions (Term goal) |
| static final boolean | hasSolution (String text, Term[] params) |
| static final boolean | hasSolution (String text) |
| static final boolean | hasSolution (Term goal) |
| static final Hashtable[] | nSolutions (String text, Term[] params, long n) |
| static final Hashtable[] | nSolutions (String text, long n) |
| static final Hashtable[] | nSolutions (Term goal, long n) |
| static final Hashtable | oneSolution (String text, Term[] params) |
| static final Hashtable | oneSolution (String text) |
| static final Hashtable | oneSolution (Term goal) |
Protected Attributes | |
| final String | contextModule = "user" |
| final Compound | goal_ |
| final String | hostModule = "user" |
Private Member Functions | |
| final boolean | get1 () |
| final Hashtable | get2 () |
| final Hashtable | get2WithNameVars () |
| Compound | Query1 (Term t) |
Static Private Member Functions | |
| static Term | Query1 (String text, Term[] args) |
Private Attributes | |
| engine_t | engine = null |
| fid_t | fid = null |
| boolean | open = false |
| predicate_t | predicate = null |
| qid_t | qid = null |
| Query | subQuery = null |
| term_t | term0 = null |
Static Private Attributes | |
| static Map | m = new Hashtable() |
A Query instance is created by an application in order to query the Prolog database (or to invoke a built-in predicate). 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 may 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 system; when open, it is linked to an active goal within a Prolog engine.
The Query class implements the Enumeration interface, through which one can obtain 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 (String) names of 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("X"); 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 close() 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 obtain at most N solutions, use the nSolutions() method.
To determine merely whether the Query is provable, use the hasSolution() method (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.
Definition at line 102 of file Query.java.
| jpl::Query::Query | ( | Term | t | ) | [inline] |
This constructor creates a Query whose goal is the specified Term. The Query is initially closed. NB Creating an instance of the Query class does not result in a call to a Prolog engine. NB The goal can be a Compound or an Atom (Atom extends Compound), but cannot be an instance of jpl.Float, jpl.Integer or jpl.Variable.
| t | the goal of this Query |
Definition at line 148 of file Query.java.
| jpl::Query::Query | ( | String | text, | |
| Term[] | args | |||
| ) | [inline] |
If text denotes an atom, this constructor is shorthand for <font face="monospace">new Query(new Compound(name,args))</font>, 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.
| text | the name of the principal functor of this Query's goal | |
| args | the arguments of this Query's goal |
Definition at line 175 of file Query.java.
| jpl::Query::Query | ( | String | text, | |
| Term | arg | |||
| ) | [inline] |
Definition at line 179 of file Query.java.
| jpl::Query::Query | ( | String | text | ) | [inline] |
This constructor builds a Query from the given Prolog source text. Throws PrologException containing error(syntax_error(_),_) if text is invalid.
| text | the Prolog source text of this Query |
Definition at line 197 of file Query.java.
| final int jpl::Query::abort | ( | ) | [inline] |
Definition at line 801 of file Query.java.
| static final Hashtable [] jpl::Query::allSolutions | ( | String | text, | |
| Term[] | params | |||
| ) | [inline, static] |
If text denotes (in traditional Prolog source syntax) a term containing N questionmark (?) symbols and there are N accompanying Term params, this static method replaces each questionmark symbol by its respective param, calls the resulting goal to exhaustion, and returns an array of zero or more Hashtables of zero or more variablename-to-term bindings (each Hashtable represents a solution, in the order in which they were found).
Otherwise, if text denotes an atom, this static method creates a Query where text is the name of the goal and params are the args; the resulting goal is then called as above. This letter mode is redundant, deprecated (informally), and retained only for backward compatibility.
| text | the Prolog source text of a goal, in which questionmarks are regarded as substitutible parameters | |
| params | terms to be substituted for the respective questionmarks in the query text |
Definition at line 606 of file Query.java.
| static final Hashtable [] jpl::Query::allSolutions | ( | String | text | ) | [inline, static] |
This static method creates a Query from the given Prolog source text fragment, calls it to exhaustion, and returns an array of zero or more Hashtables of zero or more variablename-to-term bindings (each Hashtable represents a solution, in the order in which they were found). Throws PrologException containing error(syntax_error(_),_) if text is invalid.
| text | a Prolog source text fragment denoting a goal |
Definition at line 587 of file Query.java.
| static final Hashtable [] jpl::Query::allSolutions | ( | Term | goal | ) | [inline, static] |
This static method creates a Query whose goal is the given Term, calls it to exhaustion, and returns an array of zero or more Hashtables of zero or more variablename-to-term bindings (each Hashtable represents a solution, in the order in which they were found). Throws JPLException if goal is neither a jpl.Atom nor a jpl.Compound.
| goal | the goal of this Query |
Definition at line 574 of file Query.java.
| synchronized final Hashtable [] jpl::Query::allSolutions | ( | ) | [inline] |
calls the Query's goal to exhaustion and returns an array of zero or more Hashtables of zero or more variablename-to-term bindings (each Hashtable represents a solution, in the order in which they were found).
NB in JPL 1.0.1, bindings were keyed (awkwardly) by Variable instances; in JPL 2.x onwards they are keyed by the (String) names of variables, which is consistent with the Term type being just a concrete syntax for terms (and hence queries).
Definition at line 549 of file Query.java.
| final Term [] jpl::Query::args | ( | ) | [inline] |
Definition at line 124 of file Query.java.
| synchronized final void jpl::Query::close | ( | ) | [inline] |
This method can be used to close an open query before its solutions are exhausted. It is called automatically when solutions are exhausted, i.e. when hasMoreSolutions() fails. Calling close() on an already closed Query is harmless (has no effect).
Here is one way to get the first three solutions to a Query:
Query q = new Query(predicate, args); Hashtable sub1 = (Hashtable) q.nextSolution(); Hashtable sub2 = (Hashtable) q.nextSolution(); Hashtable sub3 = (Hashtable) q.nextSolution(); q.close();
Definition at line 503 of file Query.java.
| String jpl::Query::debugString | ( | ) | [inline] |
Returns a debug-friendly representation of a Query
Definition at line 870 of file Query.java.
| final boolean jpl::Query::get1 | ( | ) | [inline, private] |
Definition at line 326 of file Query.java.
| final Hashtable jpl::Query::get2 | ( | ) | [inline, private] |
Definition at line 432 of file Query.java.
| final Hashtable jpl::Query::get2WithNameVars | ( | ) | [inline, private] |
Definition at line 443 of file Query.java.
| synchronized final Hashtable jpl::Query::getSolution | ( | ) | [inline] |
This method returns a java.util.Hashtable, which represents a set of bindings from the names of query variables to terms within the solution.
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("X"); 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. <menu> The nextSolution() method should only be called after the hasMoreSolutions() method returns true; otherwise a JPLException will be raised, indicating that the Query is no longer open. The nextSolution() and hasMoreSolutions() should be called in the same thread of execution, for a given Query instance. </menu>
This method will throw a JPLException if Query is not open.
Definition at line 376 of file Query.java.
| synchronized final Hashtable jpl::Query::getSubstWithNameVars | ( | ) | [inline] |
Definition at line 386 of file Query.java.
| final Compound jpl::Query::goal | ( | ) | [inline] |
| synchronized final boolean jpl::Query::hasMoreElements | ( | ) | [inline] |
This method implements part of the java.util.Enumeration interface. It is a wrapper for hasMoreSolutions.
Definition at line 471 of file Query.java.
| synchronized final boolean jpl::Query::hasMoreSolutions | ( | ) | [inline] |
This method returns true if JPL was able to initiate a "call" of this Query within a Prolog engine. It is designed to be used with the nextSolution() method to retrieve one or more substitutions in the form of Hashtables. To iterate through all the solutions to a Query, for example, one might write
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... } }
Definition at line 254 of file Query.java.
| static final boolean jpl::Query::hasSolution | ( | String | text, | |
| Term[] | params | |||
| ) | [inline, static] |
If text denotes (in traditional Prolog source syntax) a term containing N questionmark (?) symbols and there are N params, each questionmark symbol is replaced by its corresponding arg to provide the new Query's goal: the resulting Query is called as described above.
Otherwise, if text denotes an atom, this static method creates a Query where text is the name of its goal and args are its args; it then calls this goal (at most once) and returns true if a solution was found, else false. This latter mode is redundant, deprecated (informally), and retained only for backward compatibility.
| text | the Prolog source text of a goal, in which questionmarks are regarded as substitutible parameters | |
| params | terms to be substituted for the respective questionmarks in the query text |
Definition at line 795 of file Query.java.
| static final boolean jpl::Query::hasSolution | ( | String | text | ) | [inline, static] |
This static method creates a Query from the given Prolog source text and calls it at most once, returning true if a solution was found, else false. Throws PrologException containing error(syntax_error(_),_) if text is invalid.
| text | the goal of this Query, as Prolog source text |
Definition at line 779 of file Query.java.
| static final boolean jpl::Query::hasSolution | ( | Term | goal | ) | [inline, static] |
This static method creates a Query (whose goal is the specified Term) and calls it at most once, returning true if a solution was found, else false. The goal can be a jpl.Atom or a jpl.Compound, but cannot be an instance of jpl.Float, jpl.Integer or jpl.Variable.
| goal | the goal of this Query |
Definition at line 769 of file Query.java.
| synchronized final boolean jpl::Query::hasSolution | ( | ) | [inline] |
This method will attempt to call this Query's goal within an available Prolog engine.
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 JPLException if this Query is already open.
Definition at line 758 of file Query.java.
| synchronized final boolean jpl::Query::isOpen | ( | ) | [inline] |
isOpen() returns true iff the query is open.
Definition at line 221 of file Query.java.
| final String jpl::Query::name | ( | ) | [inline] |
Definition at line 117 of file Query.java.
| synchronized final Object jpl::Query::nextElement | ( | ) | [inline] |
This method implements part of the java.util.Enumeration interface. It is a wrapper for nextSolution.
Definition at line 483 of file Query.java.
| synchronized final Hashtable jpl::Query::nextSolution | ( | ) | [inline] |
This method returns a java.util.Hashtable, which represents a binding from the names of query variables to terms within the solution.
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("X"); 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. <menu> The nextSolution() method should only be called after the hasMoreSolutions() method returns true; otherwise a JPLException will be raised, indicating that the Query is no longer open. The nextSolution() and hasMoreSolutions() should be called in the same thread of execution, for a given Query instance. </menu>
This method will throw a JPLException if Query is not open.
Definition at line 429 of file Query.java.
| static final Hashtable [] jpl::Query::nSolutions | ( | String | text, | |
| Term[] | params, | |||
| long | n | |||
| ) | [inline, static] |
If text denotes (in traditional Prolog source syntax) a term containing N questionmark (?) symbols and there are N accompanying params, this static method replaces each questionmark symbol by its respective param, calls the resulting goal to exhaustion or until N solutions are found, whichever is sooner, and returns an array containing (as possibly empty Hashtables of variablename-to-term bindings) every found solution (in the order in which they were found).
Otherwise, if text denotes an atom, this static method creates a Query where text is the name of the goal and params are the args; the resulting goal is then called as above. This latter mode is redundant, deprecated (informally), and retained only for backward compatibility.
| text | the Prolog source text of a goal, in which questionmarks are regarded as substitutible parameters | |
| params | terms to be substituted for the respective questionmarks in the query text |
Definition at line 672 of file Query.java.
| static final Hashtable [] jpl::Query::nSolutions | ( | String | text, | |
| long | n | |||
| ) | [inline, static] |
This static method creates a Query from the given Prolog source text fragment, calls it to exhaustion or until N solutions are found, whichever is sooner, and returns an array containing (as possibly empty Hashtables of variablename-to-term bindings) every found solution (in the order in which they were found). Throws PrologException containing error(syntax_error(_),_) if text is invalid.
| text | a Prolog source text fragment denoting a goal |
Definition at line 655 of file Query.java.
| static final Hashtable [] jpl::Query::nSolutions | ( | Term | goal, | |
| long | n | |||
| ) | [inline, static] |
This static method creates a Query whose goal is the given Term, calls it to exhaustion or until N solutions are found, whichever is sooner, and returns an array containing (as possibly empty Hashtables of variablename-to-term bindings) every found solution (in the order in which they were found). Throws JPLException if goal is neither a jpl.Atom nor a jpl.Compound.
| goal | the goal of this Query |
Definition at line 644 of file Query.java.
| synchronized final Hashtable [] jpl::Query::nSolutions | ( | long | n | ) | [inline] |
calls the Query's goal to exhaustion or until N solutions are found, whichever is sooner, and returns an array containing (as possibly empty Hashtables of variablename-to-term bindings) every found solution (in the order in which they were found).
NB in JPL 1.0.1, bindings were keyed (awkwardly) by Variable instances; in JPL 2.x onwards they are keyed by the (String) names of variables, which is consistent with the Term type being just a concrete syntax for terms (and hence queries).
Definition at line 621 of file Query.java.
| static final Hashtable jpl::Query::oneSolution | ( | String | text, | |
| Term[] | params | |||
| ) | [inline, static] |
If text denotes (in traditional Prolog source syntax) a term containing N questionmark (?) symbols and there are N params, each questionmark symbol is replaced by its respective param to provide the goal of this query: the resulting goal is then called (at most once) and the first solution, if there is one, is returned as a (possibly empty) Hashtable, else null.
Otherwise, if text denotes an atom, this static method creates a Query where text is the name of the goal and params are the args; the resulting goal is then called as above. This latter mode is redundant, deprecated (informally), and retained only for backward compatibility.
| text | the Prolog source text of a goal, in which questionmarks are regarded as substitutible parameters | |
| params | terms to be substituted for the respective questionmarks in the query text |
Definition at line 732 of file Query.java.
| static final Hashtable jpl::Query::oneSolution | ( | String | text | ) | [inline, static] |
This static method creates a Query from the given Prolog source text fragment, and calls it at most once, returning the first solution, if there is one, as a (possibly empty) Hashtable, else null. Throws PrologException containing error(syntax_error(_),_) if text is invalid.
| text | a Prolog source text fragment denoting a goal |
Definition at line 715 of file Query.java.
| static final Hashtable jpl::Query::oneSolution | ( | Term | goal | ) | [inline, static] |
This static method creates a Query (whose goal is the specified Term) and calls it at most once, returning the first solution, if there is one, as a (possibly empty) Hashtable, else null. The goal can be a jpl.Atom or a jpl.Compound, but cannot be an instance of jpl.Float, jpl.Integer or jpl.Variable.
| goal | the goal of this Query |
Definition at line 705 of file Query.java.
| synchronized final Hashtable jpl::Query::oneSolution | ( | ) | [inline] |
Returns the first solution, if any, as a (possibly empty) Hashtable of variablename-to-term bindings, else null.
This method will throw a JPLException if this Query is already open (and the Query will remain open as before). Otherwise, upon return, the Query will be closed.
Definition at line 683 of file Query.java.
| synchronized final void jpl::Query::open | ( | ) | [inline] |
This method returns true if JPL was able to initiate a "call" of this Query within the Prolog engine. It is designed to be used with the getSolution() and close() methods to retrieve one or more substitutions in the form of Hashtables.
Query q = // obtain Query reference Hashtable soln; q.open(); while ((soln = q.getSolution()) != null) { // 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.
Definition at line 280 of file Query.java.
| synchronized final boolean jpl::Query::query | ( | ) | [inline] |
This method will attempt to call this Query's goal within an available Prolog engine.
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 JPLException if this Query is already open.
Definition at line 746 of file Query.java.
Definition at line 182 of file Query.java.
Definition at line 151 of file Query.java.
| synchronized final void jpl::Query::rewind | ( | ) | [inline] |
Definition at line 486 of file Query.java.
| String jpl::Query::toString | ( | ) | [inline] |
Returns a crude String representation of a Query.
Definition at line 858 of file Query.java.
final String jpl::Query::contextModule = "user" [protected] |
Definition at line 112 of file Query.java.
engine_t jpl::Query::engine = null [private] |
Definition at line 210 of file Query.java.
fid_t jpl::Query::fid = null [private] |
Definition at line 213 of file Query.java.
final Compound jpl::Query::goal_ [protected] |
final String jpl::Query::hostModule = "user" [protected] |
Definition at line 111 of file Query.java.
Map jpl::Query::m = new Hashtable() [static, private] |
Definition at line 106 of file Query.java.
boolean jpl::Query::open = false [private] |
These variables are used and set across the hasMoreElements and nextElement Enumeration interface implementation
Definition at line 207 of file Query.java.
predicate_t jpl::Query::predicate = null [private] |
Definition at line 212 of file Query.java.
qid_t jpl::Query::qid = null [private] |
Definition at line 215 of file Query.java.
Query jpl::Query::subQuery = null [private] |
Definition at line 211 of file Query.java.
term_t jpl::Query::term0 = null [private] |
Definition at line 214 of file Query.java.