db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1596238 - in /db/derby/docs/trunk/src/devguide: cdevspecialtfarchivevti.dita cdevspecialtfcontext.dita derbydev.ditamap
Date Tue, 20 May 2014 13:29:28 GMT
Author: chaase3
Date: Tue May 20 13:29:28 2014
New Revision: 1596238

URL: http://svn.apache.org/r1596238
Log:
DERBY-6467  Document context-aware table functions.

Added 2 new topics to Developer's Guide and modified map file.

Patches: DERBY-6467-2.diff

Added:
    db/derby/docs/trunk/src/devguide/cdevspecialtfarchivevti.dita   (with props)
    db/derby/docs/trunk/src/devguide/cdevspecialtfcontext.dita   (with props)
Modified:
    db/derby/docs/trunk/src/devguide/derbydev.ditamap

Added: db/derby/docs/trunk/src/devguide/cdevspecialtfarchivevti.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtfarchivevti.dita?rev=1596238&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtfarchivevti.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtfarchivevti.dita Tue May 20 13:29:28 2014
@@ -0,0 +1,269 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+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.
+-->
+<concept id="cdevspecialtfarchivevti" xml:lang="en-us">
+<title>ArchiveVTI source code</title>
+<shortdesc>The code that defines the <i>archiveVTI</i> table function is
as 
+follows.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>functions<indexterm>context-aware table functions</indexterm></indexterm>
+<indexterm>functions<indexterm>archiveVTI table function</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<codeblock>package org.apache.derbyTesting.functionTests.tests.lang;
+
+import java.sql.Connection;
+import java.sql.DatabaseMetaData;
+import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.util.ArrayList;
+
+import org.apache.derby.vti.AwareVTI;
+import org.apache.derby.vti.ForeignTableVTI;
+import org.apache.derby.vti.ForwardingVTI;
+import org.apache.derby.vti.RestrictedVTI;
+import org.apache.derby.vti.Restriction;
+import org.apache.derby.vti.VTIContext;
+
+/**
+ * &lt;p>
+ * This table function acts like a union view on a set of archive tables.
+ * The idea is that the old contents of a main table are periodically
+ * moved to archive tables whose names start with $tableName$suffix.
+ * Each bulk move of rows results in the creation of a new archive table.
+ * The archive tables live in the same schema as the main table and have
+ * its shape. This table function unions the main table together with all
+ * of its archived snapshots. So, for instance, you might have the
+ * following set of tables, which this table function unions together:
+ * &lt;/p>
+ *
+ * &lt;pre>
+ *  T1
+ *  T1_ARCHIVE_1
+ *  T1_ARCHIVE_2
+ *   ...
+ *  T1_ARCHIVE_N
+ * &lt;/pre>
+ *
+ * &lt;p>
+ * This table function may appear in user documentation. If you change
+ * the behavior of this table function, make sure that you adjust the
+ * user documentation linked from DERBY-6117.
+ * &lt;/p>
+ */
+public class ArchiveVTI extends ForwardingVTI implements AwareVTI,
+        RestrictedVTI
+{
+    /////////////////////////////////////////////////////////////////////
+    //
+    //	CONSTANTS
+    //
+    /////////////////////////////////////////////////////////////////////
+
+    /////////////////////////////////////////////////////////////////////
+    //
+    //	STATE
+    //
+    /////////////////////////////////////////////////////////////////////
+
+    private Connection  _connection;
+    private String      _archiveSuffix;
+    private VTIContext  _vtiContext;
+    private ArrayList&lt;String>   _tableNames;
+    private int         _tableIdx;
+    
+    private String[]    _columnNames;
+    private Restriction _restriction;
+
+    /////////////////////////////////////////////////////////////////////
+    //
+    //  TABLE FUNCTION
+    //
+    /////////////////////////////////////////////////////////////////////
+
+    /**
+     * &lt;p>
+     * Entry point for creating an ArchiveVTI which is bound to a Derby
+     * table function by a CREATE FUNCTION statement which looks like
+     * this:
+     * &lt;/p>
+     *
+     * &lt;pre>
+     * create function t1( archiveSuffix varchar( 32672 ) ) returns table
+     * (
+     *     keyCol int,
+     *     aCol int,
+     *     bCol int
+     * )
+     * language java parameter style derby_jdbc_result_set reads sql data
+     * external name
+     * 'org.apache.derbyTesting.functionTests.tests.lang.ArchiveVTI.archiveVTI'
+     * &lt;/pre>
+     *
+     * @param archiveSuffix All of the archive tables have names of the
+     *                      form $tablename$archiveSuffix.
+     */
+    public  static  ArchiveVTI  archiveVTI( String archiveSuffix )
+            throws SQLException
+    { return new ArchiveVTI( archiveSuffix ); }
+
+    /////////////////////////////////////////////////////////////////////
+    //
+    //	CONSTRUCTOR
+    //
+    /////////////////////////////////////////////////////////////////////
+
+    /** Construct from the suffix which flags all of the relevant
+     *  tables.
+     */
+    public  ArchiveVTI( String archiveSuffix )    throws SQLException
+    {
+        _connection = DriverManager.getConnection( 
+                "jdbc:default:connection" );
+        _archiveSuffix = archiveSuffix;
+    }
+
+    /////////////////////////////////////////////////////////////////////
+    //
+    //  AwareVTI BEHAVIOR
+    //
+    /////////////////////////////////////////////////////////////////////
+
+    public  VTIContext  getContext() { return _vtiContext; }
+    public  void    setContext( VTIContext context )
+    { _vtiContext = context; }
+
+    /////////////////////////////////////////////////////////////////////
+    //
+    //	RestrictedVTI BEHAVIOR
+    //
+    /////////////////////////////////////////////////////////////////////
+
+    public  void    initScan
+        ( String[] columnNames, Restriction restriction )
+        throws SQLException
+    {
+        _columnNames = new String[ columnNames.length ];
+        System.arraycopy( columnNames, 0, _columnNames, 0,
+                columnNames.length );
+        _restriction = restriction;
+    }
+
+    /////////////////////////////////////////////////////////////////////
+    //
+    //	ResultSet BEHAVIOR
+    //
+    /////////////////////////////////////////////////////////////////////
+
+    public boolean next()   throws SQLException
+    {
+        if ( _tableNames == null )
+        {
+            getTableNames();
+            _tableIdx = 0;
+            loadResultSet();
+        }
+
+        while ( !super.next() )
+        {
+            _tableIdx++;
+            if ( _tableIdx >= _tableNames.size() ) { return false; }
+            loadResultSet();
+        }
+
+        return true;
+    }
+
+    public  void    close() throws SQLException
+    {
+        if ( getWrappedResultSet() != null ) 
+        { 
+            getWrappedResultSet().close();
+        }
+        wrapResultSet( null );
+        _connection = null;
+    }
+
+    /////////////////////////////////////////////////////////////////////
+    //
+    //	UTILITY METHODS
+    //
+    /////////////////////////////////////////////////////////////////////
+
+    /**
+     * &lt;p>
+     * Get cursors on all the tables which we are going to union
+     * together.
+     * &lt;/p>
+     */
+    private void    getTableNames() throws SQLException
+    {
+        _tableNames = new ArrayList&lt;String>();
+        _tableNames.add( getContext().vtiTable() );
+
+        DatabaseMetaData    dbmd = getConnection().getMetaData();
+        ResultSet   candidates = dbmd.getTables
+            ( null, getContext().vtiSchema(), getContext().vtiTable() 
+              + _archiveSuffix + "%", null );
+
+        while ( candidates.next() )
+        {
+            _tableNames.add( candidates.getString( "TABLE_NAME" ) );
+        }
+        candidates.close();
+    }
+    
+    /**
+     * &lt;p>
+     * Compile the query against the next table and use its ResultSet
+     * until it's drained.
+     * &lt;/p>
+     */
+    private void    loadResultSet() throws SQLException
+    {
+        if ( getWrappedResultSet() != null )
+        { 
+            getWrappedResultSet().close();
+        }
+        
+        ForeignTableVTI     nextRS = new ForeignTableVTI
+            ( getContext().vtiSchema(), _tableNames.get( _tableIdx ),
+              getConnection() );
+        nextRS.initScan( _columnNames, _restriction );
+
+        wrapResultSet( nextRS );
+    }
+
+    /**
+     * &lt;p>
+     * Get this database session's connection to the database.
+     * &lt;/p>
+     */
+    private Connection  getConnection() throws SQLException
+    {
+        return _connection;
+    }
+    
+}</codeblock>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtfarchivevti.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/devguide/cdevspecialtfcontext.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevspecialtfcontext.dita?rev=1596238&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevspecialtfcontext.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevspecialtfcontext.dita Tue May 20 13:29:28 2014
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!-- 
+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.
+-->
+<concept id="cdevspecialtfcontext" xml:lang="en-us">
+<title>Writing context-aware table functions</title>
+<shortdesc>A context-aware table function is able to access context information
+that is passed in to it from
+<ph conref="../conrefs.dita#prod/productshortname"></ph>.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>functions<indexterm>context-aware table functions</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<p>Context-aware table functions are useful when both of the following are the
+case:
+<ul>
+<li>You want to bind a single Java method to many table functions, each of which
+has a different row shape.</li>
+<li>You are able to determine the row shape, at runtime, from the
+schema-qualified name of the table function which is being invoked.</li>
+</ul></p>
+<p>A context-aware table function makes use of the
+<i>org.apache.derby.vti.AwareVTI</i> interface and the
+<i>org.apache.derby.vti.VTIContext</i> class. The <i>VTIContext</i>
class, which
+can be accessed through the <i>AwareVTI</i> interface, provides methods that
+return the unqualified table function name, the name of the schema which holds
+the table function, and the text of the statement which invoked the table
+function. See the <ph conref="../conrefs.dita#prod/productshortname"></ph>
+public API documentation for more information about <i>AwareVTI</i> and
+<i>VTIContext</i>.</p>
+<p>For example, the <i>ArchiveVTI</i> table function performs a task
+which many users have found useful: it provides a union of a main table with a 
+set of archive tables. The archive tables are created at regular intervals. When
+a new archive table is created, the oldest rows from the main table are moved to
+the archive table.</p>
+<p>To use the <i>ArchiveVTI</i> table function, you need to include
+<i>derbyTesting.jar</i> in your classpath along with other
+<ph conref="../conrefs.dita#prod/productshortname"></ph> jar files.</p>
+<p>The following series of commands shows how to use the <i>archiveVTI</i>
+method, which is included in the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> test code. The source
+code for the <i>ArchiveVTI</i> class is provided in the next topic.
+</p>
+<p>In this
+example, the method is bound to two table functions; one function returns a
+three-column table, the other a two-column table.</p>
+<codeblock><b>java org.apache.derby.tools.ij</b>
+ij version 10.11
+ij> <b>connect 'jdbc:derby:memory:db;create=true';</b>
+ij> <b>create table t1
+(
+    keyCol int,
+    aCol int,
+    bCol int
+);</b>
+0 rows inserted/updated/deleted
+ij> <b>create table t1_archive_001 as select * from t1 with no data;</b>
+0 rows inserted/updated/deleted
+ij> <b>create table t1_archive_002 as select * from t1 with no data;</b>
+0 rows inserted/updated/deleted
+ij> <b>insert into t1_archive_002 values ( 1, 100, 1000 ), ( 2, 200, 2000 ),
+    ( 3, 300, 3000 );</b>
+3 rows inserted/updated/deleted
+ij> <b>insert into t1_archive_001 values ( 4, 400, 4000 ), ( 5, 500, 5000 ),
+    ( 6, 600, 6000 );</b>
+3 rows inserted/updated/deleted
+ij> <b>insert into t1 values ( 7, 700, 7000 ), ( 8, 800, 8000 ), 
+    ( 9, 900, 9000 );</b>
+3 rows inserted/updated/deleted
+ij> <b>create table t2
+(
+    keyCol int,
+    aCol int
+);</b>
+0 rows inserted/updated/deleted
+ij> <b>create table t2_arc_001 as select * from t2 with no data;</b>
+0 rows inserted/updated/deleted
+ij> <b>create table t2_arc_002 as select * from t2 with no data;</b>
+0 rows inserted/updated/deleted
+ij> <b>insert into t2_arc_002 values ( 1, 100 ), ( 2, 200 ),  ( 3, 300 );</b>
+3 rows inserted/updated/deleted
+ij> <b>insert into t2_arc_001 values ( 4, 400 ), ( 5, 500 ),  ( 6, 600 );</b>
+3 rows inserted/updated/deleted
+ij> <b>insert into t2 values ( 7, 700 ), ( 8, 800 ), ( 9, 900 );</b>
+3 rows inserted/updated/deleted
+ij> <b>create function t1( archiveSuffix varchar( 32672 ) ) returns table
+(
+    keyCol int,
+    aCol int,
+    bCol int
+)
+language java parameter style derby_jdbc_result_set reads sql data
+external name 
+'org.apache.derbyTesting.functionTests.tests.lang.ArchiveVTI.archiveVTI';</b>
+0 rows inserted/updated/deleted
+ij> <b>create function t2( archiveSuffix varchar( 32672 ) ) returns table
+(
+    keyCol int,
+    aCol int
+)
+language java parameter style derby_jdbc_result_set reads sql data
+external name 
+'org.apache.derbyTesting.functionTests.tests.lang.ArchiveVTI.archiveVTI';</b>
+0 rows inserted/updated/deleted
+ij> <b>select * from table( t1( '_ARCHIVE_' ) ) s
+where keyCol between 3 and 7
+order by keyCol;</b>
+KEYCOL     |ACOL       |BCOL       
+-----------------------------------
+3          |300        |3000       
+4          |400        |4000       
+5          |500        |5000       
+6          |600        |6000       
+7          |700        |7000       
+      
+5 rows selected
+ij> <b>select * from table( t2( '_ARC_' ) ) s
+where keyCol between 3 and 7
+order by keyCol;</b>
+KEYCOL     |ACOL       
+-----------------------
+3          |300        
+4          |400        
+5          |500        
+6          |600        
+7          |700        
+
+5 rows selected</codeblock>
+</conbody>
+</concept>

Propchange: db/derby/docs/trunk/src/devguide/cdevspecialtfcontext.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=1596238&r1=1596237&r2=1596238&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Tue May 20 13:29:28 2014
@@ -1791,6 +1791,9 @@ limitations under the License.
 </topicref>
 <topicref href="cdevspecialtfrestr.dita" navtitle="Writing restricted table functions">
 </topicref>
+<topicref href="cdevspecialtfcontext.dita" navtitle="Writing context-aware table functions">
+<topicref href="cdevspecialtfarchivevti.dita" navtitle="ArchiveVTI source code"/>
+</topicref>
 <topicref href="cdevspecialtfoptimizer.dita" navtitle="Optimizer support for Derby-style
table functions">
 <topicref href="cdevspecialtfopttune.dita" navtitle="Measuring the cost of Derby-style
table functions">
 </topicref>



Mime
View raw message