com/intendico/data/Query.java

   1 /*********************************************************************
   2 Copyright 2012, Ralph Ronnquist.
   3
   4 This file is part of GORITE.
   5
   6 GORITE is free software: you can redistribute it and/or modify it
   7 under the terms of the Lesser GNU General Public License as published
   8 by the Free Software Foundation, either version 3 of the License, or
   9 (at your option) any later version.
  10
  11 GORITE is distributed in the hope that it will be useful, but WITHOUT
  12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  14 License for more details.
  15
  16 You should have received a copy of the Lesser GNU General Public
  17 License along with GORITE.  If not, see <http://www.gnu.org/licenses/>.
  18 **********************************************************************/
  19
  20 package com.intendico.data;
  21
  22 import java.util.Observer;
  23 import java.util.Vector;
  24
  25 /**
  26  * The Query interface defines methods for query processing, to
  27  * support left-to-right short-cut evaluation with multiple bindings.
  28  *
  29  * <p>The sequence for query processing would typically be as follows:
  30  * <ol>
  31  *
  32  * <li> create the {@link Ref} objects to carry query outputs and
  33  * intermediate values between query conjuncts;
  34  *
  35  * <li> create the query object structure;
  36  *
  37  * <li> (optionally) add an observer on the query, in order to
  38  * capture triggerring from the source elements. This is only needed
  39  * when the following query processing is deferred or temporal in some
  40  * fashion;
  41  *
  42  * <li> invoke the {@link #reset} method. Most {@link Query}
  43  * implementations include an automatic intital {@link #reset}, and
  44  * therefore this call would only be needed at a second or subsequent
  45  * use of the query object structure;
  46  *
  47  * <li> invoke the {@link #next} method. The first invokation
  48  * establishes the first valid combination of bindings for the {@link
  49  * Ref} objects involved, and subsequent calls establish subsequent
  50  * valid bindings. The {@link #next} method returns <i>false</i> when
  51  * it exhausts the vlid combinations of bindings.
  52  *
  53  * <li> (optionally) remove the observer previosuly added.
  54  *
  55  * </ol>
  56  *
  57  * <p> The following snippet is an illustration:
  58  * <pre>
  59  * Relation r = new Relation( "parent", String.class, String.class );
  60  * Ref<String> p = new Ref<String>( "$parent" );
  61  * Ref<String> pc = new Ref<String>( "$child_parent" );
  62  * Ref<String> c = new Ref<String>( "$child" );
  63  *
  64  * Query grandparent = new And( r.get( p, ch ), r.get( ch, c ) );
  65  * while ( grandparent.next() ) {
  66  *     // Here r, pc and c have a valid combination of bindings
  67  *     System.out.println( p + " is grand parent of " + c );
  68  * }
  69  *
  70  * </pre>
  71  */
  72 public interface Query {
  73
  74     /**
  75      * The reset() method is invoked in order for the Query to renew
  76      * itself, and provide its binding sequence from the top. The
  77      * Query should renew itself with regard to any changes in the
  78      * input.
  79      */
  80     public void reset() throws Exception;
  81
  82     /**
  83      * The next() method is invoked in order for the Query to
  84      * establish the next binding in its output.
  85      */
  86     public boolean next() throws Exception;
  87
  88     /**
  89      * The getRefs() method is invoked in order for the Query to
  90      * collect and report all its Ref objects.
  91      */
  92     public Vector/*<Ref>*/ getRefs(Vector/*<Ref>*/ v);
  93
  94     /**
  95      * The copy method is invoked for the purpose of obtaining a deep
  96      * copy of a query, and in particular using new {@link Ref}
  97      * objects by the original names.
  98      */
  99     public Query copy(Vector/*<Ref>*/ newrefs) throws Exception;
 100
 101     /**
 102      * The addObserver method is invoked for the purpose of adding a
 103      * Query processor to the observable source(s) of the query.
 104      */
 105     public void addObserver(Observer x);
 106
 107     /**
 108      * The deleteObserver method is invoked by the Query processor in
 109      * order to "detach" from the observable Query source(s).
 110      */
 111     public void deleteObserver(Observer x);
 112
 113     /**
 114      * The addable method is invoked with bound {@link Ref} objects to
 115      * ask whether these bindings could be added.
 116      */
 117     public boolean addable();
 118
 119     /**
 120      * The add method is invoked with bound {@link Ref} objects in
 121      * order to add the current combination to all query sources, if
 122      * possible.
 123      *
 124      * @return <em>true</em> if any source element was updated, and
 125      * <em>false</em> otherwise.
 126      */
 127     public boolean add();
 128
 129     /**
 130      * The removable method is invoked with bound {@link Ref} objects
 131      * to ask whether these bindings could be removed.
 132      */
 133     public boolean removable();
 134
 135     /**
 136      * The remove method is invoked with bound {@link Ref} objects in
 137      * order to remove the current combination to query sources.
 138      *
 139      * @return <em>true</em> if any source element was updated, and
 140      * <em>false</em> otherwise.
 141      */
 142     public boolean remove();
 143
 144 }