db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rhille...@apache.org
Subject svn commit: r574945 - in /db/derby/code/trunk: java/engine/org/apache/derby/vti/VTICosting.java java/engine/org/apache/derby/vti/VTIEnvironment.java java/engine/org/apache/derby/vti/package.html tools/javadoc/publishedapi.ant
Date Wed, 12 Sep 2007 13:19:45 GMT
Author: rhillegas
Date: Wed Sep 12 06:19:44 2007
New Revision: 574945

URL: http://svn.apache.org/viewvc?rev=574945&view=rev
Log:
DERBY-716: Expose VTICosting and VTIEnvironment in Derby's public api.

Added:
    db/derby/code/trunk/java/engine/org/apache/derby/vti/package.html   (with props)
Modified:
    db/derby/code/trunk/java/engine/org/apache/derby/vti/VTICosting.java
    db/derby/code/trunk/java/engine/org/apache/derby/vti/VTIEnvironment.java
    db/derby/code/trunk/tools/javadoc/publishedapi.ant

Modified: db/derby/code/trunk/java/engine/org/apache/derby/vti/VTICosting.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/vti/VTICosting.java?rev=574945&r1=574944&r2=574945&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/vti/VTICosting.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/vti/VTICosting.java Wed Sep 12 06:19:44
2007
@@ -24,39 +24,76 @@
 import java.sql.SQLException;
 
 /**
+  * <P>
   *	VTICosting is the interface that the query optimizer uses
-  * to cost VTIs.
-  * 
-  The methods on the interface provide the optimizer
+  * to cost Table Functions. The methods on this interface provide the optimizer
   * with the following information:
-  <UL> 
-  <LI> the estimated number of rows returned by the VTI in a single instantiation.
-  <LI> the estimated cost to instantiate and iterate through the VTI.
-  <LI> whether or not the VTI can be instantiated multiple times within a single query
execution
-  </UL>
+  * </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>
-  * This class can only be used within an SQL-J statement.  Using the methods
-  * in application-side Java code results in Exceptions being thrown.
+  * 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 VTI.
+	 * 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 VTI.
+	   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 VTI.
+	 *  Get the estimated row count for a single scan of a Table Function.
 	 *
-	 *  @param vtiEnvironment The VTIEnvironment.
+	 *  @param vtiEnvironment The state variable for optimizing the Table Function.
 	 *
-	 *  @return	The estimated row count for a single scan of a VTI.
+	 *  @return	The estimated row count for a single scan of the Table Function.
 	 *
 	 *  @exception SQLException thrown if the costing fails.
 	 */
@@ -64,11 +101,11 @@
 		throws SQLException;
 
 	/**
-	 *  Get the estimated cost for a single instantiation of a VTI.
+	 *  Get the estimated cost for a single instantiation of a Table Function.
 	 *
-	 *  @param vtiEnvironment The VTIEnvironment.
+	 *  @param vtiEnvironment The state variable for optimizing the Table Function.
 	 *
-	 *  @return	The estimated cost for a single instantiation of a VTI.
+	 *  @return	The estimated cost for a single instantiation of the Table Function.
 	 *
 	 *  @exception SQLException thrown if the costing fails.
 	 */
@@ -76,9 +113,9 @@
 		throws SQLException;
 
 	/**
-		 Find out if the ResultSet of the VTI can be instantiated multiple times.
+		 Find out if the ResultSet of the Table Function can be instantiated multiple times.
 
-		 @param vtiEnvironment The VTIEnvironment.
+		 @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.

Modified: db/derby/code/trunk/java/engine/org/apache/derby/vti/VTIEnvironment.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/vti/VTIEnvironment.java?rev=574945&r1=574944&r2=574945&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/vti/VTIEnvironment.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/vti/VTIEnvironment.java Wed Sep 12 06:19:44
2007
@@ -22,11 +22,14 @@
 package org.apache.derby.vti;
 
 /**
-  * 
-  *	VTIEnvironment is an interface used in costing VTIs.
-  * 
-  * The interface is
-  * passed as a parameter to various methods in the Virtual Table interface.
+  *
+  * <P>
+  *	VTIEnvironment is the state variable created by the optimizer to help it
+  *	place a Table Function in the join order.
+  *	The methods of <a href="./VTICosting.html">VTICosting</a> use this state
variable in
+  *	order to pass information to each other and learn other details of the
+  *	operating environment.
+  * </P>
   *
   * @see org.apache.derby.vti.VTICosting
   */
@@ -34,7 +37,7 @@
 {
 
 	/**
-		Return true if this instance of the VTI has been created for compilation,
+		Return true if this instance of the Table Function has been created for compilation,
 		false if it is for runtime execution.
 	*/
 	public boolean isCompileTime();
@@ -60,7 +63,7 @@
 	public void setSharedState(String key, java.io.Serializable value);
 
 	/**
-		Get an an object associated with a key from set of objects maintained with the statement
plan.
+		Get an object associated with a key from set of objects maintained with the statement plan.
 	*/
 	public Object getSharedState(String key);
 }

Added: db/derby/code/trunk/java/engine/org/apache/derby/vti/package.html
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/vti/package.html?rev=574945&view=auto
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/vti/package.html (added)
+++ db/derby/code/trunk/java/engine/org/apache/derby/vti/package.html Wed Sep 12 06:19:44
2007
@@ -0,0 +1,105 @@
+<!--
+  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.
+-->
+<BODY>
+<h2> Support for Table Functions. </h2>
+
+<P>
+Derby lets you declare functions which return
+<a href="http://java.sun.com/javase/6/docs/api/java/sql/ResultSet.html">ResultSet</a>s.
+You can then use these function results as tables in your queries.
+This, in turn, lets you do the following:
+</P>
+
+<UL>
+<LI><B>Migrate</B> - Bulk-load data from an external
+        database. The external data source could be any vendor's
+        database.
+</LI>
+<LI><B>Integrate</B> - Transform live data from an existing
+legacy server and load the data into Derby. This lets users
+ build new Derby-powered apps against subsets of legacy data,
+keep the data current, but limit the burden which the new apps
+place on the legacy server.
+</LI>
+<LI><B>Snapshot</B> - Copy a subset of server data to a laptop before travelling.
+</LI>
+<LI><B>Federate</B> - Join data from multiple external data
+sources. The external sources could be other relational databases
+or they could be non-relational data feeds.
+</LI>
+</Ul>
+
+<P>
+Here is an example of how to declare and invoke a Table Function:
+</P>
+
+<BLOCKQUOTE><PRE><FONT color="blue" size="+1"><B>
+CREATE FUNCTION externalEmployees
+()
+RETURNS TABLE
+(
+  employeeId    INT,
+  lastName       VARCHAR( 50 ),
+  firstName      VARCHAR( 50 ),
+  birthday         DATE
+)
+LANGUAGE JAVA
+PARAMETER STYLE DERBY_JDBC_RESULT_SET
+NO SQL
+EXTERNAL NAME 'com.acme.hrSchema.EmployeesTable.read'
+;
+
+INSERT INTO employees
+  SELECT s.*
+    FROM TABLE (externalEmployees() ) s;
+</B></FONT></PRE></BLOCKQUOTE>
+
+<P>
+The Derby optimizer makes some assumptions about these Table Functions:
+</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>
+Based on these assumptions, the optimizer decides where to place the
+Table Function in the join order. Using the interfaces in this package,
+you may override the optimizer's guesses and force the optimizer to
+choose a better join order.
+</P>
+
+<UL>
+  <LI><a href="./VTICosting.html">VTICosting</a> - This interface
+  exposes methods which let you override the optimizer's guesses.</LI>
+  <LI><a href="./VTIEnvironment.html">VTIEnvironment</a> - This is a
+  state variable, created by the optimizer and passed to the methods
+  in <a href="./VTICosting.html">VTICosting</a>.
+  <a href="./VTICosting.html">VTICosting</a> methods use this state
+  variable to communicate with one another and learn more about the
+  operating environment.</LI>
+</UL>
+
+</BODY>

Propchange: db/derby/code/trunk/java/engine/org/apache/derby/vti/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/code/trunk/tools/javadoc/publishedapi.ant
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/tools/javadoc/publishedapi.ant?rev=574945&r1=574944&r2=574945&view=diff
==============================================================================
--- db/derby/code/trunk/tools/javadoc/publishedapi.ant (original)
+++ db/derby/code/trunk/tools/javadoc/publishedapi.ant Wed Sep 12 06:19:44 2007
@@ -35,3 +35,9 @@
 org/apache/derby/tools/ij.java
 org/apache/derby/tools/sysinfo.java
 org/apache/derby/tools/dblook.java
+
+# package: org.apache.derby.vti
+
+org/apache/derby/vti/VTICosting.java
+org/apache/derby/vti/VTIEnvironment.java
+



Mime
View raw message