--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.sql.compile.RowOrdering\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.sql.compile;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+/**\r
+ * This interface provides a representation of the ordering of rows in a\r
+ * ResultSet.\r
+ */\r
+public interface RowOrdering\r
+{\r
+ static final int ASCENDING = 1;\r
+ static final int DESCENDING = 2;\r
+ static final int DONTCARE = 3;\r
+\r
+ /**\r
+ * Tell whether this ordering is ordered on the given column in\r
+ * the given position\r
+ *\r
+ * @param direction One of ASCENDING, DESCENDING, or DONTCARE\r
+ * depending on the requirements of the caller.\r
+ * An ORDER BY clause cares about direction,\r
+ * while DISTINCT and GROUP BY do not.\r
+ * @param orderPosition The position in the ordering list. For example,\r
+ * for ORDER BY A, B, position 0 has column A,\r
+ * and position 1 has column B. Note that for an\r
+ * ordering, more than one column can be in a single\r
+ * ordering position: for example, in the query\r
+ * SELECT * FROM S, T WHERE S.A = T.B ORDER BY T.B\r
+ * columns S.A and T.B will be in the same ordering\r
+ * positions because they are equal. Also, constant\r
+ * values are considered ordered in all positions\r
+ * (consider SELECT A FROM T WHERE A = 1 ORDER BY A).\r
+ * @param tableNumber The table number of the Optimizable containing\r
+ * the column in question\r
+ * @param columnNumber The column number in the table (one-based).\r
+ *\r
+ * @return true means this ordering is ordered on the given column\r
+ * in the given position.\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ boolean orderedOnColumn(int direction,\r
+ int orderPosition,\r
+ int tableNumber,\r
+ int columnNumber)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Tell whether this ordering is ordered on the given column.\r
+ * This is similar to the method above, but it checks whether the\r
+ * column is ordered in any position, rather than a specified position.\r
+ * This is useful for operations like DISTINCT and GROUP BY.\r
+ *\r
+ * @param direction One of ASCENDING, DESCENDING, or DONTCARE\r
+ * depending on the requirements of the caller.\r
+ * An ORDER BY clause cares about direction,\r
+ * while DISTINCT and GROUP BY do not.\r
+ * @param tableNumber The table number of the Optimizable containing\r
+ * the column in question\r
+ * @param columnNumber The column number in the table (one-based).\r
+ *\r
+ * @return true means this ordering is ordered on the given column\r
+ * in the given position.\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ boolean orderedOnColumn(int direction,\r
+ int tableNumber,\r
+ int columnNumber)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Add a column to this RowOrdering in the current order position.\r
+ * This is a no-op if there are any unordered optimizables in the\r
+ * join order (see below).\r
+ *\r
+ * @param direction One of ASCENDING, DESCENDING, or DONTCARE.\r
+ * DONTCARE can be used for things like columns\r
+ * with constant value, and for one-row tables.\r
+ * @param tableNumber The table the column is in.\r
+ * @param columnNumber The column number in the table (one-based)\r
+ */\r
+ void addOrderedColumn(int direction,\r
+ int tableNumber,\r
+ int columnNumber);\r
+\r
+ /**\r
+ * Move to the next order position for adding ordered columns.\r
+ * This is a no-op if there are any unordered optimizables in the\r
+ * join order (see below).\r
+ *\r
+ * @param direction One of ASCENDING, DESCENDING, or DONTCARE.\r
+ * DONTCARE can be used for things like columns\r
+ * with constant value, and for one-row tables.\r
+ */\r
+ void nextOrderPosition(int direction);\r
+\r
+ /**\r
+ * Tell this RowOrdering that it is always ordered on the given optimizable\r
+ * This is useful when considering a unique index where there is an\r
+ * equality match on the entire key - in this case, all the columns\r
+ * are ordered, regardless of the direction or position,\r
+ * or even whether the columns are in the index.\r
+ *\r
+ * @param optimizable The table in question\r
+ */\r
+ void optimizableAlwaysOrdered(Optimizable optimizable);\r
+\r
+ /**\r
+ * Tell this RowOrdering that it is always ordered on the given column\r
+ * of the given optimizable. This is useful when a column in the\r
+ * optimizable has an equals comparison with a constant expression.\r
+ * This is reset when the optimizable is removed from this RowOrdering.\r
+ *\r
+ * @param optimizable The table in question\r
+ * @param columnNumber The number of the column in question.\r
+ */\r
+ void columnAlwaysOrdered(Optimizable optimizable, int columnNumber);\r
+\r
+ /**\r
+ * Ask whether the given table is always ordered.\r
+ */\r
+ boolean alwaysOrdered(int tableNumber);\r
+\r
+ /**\r
+ * Tell this row ordering that it is no longer ordered on the given\r
+ * table. Also, adjust the current order position, if necessary.\r
+ * This only works to remove ordered columns from the end of the\r
+ * ordering.\r
+ *\r
+ * @param tableNumber The number of the table to remove from \r
+ * this RowOrdering.\r
+ */\r
+ void removeOptimizable(int tableNumber);\r
+\r
+ /**\r
+ * Add an unordered optimizable to this RowOrdering. This is to\r
+ * solve the following problem:\r
+ *\r
+ * Suppose we have the query:\r
+ *\r
+ * select * from r, s, t order by r.a, t.b\r
+ *\r
+ * Also suppose there are indexes on r.a and t.b. When the\r
+ * optimizer considers the join order (r, s, t) using the index\r
+ * on r.a, the heap on s, and the index on t.b, the rows from the\r
+ * join order will *NOT* be ordered on t.b, because there is an\r
+ * unordered result set between r and t. So, when s is added to\r
+ * the partial join order, and we then add table t to the join order,\r
+ * we want to ensure that we don't add column t.b to the RowOrdering.\r
+ */\r
+ void addUnorderedOptimizable(Optimizable optimizable);\r
+\r
+ /**\r
+ * Copy the contents of this RowOrdering to the given RowOrdering.\r
+ */\r
+ void copy(RowOrdering copyTo);\r
+}\r