1 /*********************************************************************
2 Copyright 2012, Ralph Ronnquist.
4 This file is part of GORITE.
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.
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.
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 **********************************************************************/
20 package com.intendico.data;
22 import java.util.Observer;
23 import java.util.Vector;
26 * The Query interface defines methods for query processing, to
27 * support left-to-right short-cut evaluation with multiple bindings.
29 * <p>The sequence for query processing would typically be as follows:
32 * <li> create the {@link Ref} objects to carry query outputs and
33 * intermediate values between query conjuncts;
35 * <li> create the query object structure;
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
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;
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.
53 * <li> (optionally) remove the observer previosuly added.
57 * <p> The following snippet is an illustration:
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" );
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 );
72 public interface Query {
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
80 public void reset() throws Exception;
83 * The next() method is invoked in order for the Query to
84 * establish the next binding in its output.
86 public boolean next() throws Exception;
89 * The getRefs() method is invoked in order for the Query to
90 * collect and report all its Ref objects.
92 public Vector/*<Ref>*/ getRefs(Vector/*<Ref>*/ v);
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.
99 public Query copy(Vector/*<Ref>*/ newrefs) throws Exception;
102 * The addObserver method is invoked for the purpose of adding a
103 * Query processor to the observable source(s) of the query.
105 public void addObserver(Observer x);
108 * The deleteObserver method is invoked by the Query processor in
109 * order to "detach" from the observable Query source(s).
111 public void deleteObserver(Observer x);
114 * The addable method is invoked with bound {@link Ref} objects to
115 * ask whether these bindings could be added.
117 public boolean addable();
120 * The add method is invoked with bound {@link Ref} objects in
121 * order to add the current combination to all query sources, if
124 * @return <em>true</em> if any source element was updated, and
125 * <em>false</em> otherwise.
127 public boolean add();
130 * The removable method is invoked with bound {@link Ref} objects
131 * to ask whether these bindings could be removed.
133 public boolean removable();
136 * The remove method is invoked with bound {@link Ref} objects in
137 * order to remove the current combination to query sources.
139 * @return <em>true</em> if any source element was updated, and
140 * <em>false</em> otherwise.
142 public boolean remove();