| /* |
| |
| Derby - Class org.apache.derby.vti.VTICosting |
| |
| 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> |
| * VTICosting is the interface that the query optimizer uses |
| * to cost Table Functions. The methods on this interface provide the optimizer |
| * with the following information: |
| * </P> |
| * |
| * <UL> |
| * <LI> The estimated number of rows returned by the Table Function in a single instantiation. |
| * <LI> The estimated cost to instantiate and iterate through the Table Function. |
| * <LI> Whether or not the Table Function can be instantiated multiple times within a single query execution. |
| * </UL> |
| * |
| * <P> |
| * The optimizer places a Table Function in the join order after making some |
| * assumptions: |
| * </P> |
| * |
| * <UL> |
| * <LI><B>Cost</B> - The optimizer hard-codes a guess about how expensive |
| * it is to materialize a Table Function. |
| * </LI> |
| * <LI><B>Count</B> - The optimizer also hard-codes a guess about how |
| * many rows a Table Function returns. |
| * </LI> |
| * <LI><B>Repeatability</B> - The optimizer assumes that the same results |
| * come back each time you invoke a Table Function. |
| * </LI> |
| * </Ul> |
| * |
| * <P> |
| * The class which contains your Table Function can override these assumptions |
| * and improve the join order as follows: |
| * </P> |
| * |
| * <UL> |
| * <LI><B>Implement</B> - The class must implement <a href="./VTICosting.html">VTICosting</a>. |
| * </LI> |
| * <LI><B>Construct</B> - The class must contain a public, no-arg constructor. |
| * </LI> |
| * </Ul> |
| * |
| * <P> |
| * The methods in this interface take a <a href="./VTIEnvironment.html">VTIEnvironment</a> |
| * argument. This is a state variable created by the optimizer. The methods in |
| * this interface can use this state variable to pass information to one |
| * another and learn other details of the operating environment. |
| * </P> |
| * |
| * |
| * @see org.apache.derby.vti.VTIEnvironment |
| */ |
| public interface VTICosting |
| { |
| /** |
| * A useful constant: the default estimated number of rows returned by a |
| * Table Function. |
| */ |
| public static final double defaultEstimatedRowCount = 10000d; |
| /** |
| A useful constant: The default estimated cost of instantiating and |
| iterating throught a Table Function. |
| */ |
| public static final double defaultEstimatedCost = 100000d; |
| |
| /** |
| * Get the estimated row count for a single scan of a Table Function. |
| * |
| * @param vtiEnvironment The state variable for optimizing the Table Function. |
| * |
| * @return The estimated row count for a single scan of the Table Function. |
| * |
| * @exception SQLException thrown if the costing fails. |
| */ |
| public double getEstimatedRowCount(VTIEnvironment vtiEnvironment) |
| throws SQLException; |
| |
| /** |
| * Get the estimated cost for a single instantiation of a Table Function. |
| * |
| * @param vtiEnvironment The state variable for optimizing the Table Function. |
| * |
| * @return The estimated cost for a single instantiation of the Table Function. |
| * |
| * @exception SQLException thrown if the costing fails. |
| */ |
| public double getEstimatedCostPerInstantiation(VTIEnvironment vtiEnvironment) |
| throws SQLException; |
| |
| /** |
| Find out if the ResultSet of the Table Function can be instantiated multiple times. |
| |
| @param vtiEnvironment The state variable for optimizing the Table Function. |
| |
| @return True if the ResultSet can be instantiated multiple times, false if |
| can only be instantiated once. |
| |
| @exception SQLException thrown if the costing fails. |
| */ |
| public boolean supportsMultipleInstantiations(VTIEnvironment vtiEnvironment) |
| throws SQLException; |
| } |