KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > access > Qualifier


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.access.Qualifier
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.store.access;
23
24 import org.apache.derby.iapi.types.DataValueDescriptor;
25
26 import org.apache.derby.iapi.error.StandardException;
27
28 /**
29   <p>
30   A structure which is used to "qualify" a column. Specifies
31   that the column value in a given column identified by column
32   id is to be compared via a specific operator to a particular
33   DataValueDescriptor value.
34   <p>
35   The implementation of this interface is provided by the client;
36   the methods of Qualifier are the methods the access code uses to use it.
37   <p>
38   Arrays of qualifiers are provided to restrict the rows
39   returned by scans. A row is returned from a scan if all qualifications
40   in the array return true.
41   <p>
42   A qualification returns true if in the following pseudo-code compare_result
43   is true.
44   <p>
45   <blockquote><pre>
46   if (qualifier.negateCompareResult())
47   {
48       compare_result =
49       row[(qualifier.getColumnId())].compare(
50         qualifier.getOperator(),
51         qualifier.getOrderable(),
52         qualifier.getOrderedNulls(),
53         qualifier.getUnknownRV())
54       if (qualifier.negateCompareResult())
55       {
56           compare_result = !(compare_result);
57       }
58   }
59   </blockquote></pre>
60   <p>
61   Qualifiers are often passed through interfaces as a set of Qualifiers,
62   rather than one at a time, for example see the qualifier argument in
63   TransactionController.openScan().
64   <p>
65   To make this consistent the following protocols are to be used when passing
66   around sets of Qualifiers.
67   <p>
68   A single dimensional array is to be used to pass around a set of AND'd
69   qualifiers. Thus qualifier[] argument is to be treated as:
70   <blockquote><pre>
71       qualifier[0] AND qualifer[1] ... AND qualifier[qualifer.length - 1]
72   </blockquote></pre>
73   <p>
74   A two dimensional array is to be used to pass around a AND's and OR's in
75   conjunctive normal form. The top slot of the 2 dimensional array is optimized
76   for the more frequent where no OR's are present. The first array slot is
77   always a list of AND's to be treated as described above for single dimensional
78   AND qualifier arrays. The subsequent slots are to be treated as AND'd arrays
79   of OR's. Thus the 2 dimensional array qual[][] argument is to be treated as
80   the following, note if qual.length = 1 then only the first array is valid and
81   it is and an array of AND clauses:
82   <blockquote><pre>
83   (qual[0][0] AND qual[0][0] ... AND qual[0][qual[0].length - 1])
84   AND
85   (qual[1][0] OR qual[1][1] ... OR qual[1][qual[1].length - 1])
86   AND
87   (qual[2][0] OR qual[2][1] ... OR qual[2][qual[2].length - 1])
88   ...
89   AND (qual[qual.length - 1][0] OR qual[1][1] ... OR qual[1][2])
90   </blockquote></pre>
91   <p>
92   If any of the array's qual[0].length ... qual[qual.length -1] are 0 length
93   they will be evaluated as TRUE; but they must be not NULL. See Example 4 for
94   encoding of (a or b) that takes advantage of this.
95   <p>
96   Note that any of the arrays qual[0].length ... qual[qual.length -1] may also
97   be of length 1, thus no guarantee is made the presence of OR
98   predicates if qual.length > 1. See example 1a.
99   <p>
100   The following give pseudo-code examples of building Qualifier arrays:
101   <p>
102   Example 1: "a AND b AND c"
103   <blockquote><pre>
104     qualifier = new Qualifier[1][3]; // 3 AND clauses
105
106     qualifier[0][0] = a
107     qualifier[0][1] = b
108     qualifier[0][2] = c
109   </blockquote></pre>
110   <p>
111   Example 1a "a AND b AND c" - less efficient than example 1 but legal
112   <blockquote><pre>
113     qualifier = new Qualifier[3]; // 3 AND clauses
114     qualifier[0] = new Qualifier[1];
115     qualifier[1] = new Qualifier[1];
116     qualifier[2] = new Qualifier[1];
117     
118     qualifier[0][0] = a
119     qualifier[1][0] = b
120     qualifier[2][0] = c
121   </blockquote></pre>
122   <p>
123   Example 2: "(f) AND (a OR b) AND (c OR d OR e)"
124     Would be represented by an array that looks like the following:
125   <blockquote><pre>
126     qualifier = new Qualifier[3]; // 3 and clauses
127     qualifier[0] = new Qualifier[1]; // to be intitialized to f
128     qualifier[1] = new Qualifier[2]; // to be initialized to (a OR b)
129     qualifier[2] = new Qualifier[3]; // to be initialized to (c OR d OR e)
130
131     qualifier[0][0] = f
132     qualifier[1][0] = a
133     qualifier[1][1] = b
134     qualifier[2][0] = c
135     qualifier[2][1] = d
136     qualifier[2][2] = e
137   </blockquote></pre>
138   <p>
139   Example 3: "(a OR b) AND (c OR d) AND (e OR f)"
140   <blockquote><pre>
141     qualifier = new Qualifier[3]; // 3 and clauses
142     qualifier = new Qualifier[4]; // 4 and clauses
143     qualifier[0] = new Qualifier[1]; // to be intitialized to TRUE
144     qualifier[1] = new Qualifier[2]; // to be initialized to (a OR b)
145     qualifier[2] = new Qualifier[2]; // to be initialized to (c OR d)
146     qualifier[3] = new Qualifier[2]; // to be initialized to (e OR f)
147
148     qualifier[0][0] = TRUE
149     qualifier[1][0] = a
150     qualifier[1][1] = b
151     qualifier[2][0] = c
152     qualifier[2][1] = d
153     qualifier[3][0] = e
154     qualifier[3][1] = f
155   </blockquote></pre>
156   <p>
157   Example 4: "(a OR b)"
158   <blockquote><pre>
159     qualifier = new Qualifier[2]; // 2 and clauses
160     qualifier[0] = new Qualifier[0]; // 0 length array is TRUE
161     qualifier[1] = new Qualifier[2]; // to be initialized to (a OR b)
162
163     qualifier[1][0] = a
164     qualifier[1][1] = b
165   </blockquote></pre>
166
167   @see ScanController
168   @see TransactionController#openScan
169   @see DataValueDescriptor#compare
170 **/
171
172
173 public interface Qualifier
174 {
175
176     /**
177      * The DataValueDescriptor can be 1 of 4 types:<ul>
178      * <li> VARIANT - cannot be cached as its value can vary
179      * within a scan</li>
180      * <li> SCAN_INVARIANT - can be cached within a scan as its value
181      * will not change within a scan </li>
182      * <li> QUERY_INVARIANT- can be cached across the life of the query
183      * as its value will never change </li>
184      * <li> CONSTANT - can be cached across executions. </li></ul>
185      * <p>
186      * <b>NOTE</b>: the following is guaranteed: <i>
187      * VARIANT < SCAN_INVARIANT < QUERY_INVARIANT < CONSTANT
188      */
189     public static final int VARIANT = 0;
190     public static final int SCAN_INVARIANT = 1;
191     public static final int QUERY_INVARIANT = 2;
192     public static final int CONSTANT = 3;
193
194     /**
195      * Get the (zero based) id of the column to be qualified.
196      * <p>
197      * This id is the column number of the column in the table, no matter
198      * whether a partial column set is being retrieved by the actual fetch.
199      * Note that the column being specified in the qualifier must appear in
200      * the column list being fetched.
201      **/
202     int getColumnId();
203
204     /**
205      * Get the value that the column is to be compared to.
206      *
207      * @exception StandardException Thrown on error
208      */
209     DataValueDescriptor getOrderable() throws StandardException;
210
211     /** Get the operator to use in the comparison.
212      *
213      * @see DataValueDescriptor#compare
214      **/
215     int getOperator();
216
217     /** Determine if the result from the compare operation should be negated.
218      * If true then only rows which fail the compare operation will qualify.
219      *
220      * @see DataValueDescriptor#compare
221      **/
222     boolean negateCompareResult();
223
224     /** Get the getOrderedNulls argument to use in the comparison.
225      *
226      * @see DataValueDescriptor#compare
227      **/
228     boolean getOrderedNulls();
229
230     /** Get the getOrderedNulls argument to use in the comparison.
231      *
232      * @see DataValueDescriptor#compare
233      **/
234     boolean getUnknownRV();
235
236     /** Clear the DataValueDescriptor cache, if one exists.
237      * (The DataValueDescriptor can be 1 of 3 types:
238      * o VARIANT - cannot be cached as its value can
239      * vary within a scan
240      * o SCAN_INVARIANT - can be cached within a scan as its
241      * value will not change within a scan
242      * o QUERY_INVARIANT- can be cached across the life of the query
243      * as its value will never change
244      */
245     void clearOrderableCache();
246
247
248     /**
249      * This method reinitializes all the state of
250      * the Qualifier. It is used to distinguish between
251      * resetting something that is query invariant
252      * and something that is constant over every
253      * execution of a query. Basically, clearOrderableCache()
254      * will only clear out its cache if it is a VARIANT
255      * or SCAN_INVARIANT value. However, each time a
256      * query is executed, the QUERY_INVARIANT qualifiers need
257      * to be reset.
258      */
259     void reinitialize();
260 }
261
Popular Tags