001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.SortCostController
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.access;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: import org.apache.derby.iapi.types.DataValueDescriptor;
027:
028: /**
029:
030: The SortCostController interface provides methods that an access client
031: (most likely the system optimizer) can use to get sorter's estimated cost of
032: various operations on the SortController.
033: <p>
034: @see TransactionController#openSortCost
035: @see TransactionController#createSort
036: @see RowCountable
037:
038: **/
039:
040: import java.util.Properties;
041:
042: public interface SortCostController {
043: /**
044: * Close the controller.
045: * <p>
046: * Close the open controller. This method always succeeds, and never
047: * throws any exceptions. Callers must not use the StoreCostController
048: * after closing it; they are strongly advised to clear
049: * out the StoreCostController reference after closing.
050: * <p>
051: **/
052: void close();
053:
054: /**
055: * Calculate the cost of a sort.
056: * <p>
057: * The cost of a sort includes the time spent in the sorter inserting
058: * the rows into the sort, and the time spent in the sorter returning the
059: * rows. Note that it does not include the cost of scanning the rows from
060: * the source table, for insert into the sort.
061: * <p>
062: * Arguments to getSortCost(), should be the same as those to be passed to
063: * TransactionController.createSort().
064: *
065: * @param template A row which is prototypical for the sort. All
066: * rows inserted into the sort controller must have
067: * exactly the same number of columns as the
068: * template row. Every column in an inserted row
069: * must have the same type as the corresponding
070: * column in the template.
071: *
072: * @param columnOrdering An array which specifies which columns
073: * participate in ordering - see interface
074: * ColumnOrdering for details. The column
075: * referenced in the 0th columnOrdering object is
076: * compared first, then the 1st, etc.
077: *
078: * @param alreadyInOrder Indicates that the rows inserted into the sort
079: * controller will already be in order. This is used
080: * to perform aggregation only.
081: *
082: * @param estimatedInputRows The number of rows that the caller estimates
083: * will be inserted into the sort. This number must
084: * be >= 0.
085: *
086: * @param estimatedExportRows The number of rows that the caller estimates
087: * will be exported by the sorter. For instance if
088: * the sort is doing duplicate elimination and all
089: * rows are expected to be duplicates then the
090: * estimatedExportRows would be 1. If no duplicate
091: * eliminate is to be done then estimatedExportRows
092: * would be the same as estimatedInputRows. This
093: * number must be >= 0.
094: *
095: * @param estimatedRowSize The estimated average row size of the rows
096: * being sorted. This is the client portion of the
097: * rowsize, it should not attempt to calculate
098: * Store's overhead. -1 indicates that the caller
099: * has no idea (and the sorter will use 100 bytes
100: * in that case. Used by the sort to make good
101: * choices about in-memory vs. external sorting,
102: * and to size merge runs. The client is not
103: * expected to estimate the per column/ per row
104: * overhead of raw store, just to make a guess
105: * about the storage associated with each row
106: * (ie. reasonable estimates for some
107: * implementations would be 4 for int, 8 for long,
108: * 102 for char(100), 202 for varchar(200), a
109: * number out of hat for user types, ...).
110: *
111: * @return The cost of the sort.
112: *
113: * @exception StandardException Standard exception policy.
114: *
115: **/
116:
117: double getSortCost(DataValueDescriptor[] template,
118: ColumnOrdering columnOrdering[], boolean alreadyInOrder,
119: long estimatedInputRows, long estimatedExportRows,
120: int estimatedRowSize) throws StandardException;
121:
122: }
|