jpl
Class Query

java.lang.Object
  extended by jpl.Query
All Implemented Interfaces:
java.util.Enumeration

public class Query
extends java.lang.Object
implements java.util.Enumeration

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) 2007 Paul Singleton

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 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).
static java.util.Hashtable[] allSolutions(java.lang.String text)
          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).
static java.util.Hashtable[] allSolutions(java.lang.String text, Term[] params)
          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).
static java.util.Hashtable[] allSolutions(Term goal)
          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).
 Term[] args()
          Deprecated. Use .goal().args() instead.
 void close()
          This method can be used to close an open query before its solutions are exhausted.
 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 implements part of the java.util.Enumeration interface.
 boolean hasMoreSolutions()
          This method returns true if JPL was able to initiate a "call" of this Query within a Prolog engine.
 boolean hasSolution()
          This method will attempt to call this Query's goal within an available Prolog engine.
static boolean hasSolution(java.lang.String text)
          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.
static boolean hasSolution(java.lang.String text, Term[] params)
          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.
static boolean hasSolution(Term goal)
          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.
 java.lang.String name()
          Deprecated. Use .goal().name() instead.
 java.lang.Object nextElement()
          This method implements part of 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[] nSolutions(long n)
          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).
static java.util.Hashtable[] nSolutions(java.lang.String text, long n)
          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).
static java.util.Hashtable[] nSolutions(java.lang.String text, Term[] params, long n)
          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).
static java.util.Hashtable[] nSolutions(Term goal, long n)
          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).
 java.util.Hashtable oneSolution()
          Returns the first solution, if any, as a (possibly empty) Hashtable of variablename-to-term bindings, else null.
static java.util.Hashtable oneSolution(java.lang.String text)
          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.
static java.util.Hashtable oneSolution(java.lang.String text, Term[] params)
          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.
static java.util.Hashtable oneSolution(Term goal)
          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.
 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.
 void rewind()
           
 java.lang.String toString()
          Returns a crude String representation of a Query.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Query

public Query(Term t)
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.

Parameters:
t - the goal of this Query

Query

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

Parameters:
text - the name of the principal functor of this Query's goal
args - the arguments of this Query's goal

Query

public Query(java.lang.String text,
             Term arg)

Query

public Query(java.lang.String text)
This constructor builds a Query from the given Prolog source text. Throws PrologException containing error(syntax_error(_),_) if text is invalid.

Parameters:
text - the Prolog source text of this Query
Method Detail

name

public final java.lang.String name()
Deprecated. Use .goal().name() instead.

Returns:
the name of this Query's goal (redundant, deprecated)

args

public final Term[] args()
Deprecated. Use .goal().args() instead.

Returns:
the arguments of this Query's goal (redundant, deprecated)

goal

public final Compound goal()
Returns the Compound (hence perhaps an Atom) which is the goal of this Query

Returns:
a Term representing the goal of this Query

hasMoreSolutions

public final boolean hasMoreSolutions()
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...
     }
 }
 

Returns:
true if the Prolog query succeeds; otherwise false.

open

public final void open()
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. 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 if the query cannot be set up for whatever reason, then a JPLException will be thrown.


getSolution

public final 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.

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.
  • 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.
  • This method will throw a JPLException if Query is not open.

    Returns:
    A Hashtable representing a substitution, or null

    getSubstWithNameVars

    public final java.util.Hashtable getSubstWithNameVars()

    nextSolution

    public final 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.

    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.
  • 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.
  • This method will throw a JPLException if Query is not open.

    Returns:
    A Hashtable representing a substitution.

    hasMoreElements

    public final boolean hasMoreElements()
    This method implements part of the java.util.Enumeration interface. It is a wrapper for hasMoreSolutions.

    Specified by:
    hasMoreElements in interface java.util.Enumeration
    Returns:
    true if the Prolog query yields a (or another) solution, else false.

    nextElement

    public final java.lang.Object nextElement()
    This method implements part of the java.util.Enumeration interface. It is a wrapper for nextSolution.

    Specified by:
    nextElement in interface java.util.Enumeration
    Returns:
    A Hashtable representing a substitution.

    rewind

    public final void rewind()

    close

    public final void close()
    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();
     


    allSolutions

    public final java.util.Hashtable[] allSolutions()
    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).

    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, this method (inconsistently) returned null when a Query had no solutions; in JPL 2.x onwards it returns an empty array (thus the length of the array is, in every case, the quantity of solutions).

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


    allSolutions

    public static final java.util.Hashtable[] allSolutions(Term goal)
    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.

    Parameters:
    goal - the goal of this Query
    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)

    allSolutions

    public static final java.util.Hashtable[] allSolutions(java.lang.String text)
    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.

    Parameters:
    text - a Prolog source text fragment denoting a goal
    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)

    allSolutions

    public static final java.util.Hashtable[] allSolutions(java.lang.String text,
                                                           Term[] params)
    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.

    Parameters:
    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
    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)

    nSolutions

    public final java.util.Hashtable[] nSolutions(long n)
    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).

    Returns:
    an array of Hashtables (possibly none), each of which is a solution (in the order in which they were found) of the Query; at most 'n' solutions will be found and returned. NB in JPL 1.0.1, this method (inconsistently) returned null when a Query had no solutions; in JPL 2.x onwards it returns an empty array (thus the length of the array is, in every case, the quantity of solutions).

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


    nSolutions

    public static final java.util.Hashtable[] nSolutions(Term goal,
                                                         long n)
    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.

    Parameters:
    goal - the goal of this Query

    nSolutions

    public static final java.util.Hashtable[] nSolutions(java.lang.String text,
                                                         long n)
    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.

    Parameters:
    text - a Prolog source text fragment denoting a goal

    nSolutions

    public static final java.util.Hashtable[] nSolutions(java.lang.String text,
                                                         Term[] params,
                                                         long n)
    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.

    Parameters:
    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

    oneSolution

    public final java.util.Hashtable oneSolution()
    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.

    Returns:
    the first solution, if the query has one, as a (possibly empty) Hashtable. If the return value is null, this means that the Query has no solutions.


    oneSolution

    public static final java.util.Hashtable oneSolution(Term goal)
    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.

    Parameters:
    goal - the goal of this Query

    oneSolution

    public static final java.util.Hashtable oneSolution(java.lang.String text)
    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.

    Parameters:
    text - a Prolog source text fragment denoting a goal

    oneSolution

    public static final java.util.Hashtable oneSolution(java.lang.String text,
                                                        Term[] params)
    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.

    Parameters:
    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

    query

    public final boolean query()
    Deprecated. Use .hasSolution() instead.

    This method will attempt to call this Query's goal within an available Prolog engine.

    Returns:
    the provability of the Query, i.e. 'true' if it has at least one solution, 'false' if the call fails without finding a solution.

    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.


    hasSolution

    public final boolean hasSolution()
    This method will attempt to call this Query's goal within an available Prolog engine.

    Returns:
    the provability of the Query, i.e. 'true' if it has at least one solution, 'false' if the call fails without finding a solution.

    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.


    hasSolution

    public static final boolean hasSolution(Term goal)
    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.

    Parameters:
    goal - the goal of this Query

    hasSolution

    public static final boolean hasSolution(java.lang.String text)
    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.

    Parameters:
    text - the goal of this Query, as Prolog source text

    hasSolution

    public static final boolean hasSolution(java.lang.String text,
                                            Term[] params)
    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.

    Parameters:
    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

    abort

    public final int abort()

    toString

    public java.lang.String toString()
    Returns a crude String representation of a Query.

    Overrides:
    toString in class java.lang.Object
    Returns:
    a crude String representation of a Query

    debugString

    public java.lang.String debugString()
    Deprecated. 

    Returns a debug-friendly representation of a Query

    Returns:
    a debug-friendly representation of a Query