KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2
3    Derby - Class org.apache.derby.iapi.sql.compile.JoinStrategy
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.DataDictionary;
25 import org.apache.derby.iapi.sql.dictionary.ConglomerateDescriptor;
26
27 import org.apache.derby.iapi.store.access.TransactionController;
28
29 import org.apache.derby.iapi.services.compiler.MethodBuilder;
30
31 import org.apache.derby.iapi.error.StandardException;
32
33 /**
34  * A JoinStrategy represents a strategy like nested loop, hash join,
35  * merge join, etc. It tells the optimizer whether the strategy is
36  * feasible in a given situation, how much the strategy costs, whether
37  * the strategy requires the data from the source result sets to be ordered,
38  * etc.
39  */

40
41 public interface JoinStrategy {
42     /**
43      * Is this join strategy feasible under the circumstances?
44      *
45      * @param innerTable The inner table of the join
46      * @param predList The predicateList for the join
47      * @param optimizer The optimizer to use
48      *
49      * @return true means the strategy is feasible, false means it isn't
50      *
51      * @exception StandardException Thrown on error
52      */

53     boolean feasible(Optimizable innerTable,
54                      OptimizablePredicateList predList,
55                      Optimizer optimizer
56                      )
57             throws StandardException;
58
59     /**
60      * Is it OK to use bulk fetch with this join strategy?
61      */

62     boolean bulkFetchOK();
63
64     /**
65      * Should we just ignore bulk fetch with this join strategy?
66      */

67     boolean ignoreBulkFetch();
68
69     /**
70      * Returns true if the base cost of scanning the conglomerate should be
71      * multiplied by the number of outer rows.
72      */

73     boolean multiplyBaseCostByOuterRows();
74
75     /**
76      * Get the base predicates for this join strategy. The base predicates
77      * are the ones that can be used while scanning the table. For some
78      * join strategies (for example, nested loop), all predicates are base
79      * predicates. For other join strategies (for example, hash join),
80      * the base predicates are those that involve comparisons with constant
81      * expressions.
82      *
83      * Also, order the base predicates according to the order in the
84      * proposed conglomerate descriptor for the inner table.
85      *
86      * @param predList The predicate list to pull from.
87      * @param basePredicates The list to put the base predicates in.
88      * @param innerTable The inner table of the join
89      *
90      * @return The base predicate list. If no predicates are pulled,
91      * it may return the source predList without doing anything.
92      *
93      * @exception StandardException Thrown on error
94      */

95     OptimizablePredicateList getBasePredicates(
96                                 OptimizablePredicateList predList,
97                                 OptimizablePredicateList basePredicates,
98                                 Optimizable innerTable)
99                         throws StandardException;
100
101     /**
102      * Get the extra selectivity of the non-base predicates (those that were
103      * left in the predicate list by getBasePredicates() that are not
104      * applied to the scan of the base conglomerate.
105      *
106      * NOTE: For some types of join strategy, it may not remove any predicates
107      * from the original predicate list. The join strategy is expected to
108      * know when it does this, and to return 1.0 as the extra selectivity
109      * in these cases.
110      *
111      * @param innerTable The inner table of the join.
112      * @param predList The original predicate list that was passed to
113      * getBasePredicates(), from which some base predicates
114      * may have been pulled.
115      *
116      * @return The extra selectivity due to non-base predicates
117      */

118     double nonBasePredicateSelectivity(Optimizable innerTable,
119                                         OptimizablePredicateList predList)
120     throws StandardException;
121
122     /**
123      * Put back and base predicates that were removed from the list by
124      * getBasePredicates (see above).
125      *
126      * NOTE: Those join strategies that treat all predicates as base
127      * predicates may treat the get and put methods as no-ops.
128      *
129      * @param predList The list of predicates to put the base predicates
130      * back in.
131      * @param basePredicates The base predicates to put back in the list.
132      *
133      * @exception StandardException Thrown on error
134      */

135     void putBasePredicates(OptimizablePredicateList predList,
136                             OptimizablePredicateList basePredicates)
137                     throws StandardException;
138     /**
139      * Get the estimated cost for the join.
140      *
141      * @param predList The predicate list for the join
142      * @param innerTable The inner table to join with
143      * @param cd The conglomerate descriptor (if appropriate) to get
144      * the cost of
145      * @param outerCost The estimated cost of the part of the plan outer
146      * to the inner table
147      * @param optimizer The optimizer to use to help estimate the cost
148      * @param costEstimate The estimated cost of doing a single scan of the
149      * inner table, to be filled in with the cost of
150      * doing the join.
151      *
152      * @exception StandardException Thrown on error
153      */

154     void estimateCost(Optimizable innerTable,
155                         OptimizablePredicateList predList,
156                         ConglomerateDescriptor cd,
157                         CostEstimate outerCost,
158                         Optimizer optimizer,
159                         CostEstimate costEstimate)
160         throws StandardException;
161
162     /**
163      * @param userSpecifiedCapacity
164      * @param maxMemoryPerTable maximum number of bytes per table
165      * @param perRowUsage number of bytes per row
166      *
167      * @return The maximum number of rows that can be handled by this join strategy
168      */

169     public int maxCapacity( int userSpecifiedCapacity,
170                             int maxMemoryPerTable,
171                             double perRowUsage);
172     
173     /** Get the name of this join strategy */
174     String JavaDoc getName();
175
176     /** Get the costing type, for use with StoreCostController.getScanCost */
177     int scanCostType();
178
179     /**
180      * Get the name of the result set method for base table scans
181      *
182      * @param bulkFetch True means bulk fetch is being done on the inner
183      * table
184      */

185     String JavaDoc resultSetMethodName(boolean bulkFetch);
186
187     /**
188      * Get the name of the join result set method for the join
189      */

190     String JavaDoc joinResultSetMethodName();
191
192     /**
193      * Get the name of the join result set method for the half outerjoin
194      */

195     String JavaDoc halfOuterJoinResultSetMethodName();
196
197     /**
198      * Get the appropriate arguments to the scan for this type of join.
199      *
200      * @param tc The TransactionController
201      * @param mb The method to generate the arguments in
202      * @param innerTable The inner table of the join
203      * @param storeRestrictionList The predicate list to be evaluated in the
204      * store
205      * @param nonStoreRestrictionList The predicate list to be evaluated
206      * outside of the store
207      * @param acb The expression class builder for the activation class
208      * we're building
209      * @param bulkFetch The amount of bulk fetch to do
210      * @param resultRowAllocator A completed method to allocate the result row
211      * @param colRefItem The item number of the column reference bit map
212      * @param lockMode The lock mode to use when scanning the table
213      * (see TransactionController).
214      * @param tableLocked Whether or not the table is marked (in sys.systables)
215      * as always using table locking
216      * @param isolationLevel Isolation level specified (or not) for scans
217      * @param maxMemoryPerTable Max memory per table
218      *
219      * @return Count of the expressions pushed to use as the parameters to the
220      * result set for the inner table
221      *
222      * @exception StandardException Thrown on error
223      */

224     int getScanArgs(TransactionController tc,
225                             MethodBuilder mb,
226                             Optimizable innerTable,
227                             OptimizablePredicateList storeRestrictionList,
228                             OptimizablePredicateList nonStoreRestrictionList,
229                             ExpressionClassBuilderInterface acb,
230                             int bulkFetch,
231                             MethodBuilder resultRowAllocator,
232                             int colRefItem,
233                             int indexColItem,
234                             int lockMode,
235                             boolean tableLocked,
236                             int isolationLevel,
237                             int maxMemoryPerTable
238                             )
239                     throws StandardException;
240
241     /**
242      * Divide up the predicates into different lists for different phases
243      * of the operation. When this method is called, all of the predicates
244      * will be in restrictionList. The effect of this method is to
245      * remove all of the predicates from restrictionList except those that
246      * will be pushed down to the store as start/stop predicates or
247      * Qualifiers. The remaining predicates will be put into
248      * nonBaseTableRestrictionList.
249      *
250      * All predicate lists will be ordered as necessary for use with
251      * the conglomerate.
252      *
253      * Some operations (like hash join) materialize results, and so
254      * require requalification of rows when doing a non-covering index
255      * scan. The predicates to use for requalification are copied into
256      * baseTableRestrictionList.
257      *
258      * @param innerTable The inner table of the join
259      * @param originalRestrictionList Initially contains all predicates.
260      * This method removes predicates from
261      * this list and moves them to other
262      * lists, as appropriate.
263      * @param storeRestrictionList To be filled in with predicates to
264      * be pushed down to store.
265      * @param nonStoreRestrictionList To be filled in with predicates
266      * that are not pushed down to the
267      * store.
268      * @param requalificationRestrictionList Copy of predicates used to
269      * re-qualify rows, if necessary.
270      * @param dd The DataDictionary
271      *
272      * @exception StandardException Thrown on error
273      */

274     void divideUpPredicateLists(
275                         Optimizable innerTable,
276                         OptimizablePredicateList originalRestrictionList,
277                         OptimizablePredicateList storeRestrictionList,
278                         OptimizablePredicateList nonStoreRestrictionList,
279                         OptimizablePredicateList requalificationRestrictionList,
280                         DataDictionary dd)
281                 throws StandardException;
282
283     /**
284      * Is this a form of hash join?
285      *
286      * @return Whether or not this strategy is a form
287      * of hash join.
288      */

289     public boolean isHashJoin();
290
291     /**
292      * Is materialization built in to the join strategy?
293      *
294      * @return Whether or not materialization is built in to the join strategy
295      */

296     public boolean doesMaterialization();
297 }
298
Popular Tags