KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > sql > compile > Optimizable


1 /*
2
3    Derby - Class org.apache.derby.iapi.sql.compile.Optimizable
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.sql.compile;
23
24 import org.apache.derby.iapi.sql.dictionary.ConglomerateDescriptor;
25 import org.apache.derby.iapi.sql.dictionary.TableDescriptor;
26 import org.apache.derby.iapi.sql.dictionary.DataDictionary;
27
28 import org.apache.derby.iapi.error.StandardException;
29
30 import org.apache.derby.iapi.util.JBitSet;
31
32 import java.util.Properties JavaDoc;
33
34 /**
35  * Optimizable provides services for optimizing a table in a query.
36  */
37
38 public interface Optimizable {
39
40     /**
41      * Choose the next access path to evaluate for this Optimizable.
42      *
43      * @param optimizer Optimizer to use.
44      * @param predList The predicate list for this optimizable.
45      * The optimizer always passes null, and it is up
46      * to the optimizable object to pass along its
47      * own predicate list, if appropriate, when delegating
48      * this method.
49      * @param rowOrdering The row ordering for all the outer tables in
50      * the join order. This method will add the ordering
51      * of the next access path to the given RowOrdering.
52      *
53      * @return true means another access path was chosen, false means
54      * no more access paths to evaluate.
55      *
56      * @exception StandardException Thrown on error
57      */
58     boolean nextAccessPath(Optimizer optimizer,
59                             OptimizablePredicateList predList,
60                             RowOrdering rowOrdering)
61             throws StandardException;
62
63     /**
64      * Choose the best access path for this Optimizable.
65      *
66      * @param optimizer Optimizer to use.
67      * @param predList The predicate list to optimize against
68      * @param outerCost The CostEstimate for the outer tables in the join order,
69      * telling how many times this Optimizable will be scanned.
70      * @param rowOrdering The row ordering for all the tables in the
71      * join order, including this one.
72      *
73      * @return The optimizer's estimated cost of the best access path.
74      *
75      * @exception StandardException Thrown on error
76      */
77     CostEstimate optimizeIt(
78                     Optimizer optimizer,
79                     OptimizablePredicateList predList,
80                     CostEstimate outerCost,
81                     RowOrdering rowOrdering)
82                 throws StandardException;
83
84     /**
85      * Get the current access path under consideration for this Optimizable
86      */
87     AccessPath getCurrentAccessPath();
88
89     /**
90      * Get the best access path for this Optimizable.
91      */
92     AccessPath getBestAccessPath();
93
94     /**
95      * Get the best sort-avoidance path for this Optimizable.
96      */
97     AccessPath getBestSortAvoidancePath();
98
99     /**
100      * Get the best access path overall for this Optimizable.
101      */
102     AccessPath getTrulyTheBestAccessPath();
103
104     /**
105      * Mark this optimizable so that its sort avoidance path will be
106      * considered.
107      */
108     void rememberSortAvoidancePath();
109
110     /**
111      * Check whether this optimizable's sort avoidance path should
112      * be considered.
113      */
114     boolean considerSortAvoidancePath();
115
116     /**
117      * Remember the current join strategy as the best one so far in this
118      * join order.
119      */
120     void rememberJoinStrategyAsBest(AccessPath ap);
121
122     /**
123      * Get the table descriptor for this table (if any). Only base tables
124      * have table descriptors - for the rest of the optimizables, this
125      * method returns null.
126      */
127     TableDescriptor getTableDescriptor();
128
129     /**
130      * Get the map of referenced tables for this Optimizable.
131      *
132      * @return JBitSet Referenced table map.
133      */
134     JBitSet getReferencedTableMap();
135
136     /**
137      * Push an OptimizablePredicate down, if this node accepts it.
138      *
139      * @param optimizablePredicate OptimizablePredicate to push down.
140      *
141      * @return Whether or not the predicate was pushed down.
142      *
143      * @exception StandardException Thrown on error
144      */
145     boolean pushOptPredicate(OptimizablePredicate optimizablePredicate)
146             throws StandardException;
147
148     /**
149      * Pull all the OptimizablePredicates from this Optimizable and put them
150      * in the given OptimizablePredicateList.
151      *
152      * @param optimizablePredicates The list to put the pulled predicates
153      * in.
154      *
155      * @exception StandardException Thrown on error
156      */
157     void pullOptPredicates(OptimizablePredicateList optimizablePredicates)
158             throws StandardException;
159
160     /**
161      * Modify the access path for this Optimizable, as necessary. This includes
162      * things like adding a result set to translate from index rows to base rows
163      *
164      * @param outerTables Bit map of the tables that are outer to this one
165      * in the join order.
166      *
167      * @return The (potentially new) Optimizable at the top of the tree.
168      *
169      * @exception StandardException Thrown on error
170      */
171     Optimizable modifyAccessPath(JBitSet outerTables) throws StandardException;
172
173     /**
174      * Return whether or not this is a covering index. We expect to call this
175      * during generation, after access path selection is complete.
176      *
177      * @param cd ConglomerateDesriptor for index to consider
178      *
179      * @return boolean Whether or not this is a covering index.
180      *
181      * @exception StandardException Thrown on error
182      */
183     public boolean isCoveringIndex(ConglomerateDescriptor cd) throws StandardException;
184
185     /**
186      * Get the Properties list, if any, associated with this optimizable.
187      *
188      * @return The Properties list, if any, associated with this optimizable.
189      */
190     public Properties JavaDoc getProperties();
191
192     /**
193      * Set the Properties list for this optimizalbe.
194      *
195      * @param tableProperties The Properties list for this optimizable.
196      */
197     public void setProperties(Properties JavaDoc tableProperties);
198
199     /**
200      * Verify that the Properties list with optimizer overrides, if specified, is valid
201      *
202      * @param dDictionary The DataDictionary to use.
203      *
204      * @exception StandardException Thrown on error
205      */
206     public void verifyProperties(DataDictionary dDictionary) throws StandardException;
207
208     /**
209      * Get the (exposed) name of this Optimizable
210      *
211      * @return The name of this Optimizable.
212      * @exception StandardException Thrown on error
213      */
214     public String JavaDoc getName() throws StandardException;
215
216     /**
217      * Get the table name of this Optimizable. Only base tables have
218      * table names (by the time we use this method, all views will have
219      * been resolved).
220      */
221     public String JavaDoc getBaseTableName();
222
223     /**
224      * Convert an absolute to a relative 0-based column position.
225      * This is useful when generating qualifiers for partial rows
226      * from the store.
227      *
228      * @param absolutePosition The absolute 0-based column position for the column.
229      *
230      * @return The relative 0-based column position for the column.
231      */
232     public int convertAbsoluteToRelativeColumnPosition(int absolutePosition);
233
234     /**
235      * When remembering "truly the best" access path for an Optimizable, we
236      * have to keep track of which OptimizerImpl the "truly the best" access
237      * is for. In most queries there will only be one OptimizerImpl in
238      * question, but in cases where there are nested subqueries, there will be
239      * one OptimizerImpl for every level of nesting, and each OptimizerImpl
240      * might have its own idea of what this Optimizable's "truly the best path"
241      * access path really is. In addition, there could be Optimizables
242      * above this Optimizable that might need to override the best path
243      * chosen during optimization. So whenever we save a "truly the best" path,
244      * we take note of which Optimizer/Optimizable told us to do so. Then
245      * as each level of subquery finishes optimization, the corresponding
246      * OptimizerImpl/Optimizable can load its preferred access path into this
247      * Optimizable's trulyTheBestAccessPath field and pass it up the tree, until
248      * eventually the outer-most OptimizerImpl can choose to either use the best
249      * path that it received from below (by calling "rememberAsBest()") or else
250      * use the path that it found to be "best" for itself.
251      *
252      * This method is what allows us to keep track of which OptimizerImpl or
253      * Optimizable saved which "best plan", and allows us to load the
254      * appropriate plans after each round of optimization.
255      *
256      * @param action Indicates whether we're adding, loading, or removing
257      * a best plan for the OptimizerImpl/Optimizable.
258      * @param planKey Object to use as the map key when adding/looking up
259      * a plan. If it is an instance of OptimizerImpl then it corresponds
260      * to an outer query; otherwise it's some Optimizable above this
261      * Optimizable that could potentially reject plans chosen by the
262      * OptimizerImpl to which this Optimizable belongs.
263      */
264     public void updateBestPlanMap(short action,
265         Object JavaDoc planKey) throws StandardException;
266
267     /**
268      * Remember the current access path as the best one (so far).
269      *
270      * @param planType The type of plan (one of Optimizer.NORMAL_PLAN
271      * or Optimizer.SORT_AVOIDANCE_PLAN)
272      * @param optimizer The OptimizerImpl that is telling this Optimizable
273      * to remember its current path as "truly the best".
274      *
275      * @exception StandardException thrown on error.
276      */
277     public void rememberAsBest(int planType, Optimizer optimizer)
278         throws StandardException;
279
280     /**
281      * Begin the optimization process for this Optimizable. This can be
282      * called many times for an Optimizable while optimizing a query -
283      * it will typically be called every time the Optimizable is placed
284      * in a potential join order.
285      */
286     public void startOptimizing(Optimizer optimizer, RowOrdering rowOrdering);
287
288     /**
289      * Estimate the cost of scanning this Optimizable using the given
290      * predicate list with the given conglomerate. It is assumed that the
291      * predicate list has already been classified. This cost estimate is
292      * just for one scan, not for the life of the query.
293      *
294      * @see OptimizablePredicateList#classify
295      *
296      * @param predList The predicate list to optimize against
297      * @param cd The conglomerate descriptor to get the cost of
298      * @param outerCost The estimated cost of the part of the plan outer
299      * to this optimizable.
300      * @param optimizer The optimizer to use to help estimate the cost
301      * @param rowOrdering The row ordering for all the tables in the
302      * join order, including this one.
303      *
304      * @return The estimated cost of doing the scan
305      *
306      * @exception StandardException Thrown on error
307      */
308     CostEstimate estimateCost(OptimizablePredicateList predList,
309                                 ConglomerateDescriptor cd,
310                                 CostEstimate outerCost,
311                                 Optimizer optimizer,
312                                 RowOrdering rowOrdering)
313                     throws StandardException;
314
315     /** Tell whether this Optimizable represents a base table */
316     boolean isBaseTable();
317
318     /** Tell whether this Optimizable is materializable
319      *
320      * @exception StandardException Thrown on error
321      */
322     boolean isMaterializable() throws StandardException;
323
324     /** Tell whether this Optimizable can be instantiated multiple times */
325     boolean supportsMultipleInstantiations();
326
327     /** Get this Optimizable's result set number */
328     int getResultSetNumber();
329
330     /** Get this Optimizable's table number */
331     int getTableNumber();
332
333     /** Return true if this Optimizable has a table number */
334     boolean hasTableNumber();
335
336     /** Return true if this is the target table of an update */
337     public boolean forUpdate();
338
339     /** Return the initial capacity of the hash table, for hash join strategy */
340     public int initialCapacity();
341
342     /** Return the load factor of the hash table, for hash join strategy */
343     public float loadFactor();
344
345     /** Return the hash key column numbers, for hash join strategy */
346     public int[] hashKeyColumns();
347
348     /** Set the hash key column numbers, for hash join strategy */
349     public void setHashKeyColumns(int[] columnNumbers);
350
351     /**
352      * Is the current proposed join strategy for this optimizable feasible
353      * given the predicate list?
354      *
355      * @param predList The predicate list that has been pushed down to
356      * this optimizable
357      * @param optimizer The optimizer to use.
358      *
359      * @return true means feasible
360      *
361      * @exception StandardException Thrown on error
362      */
363     public boolean feasibleJoinStrategy(OptimizablePredicateList predList,
364                                         Optimizer optimizer)
365             throws StandardException;
366
367     /**
368      * @param rowCount
369      * @param maxMemoryPerTable
370      * @return true if the memory usage of the proposed access path is OK, false if not.
371      *
372      * @exception StandardException standard error policy
373      */
374     public boolean memoryUsageOK( double rowCount, int maxMemoryPerTable)
375             throws StandardException;
376
377     /**
378      * Return the maximum capacity of the hash table, for hash join strategy
379      *
380      * @param maxMemoryPerTable The maximum number of bytes to be used. Ignored if the user has set a maximum
381      * number of rows for the Optimizable.
382      *
383      * @exception StandardException Standard error policy
384      */
385     public int maxCapacity( JoinStrategy joinStrategy, int maxMemoryPerTable) throws StandardException;
386
387     /**
388      * Can this Optimizable appear at the current location in the join order.
389      * In other words, have the Optimizable's dependencies been satisfied?
390      *
391      * @param assignedTableMap The tables that have been placed so far in the join order.
392      *
393      * @return Where or not this Optimizable can appear at the current location in the join order.
394      */
395     public boolean legalJoinOrder(JBitSet assignedTableMap);
396
397     /**
398      * Get the DataDictionary from this Optimizable. This is useful for code generation
399      * because we need to get the constraint name if scanning a back index so that
400      * RunTimeStatistics can display the correct info.
401      *
402      * @return The DataDictionary to use.
403      *
404      * @exception StandardException Thrown on error
405      */
406     public DataDictionary getDataDictionary() throws StandardException;
407
408     /**
409      * Is the optimizable the target table of an update or delete?
410      *
411      * @return Whether or not the optimizable the target table of an update or delete.
412      */
413     public boolean isTargetTable();
414
415     /**
416      * Get the number of the number of columns returned by this Optimizable.
417      *
418      * @return The number of the number of columns returned by this Optimizable.
419      */
420     public int getNumColumnsReturned();
421
422     /**
423      * Will the optimizable return at most 1 row per scan?
424      *
425      * @return Whether or not the optimizable will return at most 1 row per scan?
426      *
427      * @exception StandardException Thrown on error
428      */
429     public boolean isOneRowScan() throws StandardException;
430
431     /**
432      * Init the access paths for this optimizable.
433      *
434      * @param optimizer The optimizer being used.
435      */
436     public void initAccessPaths(Optimizer optimizer);
437
438     /**
439      * Does this optimizable have a uniqueness condition on the
440      * given predicate list, and if so, how many unique keys will be
441      * returned per scan.
442      *
443      * @param predList The predicate list to check
444      *
445      * @return <= 0 means there is no uniqueness condition
446      * > 0 means there is a uniqueness condition,
447      * and the return value is the number of rows per scan.
448      *
449      * @exception StandardException Thrown on error
450      */
451     public double uniqueJoin(OptimizablePredicateList predList)
452                                 throws StandardException;
453 }
454
Popular Tags