KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.access.SortCostController
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.error.StandardException;
25
26 import org.apache.derby.iapi.types.DataValueDescriptor;
27
28 /**
29
30 The SortCostController interface provides methods that an access client
31 (most likely the system optimizer) can use to get sorter's estimated cost of
32 various operations on the SortController.
33 <p>
34 @see TransactionController#openSortCost
35 @see TransactionController#createSort
36 @see RowCountable
37
38 **/
39
40 import java.util.Properties JavaDoc;
41
42 public interface SortCostController
43 {
44     /**
45      * Close the controller.
46      * <p>
47      * Close the open controller. This method always succeeds, and never
48      * throws any exceptions. Callers must not use the StoreCostController
49      * after closing it; they are strongly advised to clear
50      * out the StoreCostController reference after closing.
51      * <p>
52      **/
53     void close();
54
55
56     /**
57      * Calculate the cost of a sort.
58      * <p>
59      * The cost of a sort includes the time spent in the sorter inserting
60      * the rows into the sort, and the time spent in the sorter returning the
61      * rows. Note that it does not include the cost of scanning the rows from
62      * the source table, for insert into the sort.
63      * <p>
64      * Arguments to getSortCost(), should be the same as those to be passed to
65      * TransactionController.createSort().
66      *
67      * @param template A row which is prototypical for the sort. All
68      * rows inserted into the sort controller must have
69      * exactly the same number of columns as the
70      * template row. Every column in an inserted row
71      * must have the same type as the corresponding
72      * column in the template.
73      *
74      * @param columnOrdering An array which specifies which columns
75      * participate in ordering - see interface
76      * ColumnOrdering for details. The column
77      * referenced in the 0th columnOrdering object is
78      * compared first, then the 1st, etc.
79      *
80      * @param alreadyInOrder Indicates that the rows inserted into the sort
81      * controller will already be in order. This is used
82      * to perform aggregation only.
83      *
84      * @param estimatedInputRows The number of rows that the caller estimates
85      * will be inserted into the sort. This number must
86      * be >= 0.
87      *
88      * @param estimatedExportRows The number of rows that the caller estimates
89      * will be exported by the sorter. For instance if
90      * the sort is doing duplicate elimination and all
91      * rows are expected to be duplicates then the
92      * estimatedExportRows would be 1. If no duplicate
93      * eliminate is to be done then estimatedExportRows
94      * would be the same as estimatedInputRows. This
95      * number must be >= 0.
96      *
97      * @param estimatedRowSize The estimated average row size of the rows
98      * being sorted. This is the client portion of the
99      * rowsize, it should not attempt to calculate
100      * Store's overhead. -1 indicates that the caller
101      * has no idea (and the sorter will use 100 bytes
102      * in that case. Used by the sort to make good
103      * choices about in-memory vs. external sorting,
104      * and to size merge runs. The client is not
105      * expected to estimate the per column/ per row
106      * overhead of raw store, just to make a guess
107      * about the storage associated with each row
108      * (ie. reasonable estimates for some
109      * implementations would be 4 for int, 8 for long,
110      * 102 for char(100), 202 for varchar(200), a
111      * number out of hat for user types, ...).
112      *
113      * @return The cost of the sort.
114      *
115      * @exception StandardException Standard exception policy.
116      *
117     **/
118
119     double getSortCost(
120     DataValueDescriptor[] template,
121     ColumnOrdering columnOrdering[],
122     boolean alreadyInOrder,
123     long estimatedInputRows,
124     long estimatedExportRows,
125     int estimatedRowSize)
126         throws StandardException;
127
128 }
129
Popular Tags