You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by rh...@apache.org on 2009/10/23 16:41:12 UTC
svn commit: r829078 - in
/db/derby/code/trunk/java/engine/org/apache/derby/vti: RestrictedVTI.java
Restriction.java
Author: rhillegas
Date: Fri Oct 23 14:41:11 2009
New Revision: 829078
URL: http://svn.apache.org/viewvc?rev=829078&view=rev
Log:
DERBY-4357: Add public api for restricted table functions.
Added:
db/derby/code/trunk/java/engine/org/apache/derby/vti/RestrictedVTI.java (with props)
db/derby/code/trunk/java/engine/org/apache/derby/vti/Restriction.java (with props)
Added: db/derby/code/trunk/java/engine/org/apache/derby/vti/RestrictedVTI.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/vti/RestrictedVTI.java?rev=829078&view=auto
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/vti/RestrictedVTI.java (added)
+++ db/derby/code/trunk/java/engine/org/apache/derby/vti/RestrictedVTI.java Fri Oct 23 14:41:11 2009
@@ -0,0 +1,136 @@
+/*
+
+ Derby - Class org.apache.derby.vti.RestrictedVTI
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ */
+package org.apache.derby.vti;
+
+import java.sql.ResultSet;
+import java.sql.SQLException;
+
+/**
+ <p>
+ * Interface for Table Functions which can be told which columns need to be fetched plus simple bounds on those columns.
+ * </p>
+ *
+ * <p>
+ * This interface can be implemented by the ResultSet returned by the public
+ * static method which is bound to the Table Function. If that ResultSet
+ * implements this interface, then the initScan() method of this interface will be
+ * called before the scan of the ResultSet starts, that is, before calling any
+ * ResultSet method.
+ * </p>
+ *
+ * <p>
+ * ResultSets which implement this interface can perform more efficiently
+ * because they don't have to fetch all columns and rows. This can mean
+ * performance boosts for queries which only need a subset of the Table
+ * Function's columns and for queries which compare those columns to constant
+ * expressions using the <, <=, =, >, and >= operators. This can also mean
+ * performance boosts for LIKE and BETWEEN operations on Table Function
+ * columns. For more information, see the commentary on
+ * <a href="https://issues.apache.org/jira/browse/DERBY-4357">DERBY-4357</a>.
+ * </p>
+ */
+public interface RestrictedVTI
+{
+ /**
+ * <p>
+ * Initialize a scan of a ResultSet. This method is called once before the scan begins. It
+ * is called before any
+ * ResultSet method is called. This method performs two tasks:
+ * </p>
+ *
+ * <li><b>Column names</b> - Tells the ResultSet which columns need to be fetched.</li>
+ * <li><b>Limits</b> - Gives the ResultSet simple bounds to apply in order
+ * to limit which rows are returned. Note that the ResultSet does not have
+ * to enforce all of these bounds. Derby will redundantly enforce these
+ * limits on all rows returned by the ResultSet. That is, filtering not
+ * performed inside the ResultSet will still happen outside the ResultSet.</li>
+ *
+ * <p>
+ * The <i>columnNames</i> argument is an array of columns which need to be fetched. This
+ * is an array of the column names declared in the Table Function's
+ * CREATE FUNCTION statement. Column names which were double-quoted
+ * in the CREATE FUNCTION statement appear case-sensitive in this
+ * array. Column names which were not double-quoted appear
+ * upper-cased. Derby asks the Table Function to fetch all columns mentioned
+ * in the query. This includes columns mentioned in the SELECT list as well
+ * as columns mentioned in the WHERE clause. Note that a column could be
+ * mentioned in the WHERE clause in a complex expression which could not be
+ * passed to the Table Function via the <i>restriction</i> argument.
+ * </p>
+ *
+ * <p>
+ * The array has one slot for each column declared in the CREATE FUNCTION
+ * statement. Slot 0 corresponds to the first column declared in the CREATE
+ * FUNCTION statement and so on. If a column does not need to be
+ * fetched, then the corresponding slot is null. If a column needs
+ * to be fetched, then the corresponding slot holds the column's
+ * name.
+ * </p>
+ *
+ * <p>
+ * Note that even though the array may have gaps, it is expected that
+ * columns in the ResultSet will occur at the positions declared in the
+ * CREATE FUNCTION statement. Consider the following declaration:
+ * </p>
+ *
+ * <blockquote><pre>
+ * create function foreignEmployeeTable()
+ * returns table
+ * (
+ * id int,
+ * birthDay date,
+ * firstName varchar( 100 ),
+ * lastName varchar( 100 )
+ * )
+ * ...
+ * </pre></blockquote>
+ *
+ * <p>
+ * and the following query:
+ * </p>
+ *
+ * <blockquote><pre>
+ * select lastName from table( foreignEmployeeTable() ) s
+ * </pre></blockquote>
+ *
+ * <p>
+ * In this example, the array passed to this method will have
+ * 4 slots. Slots 0, 1, and 2 will be null and slot 3 will hold
+ * the String "LASTNAME". Last names will be retrieved from the
+ * ResultSet by calls to getString( 4 )--remember that JDBC column
+ * ids are 1-based.
+ * </p>
+ *
+ * <p>
+ * The <i>restriction</i> argument is a simple expression which should be evaluated inside the Table
+ * Function in order to eliminate rows. The expression is a binary tree built out of ANDs,
+ * ORs, and column qualifiers. The column qualifiers are simple comparisons
+ * between constant values and columns in the Table Function. The Table
+ * Function only returns rows which satisfy the expression. The
+ * <i>restriction</i> is redundantly enforced by Derby on the rows returned
+ * by the ResultSet--this means that <i>restriction</i> gives the Table
+ * Function a hint about how to optimize its performance but the Table
+ * Function is not required to enforce the entire <i>restriction</i>.
+ * </p>
+ */
+ public void initScan( String[] columnNames, Restriction restriction ) throws SQLException;
+
+}
Propchange: db/derby/code/trunk/java/engine/org/apache/derby/vti/RestrictedVTI.java
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/code/trunk/java/engine/org/apache/derby/vti/Restriction.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/vti/Restriction.java?rev=829078&view=auto
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/vti/Restriction.java (added)
+++ db/derby/code/trunk/java/engine/org/apache/derby/vti/Restriction.java Fri Oct 23 14:41:11 2009
@@ -0,0 +1,213 @@
+/*
+
+ Derby - Class org.apache.derby.vti.Restriction
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ */
+package org.apache.derby.vti;
+
+import java.sql.SQLException;
+
+/**
+ <p>
+ * An expression to be pushed into a Table Function so that the Table Function
+ * can short-circuit its processing and return fewer rows. A restriction is represented
+ * as a binary tree. The non-leaf nodes are ANDs and ORs. The leaf nodes
+ * are ColumnQualifiers. A ColumnQualifier
+ * is a simple expression comparing a constant value to a column in
+ * the Table Function.
+ * </p>
+ */
+public abstract class Restriction
+{
+ /** An AND of two Restrictions */
+ public static class AND extends Restriction
+ {
+ private Restriction _leftChild;
+ private Restriction _rightChild;
+
+ /** AND together two other Restrictions */
+ public AND( Restriction leftChild, Restriction rightChild )
+ {
+ _leftChild = leftChild;
+ _rightChild = rightChild;
+ }
+
+ /** Get the left Restriction */
+ public Restriction getLeftChild() { return _leftChild; }
+
+ /** Get the right Restriction */
+ public Restriction getRightChild() { return _rightChild; }
+ }
+
+ /** An OR of two Restrictions */
+ public static class OR extends Restriction
+ {
+ private Restriction _leftChild;
+ private Restriction _rightChild;
+
+ /** OR together two other Restrictions */
+ public OR( Restriction leftChild, Restriction rightChild )
+ {
+ _leftChild = leftChild;
+ _rightChild = rightChild;
+ }
+
+ /** Get the left Restriction */
+ public Restriction getLeftChild() { return _leftChild; }
+
+ /** Get the right Restriction */
+ public Restriction getRightChild() { return _rightChild; }
+ }
+
+ /**
+ <p>
+ * A simple comparison of a column to a constant value. The comparison
+ * has the form:
+ * </p>
+ *
+ * <blockquote><pre>
+ * column OP constant
+ * </pre></blockquote>
+ *
+ * <p>
+ * where OP is one of the following:
+ * </p>
+ *
+ * <blockquote><pre>
+ * < = <= > >=
+ * </pre></blockquote>
+ */
+ public static class ColumnQualifier extends Restriction
+ {
+ ////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // CONSTANTS
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////
+
+ /** Ordering operation constant representing '<' **/
+ public static final int ORDER_OP_LESSTHAN = 1;
+
+ /** Ordering operation constant representing '=' **/
+ public static final int ORDER_OP_EQUALS = 2;
+
+ /** Ordering operation constant representing '<=' **/
+ public static final int ORDER_OP_LESSOREQUALS = 3;
+
+ /** Ordering operation constant representing '>' **/
+ public static final int ORDER_OP_GREATERTHAN = 4;
+
+ /** Ordering operation constant representing '>=' **/
+ public static final int ORDER_OP_GREATEROREQUALS = 5;
+
+ ////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // STATE
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////
+
+ /** name of column being restricted */
+ private String _columnName;
+
+ /** comparison operator, one of the ORDER_OP constants */
+ private int _comparisonOperator;
+
+ /** null handling */
+ private boolean _nullEqualsNull;
+
+ /** value to compare the column to */
+ private Object _constantOperand;
+
+ ////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // CONSTRUCTORS
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * <p>
+ * Construct from pieces.
+ * </p>
+ *
+ * @param columnName Name of column as declared in the CREATE FUNCTION statement.
+ * @param comparisonOperator One of the ORDER_OP constants.
+ * @param nullEqualsNull True if NULLS should be treated like ordinary values which sort before all other values. Used to encode IS NULL comparisons.
+ * @param constantOperand Constant value to which the column should be compared.
+ */
+ public ColumnQualifier
+ (
+ String columnName,
+ int comparisonOperator,
+ boolean nullEqualsNull,
+ Object constantOperand
+ )
+ {
+ _columnName = columnName;
+ _comparisonOperator = comparisonOperator;
+ _nullEqualsNull = nullEqualsNull;
+ _constantOperand = constantOperand;
+ }
+
+ ////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // ACCESSORS
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * <p>
+ * The name of the column being compared.
+ * </p>
+ */
+ public String getColumnName() { return _columnName; }
+
+ /**
+ * <p>
+ * The type of comparison to perform. This is one of the ORDER_OP constants
+ * defined above.
+ * </p>
+ */
+ public int getComparisonOperator() { return _comparisonOperator; }
+
+ /**
+ * <p>
+ * Specifies how nulls behave in comparisons. If true, then nulls are
+ * treated as values which sort before all other values; and the = comparison
+ * between two nulls evaluates to TRUE. If this method returns false, then
+ * any comparison involving a null evaluates to UNKNOWN. This is useful
+ * for encoding IS NULL comparisons.
+ * </p>
+ */
+ public boolean nullEqualsNull() { return _nullEqualsNull; }
+
+ /**
+ * <p>
+ * Get the constant value to which the column should be compared. The
+ * constant value must be an Object of the Java type which corresponds to
+ * the SQL type of the column. The column's SQL type was declared in the CREATE FUNCTION statement.
+ * The mapping of SQL types to Java types is defined in table 4 of chapter 14
+ * of the original JDBC 1 specification (dated 1996). Bascially, these are the Java
+ * wrapper values you would expect. For instance, SQL INT maps to java.lang.Integer, SQL CHAR
+ * maps to java.lang.String, etc..
+ * </p>
+ */
+ public Object getConstantOperand() { return _constantOperand; }
+ }
+
+}
+
Propchange: db/derby/code/trunk/java/engine/org/apache/derby/vti/Restriction.java
------------------------------------------------------------------------------
svn:eol-style = native