Query (sigma-component 2.10 API)

java.lang.Object
- jpl.Query

All Implemented Interfaces:

Enumeration
```
public class Query
extends Object
implements Enumeration
```
A Query is an Object used to query the Prolog engine. It consists of an Atom (corresponding to the name of the predicate being queried) and a list (array) of Terms, the arguments to the predicate.
The Query class implements the Enumeration interface, and it is through this interface that one obtains solutions. The Enumeration hasMoreElements() method returns true if the goal succeeded (false, o/w), and if the goal did succeed, the nextElement() method returns a Hashtable representing variable bindings; the elements in the Hashtable are Terms, indexed by the Variables to which they are bound. 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 rewind the Query if you have not asked for all its solutions. To obtain just one solution from a Query, use the oneSolution() method. To obtain all solutions, use the allSolutions() method. Use the query() method if the Query is a ground query.
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.
Version:

$Revision: 1.1.1.1 $

Author:

Fred Dushin

Field Summary

Fields
Modifier and Type Field and Description

protected Term[] args_
the arguments to this Query

protected Atom atom_
the Atom corresponding to the predicate name in this Query

Fields
Modifier and Type	Field and Description
`protected Term[]`	`args_` the arguments to this Query
`protected Atom`	`atom_` the Atom corresponding to the predicate name in this Query

Constructor Summary

Constructors
Constructor and Description
`Query(Atom atom)` This constructor creates a Prolog query with no arguments (a "proposition" or "sentence").
`Query(Atom atom, Term[] args)` This constructor creates a Query object corresponding to a Prolog query.
`Query(String name)` This constructor is shorthand for
`Query(String name, Term t0)` This constructor is shorthand for
`Query(String name, Term[] args)` This constructor is shorthand for
`Query(String name, Term t0, Term t1)` This constructor is shorthand for
`Query(String name, Term t0, Term t1, Term t2)` This constructor is shorthand for
`Query(String name, Term t0, Term t1, Term t2, Term t3)` This constructor is shorthand for
`Query(String name, Term t0, Term t1, Term t2, Term t3, Term t4)` This constructor is shorthand for
`Query(String name, Term t0, Term t1, Term t2, Term t3, Term t4, Term t5)` This constructor is shorthand for
`Query(String name, Term t0, Term t1, Term t2, Term t3, Term t4, Term t5, Term t6)` This constructor is shorthand for
`Query(String name, Term t0, Term t1, Term t2, Term t3, Term t4, Term t5, Term t6, Term t7)` This constructor is shorthand for
`Query(String name, Term t0, Term t1, Term t2, Term t3, Term t4, Term t5, Term t6, Term t7, Term t8)` This constructor is shorthand for
`Query(String name, Term t0, Term t1, Term t2, Term t3, Term t4, Term t5, Term t6, Term t7, Term t8, Term t9)` This constructor is shorthand for

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`Hashtable[]`	`allSolutions()`
`Term[]`	`args()`
`Atom`	`atom()`
`String`	`debugString()`
`boolean`	`hasMoreElements()` This method is completes the java.util.Enumeration interface.
`boolean`	`hasMoreSolutions()` This method returns true if making a Prolog Query using this Object's Atom and Terms succeeds.
`boolean`	`hasMoreSubstitutions()` Deprecated. Substitution too hard to spell; use Solution instead.
`static Object`	`lock()` Use this method to obtain the lock that is used to synchronize all calls to the Low-Level Interface.
`Object`	`nextElement()` This method is completes the java.util.Enumeration interface.
`Hashtable`	`nextSolution()` This method returns a java.util.Hashtable, which represents a substitution of Terms for Variables in the Term list in this Query.
`Hashtable`	`nextSubstitution()` Deprecated. Substitution too hard to spell; use Solution instead.
`Hashtable`	`oneSolution()`
`static void`	`printSolution(Hashtable substitution)` Deprecated. use Util.toString instead.
`static void`	`printSubstitution(Hashtable substitution)` Deprecated. use Util.toString instead.
`boolean`	`query()`
`void`	`rewind()` This method is used to rewind the query so that the query may be re-run, even if the Query qua Enumeration has more elements.
`String`	`toString()` Returns the String representation of a Query.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - atom_
```
protected Atom atom_
```
    the Atom corresponding to the predicate name in this Query
  - args_
```
protected Term[] args_
```
    the arguments to this Query
- Constructor Detail
  - Query
```
public Query(Atom atom,
             Term[] args)
```
    This constructor creates a Query object corresponding to a Prolog query. The predicate name is determined by the pred_atom parameter, and the arguments are given by the arg parameter.
    NB. Creating an instance of the Query class does not result in a call to the Prolog Abstract Machine.
    
    Parameters:
    
    atom - an Atom that names the predicate in this Query
    
    args - the arguments to this Query
  - Query
```
public Query(String name,
             Term[] args)
```
    This constructor is shorthand for
```
 new Query( new Atom( name ), arg )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    args - the arguments to this Query
  - Query
```
public Query(String name,
             Term t0)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1,
             Term t2)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1, t2 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
    
    t2 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1,
             Term t2,
             Term t3)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1, t2, t3 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
    
    t2 - a jpl.Term
    
    t3 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1,
             Term t2,
             Term t3,
             Term t4)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1, t2, t3, t4 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
    
    t2 - a jpl.Term
    
    t3 - a jpl.Term
    
    t4 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1,
             Term t2,
             Term t3,
             Term t4,
             Term t5)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1, t2, t3, t4, 
                       t5 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
    
    t2 - a jpl.Term
    
    t3 - a jpl.Term
    
    t4 - a jpl.Term
    
    t5 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1,
             Term t2,
             Term t3,
             Term t4,
             Term t5,
             Term t6)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1, t2, t3, t4, 
                       t5, t6 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
    
    t2 - a jpl.Term
    
    t3 - a jpl.Term
    
    t4 - a jpl.Term
    
    t5 - a jpl.Term
    
    t6 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1,
             Term t2,
             Term t3,
             Term t4,
             Term t5,
             Term t6,
             Term t7)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1, t2, t3, t4, 
                       t5, t6, t7 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
    
    t2 - a jpl.Term
    
    t3 - a jpl.Term
    
    t4 - a jpl.Term
    
    t5 - a jpl.Term
    
    t6 - a jpl.Term
    
    t7 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1,
             Term t2,
             Term t3,
             Term t4,
             Term t5,
             Term t6,
             Term t7,
             Term t8)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1, t2, t3, t4, 
                       t5, t6, t7, t8 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
    
    t2 - a jpl.Term
    
    t3 - a jpl.Term
    
    t4 - a jpl.Term
    
    t5 - a jpl.Term
    
    t6 - a jpl.Term
    
    t7 - a jpl.Term
    
    t8 - a jpl.Term
  - Query
```
public Query(String name,
             Term t0,
             Term t1,
             Term t2,
             Term t3,
             Term t4,
             Term t5,
             Term t6,
             Term t7,
             Term t8,
             Term t9)
```
    This constructor is shorthand for
```
 new Query( 
     new Atom( name ), 
     Util.toTermArray( t0, t1, t2, t3, t4, 
                       t5, t6, t7, t8, t9 ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
    
    t0 - a jpl.Term
    
    t1 - a jpl.Term
    
    t2 - a jpl.Term
    
    t3 - a jpl.Term
    
    t4 - a jpl.Term
    
    t5 - a jpl.Term
    
    t6 - a jpl.Term
    
    t7 - a jpl.Term
    
    t8 - a jpl.Term
    
    t9 - a jpl.Term
  - Query
```
public Query(Atom atom)
```
    This constructor creates a Prolog query with no arguments (a "proposition" or "sentence").
    
    Parameters:
    
    atom - an Atom that names the predicate in this Query
  - Query
```
public Query(String name)
```
    This constructor is shorthand for
```
 new Query( new Atom( name ) )
 
```
    Parameters:
    
    name - the name of the predicate in this Query
- Method Detail
  - lock
```
public static Object lock()
```
    Use this method to obtain the lock that is used to synchronize all calls to the Low-Level Interface. You should use this lock i) if you are using the hasMoreSolutions() and nextSolution() methods to enumerate the solutions to a Query, and ii) you need these calls to be thread-safe. Example:
```
 Query query = // get a query somehow
 synchronized ( jpl.Query.lock() ){
     while ( query.hasMoreElements() ){
          Hashtable solution = query.nextSolution();
          // process solution...
     }
 }
 
```
    The lock so acquired is the same lock used internally by hasMoreSolutions and nextSolution methods; indeed, it is the Class Object for the jpl.fli.Prolog class, so any calls to the Low-Level Interface will be blocked, as well. However, you should not intermix calls to the Low-Level Interface when using the High-Level Interface.
    Returns:
    
    the lock on any calls to the FLI
  - atom
```
public final Atom atom()
```
    Returns:
    
    the Atom corresponding to the predicate name in this Query
  - args
```
public final Term[] args()
```
    Returns:
    
    the arguments to this Query
  - hasMoreSolutions
```
public final boolean hasMoreSolutions()
```
    This method returns true if making a Prolog Query using this Object's Atom and Terms succeeds. It is designed to be used in conjunction 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...
     }
 }
 
```
    If this method is called while another is in progress, a QueryInProgressException will be thrown with the currently executing Query.
    Returns:
    
    true if the Prolog query succeeds; false, o/w.
    
    See Also:
    
    lock(), hasMoreSolutions(), nextSolution(), hasMoreElements(), nextElement(), rewind(), oneSolution(), allSolutions(), query()
  - nextSolution
```
public final Hashtable nextSolution()
```
    This method returns a java.util.Hashtable, which represents a substitution of Terms for Variables in the Term list in this Query. The Hashtable contains instances of Terms, keyed on Variable instances in the Term list.
    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.
    The nextSolution() method should only be called after the hasMoreSolutions() method returns true; otherwise a JPLException will be raised, indicating that no Query is in progress.
    The nextSolution() and hasMoreSolutions() should be called in the same thread of execution, at least for a given Query instance.
    The nextSolution() method should not be called while another Thread is in the process of evaluating a Query. The JPL High-Level interface is designed to be thread safe, and is thread-safe as long as the previous two rules are obeyed.
    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.
    Returns:
    
    A Hashtable representing a substitution.
    
    See Also:
    
    hasMoreSolutions(), nextSolution(), hasMoreElements(), nextElement(), rewind(), oneSolution(), allSolutions(), query()
  - hasMoreElements
```
public final boolean hasMoreElements()
```
    This method is completes the java.util.Enumeration interface. It is a wrapper for hasMoreSolutions.
    
    Specified by:
    
    hasMoreElements in interface Enumeration
    
    Returns:
    
    true if the Prolog query succeeds; false, o/w.
    
    See Also:
    
    hasMoreSolutions(), nextSolution(), hasMoreElements(), nextElement(), rewind(), oneSolution(), allSolutions(), query()
  - hasMoreSubstitutions
```
public final boolean hasMoreSubstitutions()
```
    Deprecated. Substitution too hard to spell; use *Solution* instead.
  - nextElement
```
public final Object nextElement()
```
    This method is completes the java.util.Enumeration interface. It is a wrapper for nextSolution.
    This method will throw a QueryInProgressException if another Query (besides this one) is in progress while this method is called.
    
    Specified by:
    
    nextElement in interface Enumeration
    
    Returns:
    
    A Hashtable representing a substitution.
    
    See Also:
    
    hasMoreSolutions(), nextSolution(), hasMoreElements(), nextElement(), rewind(), oneSolution(), allSolutions(), query()
  - nextSubstitution
```
public final Hashtable nextSubstitution()
```
    Deprecated. Substitution too hard to spell; use *Solution* instead.
  - rewind
```
public final void rewind()
```
    This method is used to rewind the query so that the query may be re-run, even if the Query qua Enumeration has more elements. Calling rewind() on an exhausted Enumeration has no effect.
    Here is a way to get the first 3 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.rewind();
 
```
    This method will throw a QueryInProgressException if another Query (besides this one) is in progress while this method is called. It is safe to call this method if no query is in progress.
    See Also:
    
    hasMoreSolutions(), nextSolution(), hasMoreElements(), nextElement(), rewind(), oneSolution(), allSolutions(), query()
  - allSolutions
```
public final Hashtable[] allSolutions()
```
    Returns:
    
    an array of Hashtables, each of which is a solution (in order) of the Query. If the return value is null, this means the Query has no solutions.
    This method will throw a QueryInProgressException if another Query (besides this one) is in progress while this method is called.
    
    See Also:
    
    hasMoreElements(), nextElement(), hasMoreSolutions(), nextSolution(), rewind(), oneSolution(), allSolutions(), query()
  - oneSolution
```
public final Hashtable oneSolution()
```
    Returns:
    
    one solution, if it has one. If the return value is null, this means that the Query has no solutions; otherwise, the solution will be a (possibly empty) Hashtable.
    This method will throw a QueryInProgressException if another Query (besides this one) is in progress while this method is called.
    
    See Also:
    
    hasMoreElements(), nextElement(), hasMoreSolutions(), nextSolution(), rewind(), oneSolution(), allSolutions(), query()
  - query
```
public final boolean query()
```
    Returns:
    
    the value of the Query.
    This method should only be called for ground queries, since the results of any bindings are discarded.
    This method will throw a QueryInProgressException if another Query (besides this one) is in progress while this method is called.
    
    See Also:
    
    hasMoreElements(), nextElement(), hasMoreSolutions(), nextSolution(), rewind(), oneSolution(), allSolutions(), query()
  - printSolution
```
public static void printSolution(Hashtable substitution)
```
    Deprecated. use Util.toString instead.
    
    Prints a substitution to stdout. For testing.
    
    Parameters:
    
    substitution - The substitution to print.
  - printSubstitution
```
public static void printSubstitution(Hashtable substitution)
```
    Deprecated. use Util.toString instead.
  - toString
```
public String toString()
```
    Returns the String representation of a Query.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    the String representation of a Query
  - debugString
```
public String debugString()
```

Class Query

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

atom_

args_

Constructor Detail

Query

Query

Query

Query

Query

Query

Query

Query

Query

Query

Query

Query

Query

Query

Method Detail

lock

atom

args

hasMoreSolutions

nextSolution

hasMoreElements

hasMoreSubstitutions

nextElement

nextSubstitution

rewind

allSolutions

oneSolution

query

printSolution

printSubstitution

toString

debugString