Query.java

Go to the documentation of this file.

//tabstop=4
//*****************************************************************************/
// Project: jpl
//
// File:    $Id$
// Date:    $Date$
// Author:  Fred Dushin <fadushin@syr.edu>
//          
//
// Description:
//    
//
// -------------------------------------------------------------------------
// Copyright (c) 2004 Paul Singleton
// Copyright (c) 1998 Fred Dushin
//                    All rights reserved.
// 
// 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.
//*****************************************************************************/
package jpl;

import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Map;
import java.util.Vector;
import jpl.fli.*;

//----------------------------------------------------------------------/
// Query
// Implementation notes:  
// 
//----------------------------------------------------------------------/
public class Query implements Enumeration {
        //==================================================================/
        //  Attributes
        //==================================================================/
        private static Map                      m                               = new Hashtable();      // maps (engine_t) engine handle to (Query) topmost query
        protected final Compound        goal_;                                                          // set by all initialisers
        protected final String          hostModule              = "user";                       // until revised constructors allow this to be specified
        protected final String          contextModule   = "user";                       // until revised constructors allow this to be specified
        public final String name() {
                return goal_.name(); // it can only be a Compound or Atom
        }
        public final Term[] args() {
                return goal_.args();
        }
        public final Compound goal() {
                return goal_;
        }
        //==================================================================/
        //  Constructors and Initialization
        //==================================================================/
        //------------------------------------------------------------------/
        // Query
        public Query(Term t) { // formerly insisted (confusingly) on a Compound (or Atom)
                this.goal_ = Query1(t);
        }
        private Compound Query1(Term t) {
                if (t instanceof Compound) {
                        return (Compound) t;
                } else if (t instanceof Integer) {
                        throw new JPLException("a Query's goal must be an Atom or Compound (not an Integer)");
                } else if (t instanceof Float) {
                        throw new JPLException("a Query's goal must be an Atom or Compound (not a Float)");
                } else if (t instanceof Variable) {
                        throw new JPLException("a Query's goal must be an Atom or Compound (not a Variable)");
                } else {
                        throw new JPLException("a Query's goal must be an Atom or Compound");
                }
        }
        // Query
        public Query(String text, Term[] args) {
                this(Query1(text, args));
        }
        // convenience case for a single arg
        public Query(String text, Term arg) {
                this(Query1(text, new Term[] { arg }));
        }
        private static Term Query1(String text, Term[] args) {
                Term t = Util.textToTerm(text);
                if (t instanceof Atom) {
                        return new Compound(text, args);
                } else {
                        return t.putParams(args);
                }
        }
        // Query
        public Query(String text) {
                this(Util.textToTerm(text));
        }
        //==================================================================/
        //  Making Prolog Queries
        //==================================================================/
        private boolean         open            = false;
        // the following state variables are used and defined only if this query is open:
        // private boolean called = false; // open/get/close vs. hasMoreSolutions/nextSolution
        private engine_t        engine          = null; // handle of attached Prolog engine iff open, else null
        private Query           subQuery        = null; // the open Query (if any) on top of which this open Query is stacked, else null
        private predicate_t     predicate       = null; // handle of this Query's predicate iff open, else undefined
        private fid_t           fid                     = null; // id of current Prolog foreign frame iff open, else null
        private term_t          term0           = null; // term refs of this Query's args iff open, else undefined
        private qid_t           qid                     = null; // id of current Prolog query iff open, else null
        //
        public synchronized final boolean isOpen() {
                return open;
        }
        //------------------------------------------------------------------/
        // hasMoreSolutions
        public synchronized final boolean hasMoreSolutions() {
                if (!open) {
                        open();
                }
                return get1();
        }
        //------------------------------------------------------------------/
        // open
        public synchronized final void open() {
                if (open) {
                        throw new JPLException("Query is already open");
                }
                // int self = Prolog.thread_self();
                // System.out.println("JPL thread_self()=" + self);
                if (Prolog.thread_self() == -1) { // this Java thread has no attached Prolog engine?
                        engine = Prolog.attach_pool_engine(); // may block for a while, or fail
                        // System.out.println("JPL attaching engine[" + engine.value + "] for " + this.hashCode() + ":" + this.toString());
                } else { // this Java thread has an attached engine
                        engine = Prolog.current_engine();
                        // System.out.println("JPL   reusing engine[" + engine.value + "] for " + this.hashCode() + ":" + this.toString());
                }
                if (m.containsKey(new Long(engine.value))) {
                        subQuery = (Query) m.get(new Long(engine.value)); // get this engine's previous topmost query
                        // System.out.println("JPL   reusing engine[" + engine.value + "] pushing " + subQuery.hashCode() + ":" + subQuery.toString());
                } else {
                        subQuery = null;
                }
                m.put(new Long(engine.value), this); // update this engine's topmost query
                //
                // here, we must check for a module prefis, e.g. jpl:jpl_modifier_bit(volatile,T)
                String module;
                Term goal;
                if (goal_.hasFunctor(":", 2)) {
                        if (goal_.arg(1).isAtom()) {
                                module = goal_.arg(1).name();
                        } else if (goal_.arg(1).isVariable()) {
                                throw new PrologException(Util.textParamsToTerm("error(instantiation_error,?)", new Term[] { goal_ }));
                        } else {
                                throw new PrologException(Util.textParamsToTerm("error(type_error(atom,?),?)", new Term[] { goal_.arg(1), goal_ }));
                        }
                        goal = goal_.arg(2);
                } else {
                        module = contextModule;
                        goal = goal_;
                }
                predicate = Prolog.predicate(goal.name(), goal.arity(), module); // was hostModule
                fid = Prolog.open_foreign_frame();
                Map varnames_to_vars = new Hashtable();
                term0 = Term.putTerms(varnames_to_vars, goal.args());
                // THINKS: invert varnames_to_Vars and use it when getting substitutions?
                qid = Prolog.open_query(Prolog.new_module(Prolog.new_atom(contextModule)), Prolog.Q_CATCH_EXCEPTION, predicate, term0);
                open = true;
                // called = false;
        }
        private final boolean get1() { // try to get the next solution; if none, close the query;
                if (Prolog.next_solution(qid)) {
                        // called = true; // OK to call get2()
                        return true;
                } else {
                        // if failure was due to throw/1, build exception term and throw it
                        term_t exception_term_t = Prolog.exception(qid);
                        if (exception_term_t.value != 0L) {
                                Term exception_term = Term.getTerm(new Hashtable(), exception_term_t);
                                close();
                                throw new PrologException(exception_term);
                        } else {
                                close();
                                return false;
                        }
                }
        }
        //------------------------------------------------------------------/
        // getSolution
        public synchronized final Hashtable getSolution() {
                // oughta check: thread has query's engine
                if (!open) {
                        throw new JPLException("Query is not open");
                } else if (get1()) {
                        return get2();
                } else {
                        return null;
                }
        }
        public synchronized final Hashtable getSubstWithNameVars() {
                // oughta check: thread has query's engine
                if (!open) {
                        throw new JPLException("Query is not open");
                } else if (get1()) {
                        return get2WithNameVars();
                } else {
                        return null;
                }
        }
        //------------------------------------------------------------------/
        // nextSolution
        public synchronized final Hashtable nextSolution() {
                return get2();
        }
        private final Hashtable get2() {
                if (!open) {
                        throw new JPLException("Query is not open");
                } else {
                        Hashtable substitution = new Hashtable();
                        // NB I reckon computeSubstitutions needn't be in Term (but where else?)
                        Term.getSubsts(substitution, new Hashtable(), goal_.args);
                        return substitution;
                }
        }
        // assumes that Query's last arg is a Variable which will be bound to a [Name=Var,..] dict
        private final Hashtable get2WithNameVars() {
                if (!open) {
                        throw new JPLException("Query is not open");
                } else {
                        Term[] args = goal_.args; // for slight convenience below
                        Term argNV = args[args.length - 1]; // the Query's last arg
                        String nameNV = ((Variable) argNV).name; // its name
                        // get the [Name=Var,..] dict from the last arg
                        Map varnames_to_Terms1 = new Hashtable();
                        Map vars_to_Vars1 = new Hashtable();
                        args[args.length - 1].getSubst(varnames_to_Terms1, vars_to_Vars1);
                        Hashtable varnames_to_Terms2 = new Hashtable();
                        Term nvs = (Term) varnames_to_Terms1.get(nameNV);
                        Map vars_to_Vars2 = Util.namevarsToMap(nvs);
                        for (int i = 0; i < args.length - 1; ++i) {
                                args[i].getSubst(varnames_to_Terms2, vars_to_Vars2);
                        }
                        return varnames_to_Terms2;
                }
        }
        //------------------------------------------------------------------/
        // hasMoreElements
        public synchronized final boolean hasMoreElements() {
                return hasMoreSolutions();
        }
        //------------------------------------------------------------------/
        // nextElement
        public synchronized final Object nextElement() {
                return nextSolution();
        }
        public synchronized final void rewind() {
                close();
        }
        public synchronized final void close() {
                if (!open) {
                        return; // it is not an error to attempt to close a closed Query
                }
                if (Prolog.thread_self() == -1) {
                        throw new JPLException("no engine is attached to this thread");
                }
                if (Prolog.current_engine().value != engine.value) {
                        throw new JPLException("this Query's engine is not that which is attached to this thread");
                }
                Query topmost = (Query) m.get(new Long(engine.value));
                if (topmost != this) {
                        throw new JPLException("this Query (" + this.hashCode() + ":" + this.toString() + ") is not topmost (" + topmost.hashCode() + ":" + topmost.toString() + ") within its engine["
                                        + engine.value + "]");
                }
                Prolog.close_query(qid);
                qid = null; // for tidiness
                jpl.fli.Prolog.discard_foreign_frame(fid);
                fid = null; // for tidiness
                m.remove(new Long(engine.value));
                if (subQuery == null) { // only Query open in this engine?
                        if (Prolog.current_engine_is_pool()) { // this (Query's) engine is from the pool?
                                Prolog.release_pool_engine();
                                // System.out.println("JPL releasing engine[" + engine.value + "]");
                        } else {
                                // System.out.println("JPL   leaving engine[" + engine.value + "]");
                        }
                } else {
                        m.put(new Long(engine.value), subQuery);
                        // System.out.println("JPL retaining engine[" + engine.value + "] popping subQuery(" + subQuery.hashCode() + ":" + subQuery.toString() + ")");
                }
                open = false; // this Query is now  closed
                engine = null; // this Query, being closed, is no longer associated with any Prolog engine
                subQuery = null; // this Query, being closed, is not stacked upon any other Query
        }
        public synchronized final Hashtable[] allSolutions() {
                if (open) {
                        throw new JPLException("Query is already open");
                } else {
                        // get a vector of solutions:
                        Vector v = new Vector();
                        while (hasMoreSolutions()) {
                                v.addElement(nextSolution());
                        }
                        // turn the vector into an array:
                        Hashtable solutions[] = new Hashtable[v.size()]; // 0 solutions -> Hashtable[0]
                        v.copyInto(solutions);
                        return solutions;
                }
        }
        public static final Hashtable[] allSolutions(Term goal) {
                return (new Query(goal)).allSolutions();
        }
        public static final Hashtable[] allSolutions(String text) {
                return (new Query(text)).allSolutions();
        }
        public static final Hashtable[] allSolutions(String text, Term[] params) {
                return (new Query(text, params)).allSolutions();
        }
        public synchronized final Hashtable[] nSolutions(long n) {
                if (open) {
                        throw new JPLException("Query is already open");
                } else {
                        // get a vector of solutions:
                        Vector v = new Vector();
                        for (long i = 0; i++ < n && hasMoreSolutions();) {
                                v.addElement(nextSolution());
                        }
                        // turn the vector into an array:
                        Hashtable solutions[] = new Hashtable[v.size()]; // 0 solutions -> Hashtable[0]
                        v.copyInto(solutions);
                        return solutions;
                }
        }
        public static final Hashtable[] nSolutions(Term goal, long n) {
                return (new Query(goal)).nSolutions(n);
        }
        public static final Hashtable[] nSolutions(String text, long n) {
                return (new Query(text)).nSolutions(n);
        }
        public static final Hashtable[] nSolutions(String text, Term[] params, long n) {
                return (new Query(text, params)).nSolutions(n);
        }
        public synchronized final Hashtable oneSolution() {
                if (open) {
                        throw new JPLException("Query is already open");
                } else {
                        Hashtable solution;
                        if (hasMoreSolutions()) {
                                solution = nextSolution();
                                close(); // safe, whether or not this is the only solution
                        } else {
                                solution = null;
                        }
                        return solution;
                }
        }
        public static final Hashtable oneSolution(Term goal) {
                return (new Query(goal)).oneSolution();
        }
        public static final Hashtable oneSolution(String text) {
                return (new Query(text)).oneSolution();
        }
        public static final Hashtable oneSolution(String text, Term[] params) {
                return (new Query(text, params)).oneSolution();
        }
        public synchronized final boolean query() {
                return oneSolution() != null;
        }
        public synchronized final boolean hasSolution() {
                return oneSolution() != null;
        }
        public static final boolean hasSolution(Term goal) {
                return (new Query(goal)).hasSolution();
        }
        public static final boolean hasSolution(String text) {
                return (new Query(text)).hasSolution();
        }
        public static final boolean hasSolution(String text, Term[] params) {
                return (new Query(text, params)).hasSolution();
        }
        //
        // this method doesn't work, but is intended to be called from another thread,
        // to abort a Query which is open and possibly currently executing nextSolution() or similar
        public final int abort() {
                if (open) {
                        (new Thread(new Runnable() {
                                public void run() {
                                        try {
                                                int rc1 = Prolog.attach_engine(engine);
                                                System.out.println("q.abort(): attach_engine() returns " + rc1);
                                                int rc2 = Prolog.action_abort();
                                                System.out.println("q.abort(): action_abort() returns " + rc2);
                                                // int rc3 = Prolog.release_pool_engine();
                                                // System.out.println("q.abort(): release_pool_engine() returns " + rc3);
                                        } catch (Exception e) {
                                        }
                                }
                        })).start(); // call the query in a separate thread
                        /*
                         int rc0a = Prolog.pool_engine_id(this.engine);
                         System.out.println("q.abort(): this.engine has id=" + rc0a);

                         engine_t e = Prolog.current_engine();
                         System.out.println("q.abort(): " + (e == null ? "no current engine" : "current engine id=" + Prolog.pool_engine_id(e)));

                         int rc0b = Prolog.release_pool_engine();
                         System.err.println("q.abort(): release_pool_engine() returns " + rc0b);

                         engine_t e2 = Prolog.current_engine();
                         System.out.println("q.abort(): " + (e == null ? "no current engine" : "current engine id=" + Prolog.pool_engine_id(e2)));

                         int rc1 = Prolog.attach_engine(this.engine);
                         System.out.println("q.abort(): attach_engine() returns " + rc1);

                         engine_t e3 = Prolog.current_engine();
                         System.out.println("q.abort(): " + (e == null ? "no current engine" : "current engine id=" + Prolog.pool_engine_id(e3)));

                         int rc2 = Prolog.action_abort();
                         System.out.println("q.abort(): action_abort() returns " + rc2);

                         int rc3 = Prolog.release_pool_engine();
                         System.out.println("q.abort(): release_pool_engine() returns " + rc3);

                         int rc4 = Prolog.attach_engine(e);
                         System.out.println("q.abort(): attach_engine() returns " + rc4);
                         */
                        return 0;
                } else {
                        System.out.println("q.abort(): query is not open");
                        return -1;
                }
        }
        //==================================================================/
        //  misc
        //==================================================================/
        public String toString() {
                return goal_.name + "( " + Term.toString(goal_.args) + " )";
        }
        //==================================================================/
        //  Methods (deprecated)
        //==================================================================/
        public String debugString() {
                return "(Query " + goal_.name + " " + Term.debugString(goal_.args) + ")";
        }
}

---

jpl
Author(s): Lorenz Moesenlechner
autogenerated on Fri Jan 11 09:40:29 2013