001: /*
002:
003: Derby - Class org.apache.derby.iapi.sql.compile.RowOrdering
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.sql.compile;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: /**
027: * This interface provides a representation of the ordering of rows in a
028: * ResultSet.
029: */
030: public interface RowOrdering {
031: static final int ASCENDING = 1;
032: static final int DESCENDING = 2;
033: static final int DONTCARE = 3;
034:
035: /**
036: * Tell whether this ordering is ordered on the given column in
037: * the given position
038: *
039: * @param direction One of ASCENDING, DESCENDING, or DONTCARE
040: * depending on the requirements of the caller.
041: * An ORDER BY clause cares about direction,
042: * while DISTINCT and GROUP BY do not.
043: * @param orderPosition The position in the ordering list. For example,
044: * for ORDER BY A, B, position 0 has column A,
045: * and position 1 has column B. Note that for an
046: * ordering, more than one column can be in a single
047: * ordering position: for example, in the query
048: * SELECT * FROM S, T WHERE S.A = T.B ORDER BY T.B
049: * columns S.A and T.B will be in the same ordering
050: * positions because they are equal. Also, constant
051: * values are considered ordered in all positions
052: * (consider SELECT A FROM T WHERE A = 1 ORDER BY A).
053: * @param tableNumber The table number of the Optimizable containing
054: * the column in question
055: * @param columnNumber The column number in the table (one-based).
056: *
057: * @return true means this ordering is ordered on the given column
058: * in the given position.
059: *
060: * @exception StandardException Thrown on error
061: */
062: boolean orderedOnColumn(int direction, int orderPosition,
063: int tableNumber, int columnNumber) throws StandardException;
064:
065: /**
066: * Tell whether this ordering is ordered on the given column.
067: * This is similar to the method above, but it checks whether the
068: * column is ordered in any position, rather than a specified position.
069: * This is useful for operations like DISTINCT and GROUP BY.
070: *
071: * @param direction One of ASCENDING, DESCENDING, or DONTCARE
072: * depending on the requirements of the caller.
073: * An ORDER BY clause cares about direction,
074: * while DISTINCT and GROUP BY do not.
075: * @param tableNumber The table number of the Optimizable containing
076: * the column in question
077: * @param columnNumber The column number in the table (one-based).
078: *
079: * @return true means this ordering is ordered on the given column
080: * in the given position.
081: *
082: * @exception StandardException Thrown on error
083: */
084: boolean orderedOnColumn(int direction, int tableNumber,
085: int columnNumber) throws StandardException;
086:
087: /**
088: * Add a column to this RowOrdering in the current order position.
089: * This is a no-op if there are any unordered optimizables in the
090: * join order (see below).
091: *
092: * @param direction One of ASCENDING, DESCENDING, or DONTCARE.
093: * DONTCARE can be used for things like columns
094: * with constant value, and for one-row tables.
095: * @param tableNumber The table the column is in.
096: * @param columnNumber The column number in the table (one-based)
097: */
098: void addOrderedColumn(int direction, int tableNumber,
099: int columnNumber);
100:
101: /**
102: * Move to the next order position for adding ordered columns.
103: * This is a no-op if there are any unordered optimizables in the
104: * join order (see below).
105: *
106: * @param direction One of ASCENDING, DESCENDING, or DONTCARE.
107: * DONTCARE can be used for things like columns
108: * with constant value, and for one-row tables.
109: */
110: void nextOrderPosition(int direction);
111:
112: /**
113: * Tell this RowOrdering that it is always ordered on the given optimizable
114: * This is useful when considering a unique index where there is an
115: * equality match on the entire key - in this case, all the columns
116: * are ordered, regardless of the direction or position,
117: * or even whether the columns are in the index.
118: *
119: * @param optimizable The table in question
120: */
121: void optimizableAlwaysOrdered(Optimizable optimizable);
122:
123: /**
124: * Tell this RowOrdering that it is always ordered on the given column
125: * of the given optimizable. This is useful when a column in the
126: * optimizable has an equals comparison with a constant expression.
127: * This is reset when the optimizable is removed from this RowOrdering.
128: *
129: * @param optimizable The table in question
130: * @param columnNumber The number of the column in question.
131: */
132: void columnAlwaysOrdered(Optimizable optimizable, int columnNumber);
133:
134: /**
135: * Ask whether the given table is always ordered.
136: */
137: boolean alwaysOrdered(int tableNumber);
138:
139: /**
140: * Tell this row ordering that it is no longer ordered on the given
141: * table. Also, adjust the current order position, if necessary.
142: * This only works to remove ordered columns from the end of the
143: * ordering.
144: *
145: * @param tableNumber The number of the table to remove from
146: * this RowOrdering.
147: */
148: void removeOptimizable(int tableNumber);
149:
150: /**
151: * Add an unordered optimizable to this RowOrdering. This is to
152: * solve the following problem:
153: *
154: * Suppose we have the query:
155: *
156: * select * from r, s, t order by r.a, t.b
157: *
158: * Also suppose there are indexes on r.a and t.b. When the
159: * optimizer considers the join order (r, s, t) using the index
160: * on r.a, the heap on s, and the index on t.b, the rows from the
161: * join order will *NOT* be ordered on t.b, because there is an
162: * unordered result set between r and t. So, when s is added to
163: * the partial join order, and we then add table t to the join order,
164: * we want to ensure that we don't add column t.b to the RowOrdering.
165: */
166: void addUnorderedOptimizable(Optimizable optimizable);
167:
168: /**
169: * Copy the contents of this RowOrdering to the given RowOrdering.
170: */
171: void copy(RowOrdering copyTo);
172: }
|