[teiid-commits] teiid SVN: r2220 - in trunk/documentation/connector-developer-guide/src/main/docbook/en-US: content and 1 other directory.

Author: rareddy Date: 2010-06-10 20:22:28 -0400 (Thu, 10 Jun 2010) New Revision: 2220 Added: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml Removed: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml Log: TEIID-315: Adding the updated chapters for the extending the JDBC Translator. Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-10 23:14:14 UTC (rev 2219) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -51,7 +51,7 @@ <xi:include href="content/command-language.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/lob-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/extending-jdbc-connector.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/jdbc-translator-examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </book> Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-10 23:14:14 UTC (rev 2219) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -321,7 +321,7 @@ </sect2> </sect1> - <sect1> + <sect1 id="translator_package"> <title>Packaging</title> <para>Once the "ExecutionFactory" class is implemented, package it in a JAR file. The only additional requirement is provide a file called "jboss-beans.xml" in the "META-INF" directory of the JAR file, with @@ -353,7 +353,7 @@ available properties in configuration for this Translator for tooling and Admin API.</para> </sect1> - <sect1> + <sect1 id="translator_deploy"> <title>Deployment</title> <para>Copy the JAR file that defines the Translator into "deploy" directory of the JBoss AS's chosen profile, and Translator will be deployed automatically. There is no restriction that, JBoss AS need to be restarted. However, if your Translator Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml 2010-06-10 23:14:14 UTC (rev 2219) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -1,212 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="examples"> - <title>JDBC Extension Examples</title> - <para>This chapter contains a series of examples showing how to extend the JDBC Connector for different common scenarios. </para> - <sect1> - <title>Adding Support for a Scalar Function</title> - <sect2> - <title>Overview</title> - <para>For this example we consider how a connector might provide support for accepting a function supported by MetaMatrix. See the following section for adding support for a new function unknown to MetaMatrix. This example will show you how to declare support for the function and modify how the function is passed to the data source.</para> - <para>Following is a summary of all the steps in supporting a new scalar function:</para> - <orderedlist> - <listitem> - <para>Modify the capabilities class to declare support for the function (REQUIRED)</para> - </listitem> - <listitem> - <para>Implement a FunctionModifier to change how a function is translated (OPTIONAL)</para> - </listitem> - <listitem> - <para>Implement a SQLTranslator extension and register the new function modifier (OPTIONAL)</para> - </listitem> - </orderedlist> - <para>The capabilities class has a method getSupportedFunctions() that declares all the scalar functions that can be supported by the connector. To add support for a new function, extend an existing capabilities class (like the base JDBC class JDBCCapabilities or the provided base class in the Connector API, BasicConnectorCapabilities). </para> - <para>Below is an example of an extended capabilities class to add support for the “abs” absolute value function:</para> - <programlisting><![CDATA[ - package my.connector; - - import java.util.ArrayList; - import java.util.List; - import com.metamatrix.connector.jdbc.JDBCCapabilities; - - public class ExtendedCapabilities extends JDBCCapabilities { - public List getSupportedFunctions() { - List supportedFunctions = new ArrayList(); - supportedFunctions.addAll(super.getSupportedFunctions()); - supportedFunctions.add("ABS"); - return supportedFunctions; - } - } - ]]></programlisting> - <para>In general, it is a good idea to call super.getSupportedFunctions() to ensure that you retain any function support provided by the connector you are extending.</para> - <para>This may be all that is needed to support a MetaMatrix function if the JDBC data source supports the same syntax as MetaMatrix. The built-in SQL translation will translate most functions as: “function(arg1, arg2, …)”.</para> - </sect2> - <sect2> - <title>Using FunctionModifiers</title> - <para>In some cases you may need to translate the function differently or even insert additional function calls above or below the function being translated. The JDBC Connector provides an interface FunctionModifier and a base class BasicFunctionModifier that can be used to register function translations in a SQLTranslator extension. </para> - <para>The FunctionModifier interface has two methods: modify and translate. Generally, it is recommended to subclass BasicFunctionModifier and override one method or the other, but not both. Use the modify method to modify the function language objects or otherwise change the attributes of the existing function. Use the translate method to change the way the function is represented; this is typically only necessary when using a non-standard function form with special operators or ways of representing parameters. </para> - <para>Below is an example of using a FunctionModifier to modify the incoming function. This particular example is from the Oracle JDBC Connector and is translating the MetaMatrix function HOUR(ts) which takes a timestamp and returns the hour part into the Oracle equivalent TO_NUMBER(TO_CHAR(ts, ‘HH24’)). It demonstrates the use of the ILanguageFactory to construct new functions and literal values.</para> - <programlisting><![CDATA[ - package com.metamatrix.connector.jdbc.oracle; - - import com.metamatrix.connector.jdbc.extension.FunctionModifier; - import com.metamatrix.connector.jdbc.extension.impl.BasicFunctionModifier; - import com.metamatrix.data.language.*; - - /** - * Convert the HOUR function into an equivalent Oracle function. - * HOUR(ts) --> TO_NUMBER(TO_CHAR(ts, 'HH24')) - */ - public class HourFunctionModifier extends BasicFunctionModifier implements FunctionModifier { - - private ILanguageFactory langFactory; - - public HourFunctionModifier(ILanguageFactory langFactory) { - this.langFactory = langFactory; - } - - public IExpression modify(IFunction function) { - IExpression[] args = function.getParameters(); - - IFunction innerFunction = langFactory.createFunction("TO_CHAR", - new IExpression[] { - args[0], - langFactory.createLiteral("HH24", String.class)}, - String.class); - - IFunction outerFunction = langFactory.createFunction("TO_NUMBER", - new IExpression[] { innerFunction }, - Integer.class); - - return outerFunction; - } - } - ]]></programlisting> - - <para>Below is an example of overriding just the translate method to translate the MOD(a, b) function into an operator form for Sybase (a % b). The translate method returns a list of strings and language objects that will be assembled by the translator into a final string. The strings will be used as is and the language objects will be further processed by the translator.</para> - - <programlisting><![CDATA[ - package com.metamatrix.connector.jdbc.sybase; - - import java.util.ArrayList; - import java.util.List; - - import com.metamatrix.connector.jdbc.extension.FunctionModifier; - import com.metamatrix.data.language.IExpression; - import com.metamatrix.data.language.IFunction; - - public class ModFunctionModifier implements FunctionModifier { - - public IExpression modify(IFunction function) { - return function; - } - - public List translate(IFunction function) { - List parts = new ArrayList(); - parts.add("("); - IExpression[] args = function.getParameters(); - parts.add(args[0]); - parts.add(" % "); - parts.add(args[1]); - parts.add(")"); - return parts; - } - } - ]]></programlisting> - - <para>In addition to building your own FunctionModifiers, there are a number of pre-built generic function modifiers that are provided with the connector. </para> - - <table frame='all'> - <title>Connection Factories</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth=".5*"/> - <thead> - <row> - <entry><para>Modifier</para></entry> - <entry><para>Description</para></entry> - </row> - </thead> - <tbody> - <row> - <entry><para>AliasModifier</para></entry> - <entry><para>Handles simply renaming a function (“ucase” to “upper” for example)</para></entry> - </row> - <row> - <entry><para>DropFunctionModifier</para></entry> - <entry><para>Replaces a function with the function’s first argument, effectively dropping the function call if it is unnecessary – useful with unneeded type conversions</para></entry> - </row> - <row> - <entry><para>EscapeSyntaxModifier</para></entry> - <entry><para>Wraps a function in the standard JDBC escape syntax for functions: {fn xxxx()}</para></entry> - </row> - </tbody> - </tgroup> - </table> - <para>To register the function modifiers for your supported functions, you must implement a SQLTranslator extension class. Below is an example that registers some functions.</para> - <programlisting><![CDATA[ - package my.connector; - - import java.util.HashMap; - import java.util.Map; - - import com.metamatrix.connector.jdbc.extension.impl.BasicSQLTranslator; - import com.metamatrix.data.api.ConnectorEnvironment; - import com.metamatrix.data.exception.ConnectorException; - import com.metamatrix.data.metadata.runtime.RuntimeMetadata; - - public class ExtendedSQLTranslator extends BasicSQLTranslator { - - private Map modifiers; - - public void initialize(ConnectorEnvironment env, RuntimeMetadata metadata) - throws ConnectorException { - - super.initialize(env, metadata); - - modifiers = new HashMap(super.getFunctionModifiers()); - modifiers.put("abs", new MyAbsModifier()); - modifiers.put("concat", new AliasModifier(“concat2”)); - } - - public Map getFunctionModifiers() { - return this.modifiers; - } - } - ]]></programlisting> - <para>Support for the two functions being registered (“abs” and “concat”) must be declared in the capabilities class as well. Functions that do not have modifiers registered will be translated as usual. In this example, no attempt is made to add to the list of modifiers for the parent class as it does not register any modifiers. However, if you are extending an existing SQLTranslator, you may need to take this into account to add support rather than replace those modifiers defined by the parent class.</para> - </sect2> - </sect1> - <sect1> - <title>Pushdown Scalar Functions</title> - <para>“Pushdown” scalar functions are special in that they are functions new to MetaMatrix that can be “pushed down” to the connector. Implementing support for a pushdown scalar function is identical to implementing support for a standard MetaMatrix function except that the function must be declared to MetaMatrix as such. This allows MetaMatrix to properly parse and resolve queries using the pushdown function.</para> - <para>Pushdown scalar functions are modeled as user-defined functions with a special attribute. They differ from normal user-defined functions in that no code is provided and the MetaMatrix engine does not how to execute the function. Pushdown functions typically must be passed to the connector for evaluation. User-defined scalar functions have a special pushdown attribute that should be set to “Required” when modeling a pushdown function. </para> - <para>For more information on modeling user-defined scalar functions, see the MetaMatrix Custom Scalar Functions Tutorial.</para> - </sect1> - - <sect1> - <title>Connection Pool Test Queries</title> - <para>The JDBCSourceConnectionFactory provides a method createConnectionStrategy() that allows subclasses to provide a custom implementation of the ConnectionStrategy interface. The ConnectionStrategy interface provides a means to check a JDBC Connection for whether it is alive or dead. If no ConnectionStrategy is specified by returning null (the default), then the Connection.isClosed() method is used to check this. </para> - <para>However, the isClosed() method does not actively test the connection to the database in most JDBC drivers. By providing an instance of the ConnectionQueryStrategy, you can cause a test query to be executed against the data source instead. </para> - <para>Below is an example from the DB2 Connector that creates a custom connection factory that uses a DB2-specific test query to test connection liveliness:</para> - - <programlisting><![CDATA[ - package com.metamatrix.connector.jdbc.db2; - - import com.metamatrix.connector.jdbc.ConnectionQueryStrategy; - import com.metamatrix.connector.jdbc.ConnectionStrategy; - import com.metamatrix.connector.jdbc.JDBCSingleIdentityConnectionFactory; - - public class DB2SingleIdentityConnectionFactory extends JDBCSingleIdentityConnectionFactory{ - private String queryTest = "Select 'x' from sysibm.systables where 1 = 2"; - - protected ConnectionStrategy createConnectionStrategy() { - return new ConnectionQueryStrategy(queryTest, - this.sourceConnectionTestInterval); - } - } - ]]></programlisting> - - <para>It is recommended that you for any custom JDBC Connector you should implement a custom connection factory extension as this will allow the pool to better manage connections and detect data source failures accurately.</para> - </sect1> -</chapter> \ No newline at end of file Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml 2010-06-10 23:14:14 UTC (rev 2219) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -2,47 +2,38 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="extendingjdbc"> <title>Extending the JDBC Connector</title> - <para>The JDBC Connector can be extended to handle new JDBC drivers and database versions. This chapter outlines the process by which a customer or consultant can modify the behavior of the JDBC Connector for a new source</para> + <para>The JDBC Connector can be extended to handle new JDBC drivers and database versions. This chapter + outlines the process by which a user can modify the behavior of the JDBC Connector for a new source</para> <sect1> <title>Extension Interfaces</title> - <para>The JDBC Connector provides four extension interfaces that can be used to customize its behavior. Activate an extension by implementing the appropriate interface and specifying the implementation class name in the appropriate connector binding property.</para> - <para>The JDBC Connector loads each of the implementations of these interfaces via reflection and requires that each of these classes have a no-argument constructor. Each extension class will be loaded exactly once and use for the life of a connector binding. Connector bindings never share instances of the extension classes.</para> - <para>This table summarizes the available extension points and their purpose. Following the table is a more detailed look at each extension type.</para> + <para>To design JDBC Translator for any RDMS that are not already provided by the Teiid, extend the + <emphasis>org.teiid.translator.jdbc.JDBCExecutionFactory</emphasis> class in the "translator-jdbc" module. There + are three types of methods that you can override from the base class to define the behavior of the Translator.</para> <table frame='all'> - <title>Extension Interfaces</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <title>Extension methods</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth=".5*"/> - <colspec colname='c3' colwidth="2*"/> + <colspec colname='c2' colwidth="2*"/> <thead> <row> <entry><para>Extension</para></entry> - <entry><para>Connector Property</para></entry> <entry><para>Purpose</para></entry> </row> </thead> <tbody> <row> - <entry><para>Connection Factory</para></entry> - <entry><para>ExtensionConnectionFactoryClass</para></entry> - <entry><para>Customize connection creation and pooling.</para></entry> - </row> - <row> - <entry><para>Connector Capabilities</para></entry> - <entry><para>ExtensionCapabilityClass</para></entry> + <entry><para>Translator Capabilities</para></entry> <entry><para>Specify the SQL syntax and functions the source supports.</para></entry> </row> <row> <entry><para>SQL Translator</para></entry> - <entry><para>ExtensionSQLTranslationClass</para></entry> <entry><para>Customize what SQL syntax is used, how source-specific functions are supported, how procedures are executed.</para></entry> </row> <row> <entry><para>Results Translator</para></entry> - <entry><para>ExtensionResultsTranslationClass</para></entry> <entry><para>Customize how results are retrieved from JDBC and translated.</para></entry> </row> </tbody> @@ -50,78 +41,22 @@ </table> <sect2> - <title>Connection Factory Extension</title> - <para>The Connection Factory extension can be used to plug in a new factory for creating JDBC Connection objects. The factory class is used within the JDBC connection pool and also controls how connections are pooled and maintained. The Connection Factory implementation class is constructed once and reused throughout the life of the connector.</para> - <para>The interface to implement is the standard connection factory interface from the Connector API connection pool utility: com.metamatrix.data.pool.SourceConnectionFactory. This interface and its implementation are described in detail in the Connector Developer’s Guide chapter on connection pooling. </para> - <para>However, the JDBC Connector provides a number of useful abstract implementations that can make the implementation somewhat easier:</para> - - <table frame='all'> - <title>Connection Factories</title> - <tgroup cols='4' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth=".5*"/> - <colspec colname='c3' colwidth="2*"/> - <colspec colname='c4' colwidth="2*"/> - <thead> - <row> - <entry><para>Class</para></entry> - <entry><para>Pooling</para></entry> - <entry><para>Connection Type</para></entry> - <entry><para>Description</para></entry> - </row> - </thead> - <tbody> - <row> - <entry><para>SourceConnection Factory</para></entry> - <entry><para>Depends on implementation</para></entry> - <entry><para>Depends on implementation</para></entry> - <entry><para>This is the basic interface – implementing at this level gives you complete freedom to create connections and control pooling in whatever way necessary.</para></entry> - </row> - <row> - <entry><para>JDBCSource ConnectionFactory</para></entry> - <entry><para>Depends on implementation</para></entry> - <entry><para>Depends on implementation</para></entry> - <entry><para>Adds JDBC-specific facilities for connection events, interpreting transaction isolation levels, strategies for determing whether connection is alive, etc.</para></entry> - </row> - <row> - <entry><para>JDBCSingleIdentity ConnectionFactory</para></entry> - <entry><para>Create a single connection pool for all connections in a connector binding using the connector binding connection properties.</para></entry> - <entry><para>DriverManager</para></entry> - <entry><para>Uses a single pool (the most common usage) and DriverManager to obtain connections.</para></entry> - </row> - <row> - <entry><para>JDBCSingleIdentity DSConnectionFactory</para></entry> - <entry><para>Create a single connection pool for all connections in a connector binding using the connector binding connection properties.</para></entry> - <entry><para>DataSource</para></entry> - <entry><para>Uses a single pool (the most common usage) and a DataSource to obtain connections.</para></entry> - </row> - <row> - <entry><para>JDBCUserIdentity ConnectionFactory</para></entry> - <entry><para>Create one pool per MetaMatrix user. Subclasses must determine how to obtain each user’s authentication information from the connector properties or trusted payloads.</para></entry> - <entry><para>DriverManager</para></entry> - <entry><para>Uses a per-user pool when pooling connections.</para></entry> - </row> - </tbody> - </tgroup> - </table> - <para>For more information on how to subclass and use these abstract classes, see the examples later in this chapter.</para> + <title>Translator Capabilities Extension</title> + <para>This extension must override the methods that begin with "supports" that describe translator capabilities. + For all the available translator capabilities please see <link linkend="translator_capabilities">this</link>.</para> + + <para>The most common example is adding + support for a scalar function – this requires both declaring that the translator has the capability + to execute the function and often modifying the SQL Translator to translate the function appropriately for the source.</para> + <para>Another common example is turning off unsupported SQL capabilities (such as outer joins or subqueries) + for less sophisticated JDBC sources. </para> </sect2> - - <sect2> - <title>Connector Capabilities Extension</title> - <para>This extension must implement the com.metamatrix.data.api.ConnectorCapabilities interface, which is the standard Connector API interface for describing connector capabilities. </para> - <para>It is strongly recommended that any implementation of the ConnectorCapabilities interface should subclass the JDBC version com.metamatrix.connector.jdbc.extension.JDBCCapabilities or minimally, the com.metamatrix.data.basic.BasicConnectorCapabilities base class. Subclassing these will protect custom implementations from breaking when new capabilities are added to the API. </para> - <para>This extension often must be modified in tandem with the SQL Translation Extension to modify the capabilities of the connector. The most common example is adding support for a scalar function – this requires both declaring that the connector has the capability to execute the function and often modifying the SQL Translator to translate the function appropriately for the source.</para> - <para>Another common example is turning off unsupported SQL capabilities (such as outer joins or subqueries) for less sophisticated JDBC sources. </para> - </sect2> <sect2> <title>SQL Translation Extension</title> - <para>The com.metamatrix.connector.jdbc.extension.SQLTranslator interface defines this extension. It provides ways to modify the command entering the JDBC Connector (in object form) before it is sent to the JDBC driver (as an SQL string). The JDBC Connector defines a base class that should be subclassed when implementing this extension</para> + <para>It provides ways to modify the command entering the JDBC Connector (in object form) before it is sent to the + JDBC driver (as an SQL string).</para> - <para><emphasis>com.metamatrix.connector.jdbc.extension.impl.BasicSQLTranslator</emphasis></para> - - <para>The SQLTranslator implementation class is constructed once and reused throughout the life of the connector, so it must not maintain any query-specific state. </para> <para>Common functions that the SQLTranslator can perform are:</para> <orderedlist> @@ -140,7 +75,9 @@ <sect2> <title>Results Translation Extension</title> - <para>The com.metamatrix.connector.jdbc.extension.ResultsTranslator interface defines ways to modify the results as they are read and returned from the JDBC driver to the MetaMatrix Server. The ResultsTranslator implementation class is constructed once and reused throughout the life of the connector, so it should generally not maintain any query-specific state. Common functions that the ResultsTranslator can perform are:</para> + <para>This defines ways to modify the results + as they are read and returned from the JDBC driver to the Teiid Server. Common functions that the + ResultsTranslator can perform are:</para> <orderedlist> <listitem> <para>Execute a stored procedure against the driver</para> @@ -168,62 +105,17 @@ <sect1> <title>Developing Extensions</title> - <para>When developing a new JDBC Connector extension, you should start with the development environment used to develop any connector, as defined in the Connector Developer’s Guide. Standard connector development requires the inclusion of the following jar: </para> - <orderedlist> - <listitem> - <para>metamatrix-cdk.jar – This jar contains the complete environment needed for developing custom connectors. It can be found in the MetaMatrix Tools kit.</para> - </listitem> - <listitem> - <para>jdbcconn.jar – The JDBC Connector jar, which can be found in the MetaMatrix Server’s installation directory under SERVER\config\extensions or exported from the pre-installed extension modules in the MetaMatrix Console.</para> - </listitem> - <listitem> - <para>MetaMatrixLicense.xml – A valid license for the MetaMatrix JDBC Connector. Your classpath should include a directory containing this file. </para> - </listitem> - <listitem> - <para>MJjdbc.jar – OPTIONAL – If extending an existing MetaMatrix JDBC Connector for access to Oracle, SQL Server, DB2, or Sybase, you may need this jar that contains the actual JDBC drivers for those sources.</para> - </listitem> - </orderedlist> + <para>When developing a new JDBC Translator extension, you should start with the development environment used to develop + any translator, as defined in the Translator Developer’s Guide.</para> </sect1> <sect1> <title>Installing Extensions</title> - <para>Once you have developed an extension to the JDBC Connector, you must install it into the MetaMatrix Server. This process involves creating and installing a Connector Archive File (CAF). Refer to the Connector Developer’s Guide for instructions on creating and installing CAF files.</para> - - <sect2> - <title>Connector Archive File Contents</title> - <para>When creating your Connector Archive File, you need to include the following jars:</para> - <orderedlist> - <listitem> - <para>jdbcconn.jar (described above) – This contains the base JDBC Connector code.</para> - </listitem> - <listitem> - <para>JDBC drivers – Any drivers needed to access the data source must be included. If you are extending the MetaMatrix JDBC Connector for Oracle, SQL Server, DB2, or Sybase, you will need to include MJjdbc.jar.</para> - </listitem> - <listitem> - <para>Connector jars – Any custom code that extends the JDBC Connector must be compiled and placed in a JAR file for inclusion in the CAF.</para> - </listitem> - <listitem> - <para>External libraries – Any additional JAR files that are needed by your connector must be included.</para> - </listitem> - <listitem> - <para>Other JDBC jars – OPTIONAL – If extending an existing MetaMatrix JDBC Connector other than those whose drivers are found in MJjdbc.jar (see list above), you will need the JDBC jar provided by that vendor. For example to extend the MySQL connector you would need their mysql-connector-java-5.1.5-bin.jar (5.1.5 is the version number and will vary).</para> - </listitem> - </orderedlist> - </sect2> - - <sect2> - <title>Connector Type Definition</title> - <para>In addition to the JAR files, you will need to create a Connector Type Definition file as described in the Connector Developer’s Guide. This Connector Type Definition file (.cdk file extension) is an XML file describing the properties needed by your JDBC Connector. </para> - <para>Typically, the easiest way to create a new Connector Type Definition file to extend the JDBC Connector is to export the JDBC Connector Type from the MetaMatrix Console and modify it. When doing this, you will need to modify the following items:</para> - <orderedlist> - <listitem> - <para>ComponentType Name – name your Connector Type</para> - </listitem> - <listitem> - <para>ComponentType SuperComponent – should be an existing Connector Type such as “JDBC Connector”. If you are extending an existing connector type, that should be specified as the SuperComponent</para> - </listitem> - </orderedlist> - <para>Property value defaults – each property’s default value should be reviewed and updated. In particular the extension class properties should be updated to activate your extension classes.</para> - </sect2> - </sect1> + <para>Once you have developed an extension to the JDBC translator, you must install it into the Teiid Server. + The process of <link linkend="translator_package">packaging</link> or <link linkend="translator_deploy">deploying</link> the + extended JDBC translators is exactly as any other other translator. Since the RDMS is accessible already through its JDBC + driver, there is no need to develop a resource adapter for this source as JBoss AS provides a wrapper JCA connector (DataSource) + for any JDBC driver. + </para> + </sect1> </chapter> \ No newline at end of file Copied: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml (from rev 2217, trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml) =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml (rev 0) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -0,0 +1,183 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="examples"> + <title>JDBC Extension Examples</title> + <para>This chapter contains a series of examples showing how to extend the JDBC Connector for different common scenarios. </para> + <sect1> + <title>Adding Support for a Scalar Function</title> + <sect2> + <title>Overview</title> + <para>For this example we consider how a translator might provide support for accepting + a function supported by Teiid. See the following section for adding support for a new + function unknown to Teiid. This example will show you how to declare support for the function + and modify how the function is passed to the data source.</para> + <para>Following is a summary of all the steps in supporting a new scalar function:</para> + <orderedlist> + <listitem> + <para>Override the capabilities method to declare support for the function (REQUIRED)</para> + </listitem> + <listitem> + <para>Implement a FunctionModifier to change how a function is translated (OPTIONAL)</para> + </listitem> + <listitem> + <para>Implement a SQLTranslator extension and register the new function modifier (OPTIONAL)</para> + </listitem> + </orderedlist> + <para>The capabilities class has a method getSupportedFunctions() that declares all the scalar functions that can be supported by the connector. To add support for a new function, extend an existing capabilities class (like the base JDBC class JDBCCapabilities or the provided base class in the Connector API, BasicConnectorCapabilities). </para> + <para>Below is an example of an extended capabilities class to add support for the “abs” absolute value function:</para> + <programlisting><![CDATA[ + package my.connector; + + import java.util.ArrayList; + import java.util.List; + + public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory { + @Override + public List getSupportedFunctions() { + List supportedFunctions = new ArrayList(); + supportedFunctions.addAll(super.getSupportedFunctions()); + supportedFunctions.add("ABS"); + return supportedFunctions; + } + } + ]]></programlisting> + <para>In general, it is a good idea to call super.getSupportedFunctions() to ensure that you retain any function + support provided by the translator you are extending.</para> + <para>This may be all that is needed to support a Teiid function if the JDBC data source supports the + same syntax as Teiid. The built-in SQL translation will translate most functions as: “function(arg1, arg2, …)”.</para> + </sect2> + <sect2> + <title>Using FunctionModifiers</title> + <para>In some cases you may need to translate the function differently or even insert + additional function calls above or below the function being translated. The JDBC translator provides + an abstract class <emphasis>FunctionModifier</emphasis> can be used to register function + translations in a SQLTranslator extension. </para> + + <para>The FunctionModifier has method called "translate". Generally, it is recommended + to subclass FunctionModifier and override the method. + Use the translate method to change the way the function is represented; + this is typically only necessary when using a non-standard function form with special operators or + ways of representing parameters. </para> + + <para>Below is an example of overriding just the translate method to translate the MOD(a, b) function into an operator form for Sybase (a % b). The translate method returns a list of strings and language objects that will be assembled by the translator into a final string. The strings will be used as is and the language objects will be further processed by the translator.</para> + + <programlisting><![CDATA[ + + public class ModFunctionModifier implements FunctionModifier { + + public List translate(Function function) { + List parts = new ArrayList(); + parts.add("("); + Expression[] args = function.getParameters(); + parts.add(args[0]); + parts.add(" % "); + parts.add(args[1]); + parts.add(")"); + return parts; + } + } + ]]></programlisting> + + <para>You can also extend the <emphasis>AliasModifier</emphasis> that defines a method called "modify" + using which you can modify in coming function from Teiid server into some thing that is source specific.</para> + + <para>Below is an example of using a AliasFunctionModifier to modify the incoming function. This particular + example is from the Oracle JDBC Translator and is translating the Teiid function HOUR(ts) which takes a + timestamp and returns the hour part into the Oracle equivalent TO_NUMBER(TO_CHAR(ts, ‘HH24’)). + It demonstrates the use of the LanguageFactory to construct new functions and literal values.</para> + <programlisting><![CDATA[ + /** + * Convert the HOUR function into an equivalent Oracle function. + * HOUR(ts) --> TO_NUMBER(TO_CHAR(ts, 'HH24')) + */ + public class HourFunctionModifier extends AliasFunctionModifier { + + private LanguageFactory langFactory; + + public HourFunctionModifier(LanguageFactory langFactory) { + this.langFactory = langFactory; + } + + public Expression modify(Function function) { + Expression[] args = function.getParameters(); + + Function innerFunction = langFactory.createFunction("TO_CHAR", + new Expression[] { + args[0], + langFactory.createLiteral("HH24", String.class)}, String.class); + + Function outerFunction = langFactory.createFunction("TO_NUMBER", + new Expression[] { innerFunction },Integer.class); + + return outerFunction; + } + } + ]]></programlisting> + + <para>In addition to building your own FunctionModifiers, there are a number of pre-built generic + function modifiers that are provided with the translator. </para> + + <table frame='all'> + <title>Connection Factories</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth=".5*"/> + <thead> + <row> + <entry><para>Modifier</para></entry> + <entry><para>Description</para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para>AliasModifier</para></entry> + <entry><para>Handles simply renaming a function (“ucase” to “upper” for example)</para></entry> + </row> + <row> + <entry><para>DropFunctionModifier</para></entry> + <entry><para>Replaces a function with the function’s first argument, effectively dropping the function call if it is unnecessary – useful with unneeded type conversions</para></entry> + </row> + <row> + <entry><para>EscapeSyntaxModifier</para></entry> + <entry><para>Wraps a function in the standard JDBC escape syntax for functions: {fn xxxx()}</para></entry> + </row> + </tbody> + </tgroup> + </table> + <para>To register the function modifiers for your supported functions, + you must implement call " public void registerFunctionModifier(String name, FunctionModifier modifier)" method. + Below is an example that registers some functions.</para> + <programlisting><![CDATA[ + + public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory + + @Override + public void start() { + super.start(); + + // register functions. + registerFunctionModifier("abs", new MyAbsModifier()); + registerFunctionModifier("concat", new AliasModifier(“concat2”)); + } + } + ]]></programlisting> + <para>Support for the two functions being registered (“abs” and “concat”) must be declared + in the capabilities as well. Functions that do not have modifiers registered will be translated as usual. + </para> + </sect2> + </sect1> + <sect1> + <title>Pushdown Scalar Functions</title> + <para>“Pushdown” scalar functions are special in that they are functions new to Teiid that can be “pushed down” + to the translator. Implementing support for a pushdown scalar function is identical to implementing support + for a standard Teiid function except that the function must be declared to Teiid as such. This allows + Teiid to properly parse and resolve queries using the pushdown function.</para> + <para>Pushdown scalar functions are modeled as user-defined functions with a special attribute. + They differ from normal user-defined functions in that no code is provided and the + Teiid engine does not how to execute the function. Pushdown functions typically must be passed + to the translator for evaluation. User-defined scalar functions have a special pushdown attribute that should be + set to “Required” when modeling a pushdown function. </para> + <para>For more information on modeling user-defined scalar functions, see the Reference manual.</para> + </sect1> + +</chapter> \ No newline at end of file Property changes on: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml ___________________________________________________________________ Name: svn:mime-type + text/plain