db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rhille...@apache.org
Subject svn commit: r829078 - in /db/derby/code/trunk/java/engine/org/apache/derby/vti: RestrictedVTI.java Restriction.java
Date Fri, 23 Oct 2009 14:41:12 GMT
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



Mime
View raw message