From teiid-commits at lists.jboss.org Thu Jun 10 20:22:29 2010 Content-Type: multipart/mixed; boundary="===============7215867151602198555==" MIME-Version: 1.0 From: teiid-commits at lists.jboss.org To: teiid-commits at lists.jboss.org Subject: [teiid-commits] teiid SVN: r2220 - in trunk/documentation/connector-developer-guide/src/main/docbook/en-US: content and 1 other directory. Date: Thu, 10 Jun 2010 20:22:29 -0400 Message-ID: <201006110022.o5B0MT3C009834@svn01.web.mwc.hst.phx2.redhat.com> --===============7215867151602198555== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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/con= tent/jdbc-translator-examples.xml Removed: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/con= tent/examples.xml Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/con= nector_developer_guide.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/con= tent/connector-api.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/con= tent/extending-jdbc-connector.xml Log: TEIID-315: Adding the updated chapters for the extending the JDBC Translato= r. Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en= -US/connector_developer_guide.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= nnector_developer_guide.xml 2010-06-10 23:14:14 UTC (rev 2219) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= nnector_developer_guide.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -51,7 +51,7 @@ - + = Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en= -US/content/connector-api.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= ntent/connector-api.xml 2010-06-10 23:14:14 UTC (rev 2219) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= ntent/connector-api.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -321,7 +321,7 @@ = - + Packaging 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. = - + Deployment 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= ntent/examples.xml 2010-06-10 23:14:14 UTC (rev 2219) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= ntent/examples.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -1,212 +0,0 @@ - - - - JDBC Extension Examples - This chapter contains a series of examples showing how to extend t= he JDBC Connector for different common scenarios. - - Adding Support for a Scalar Function - - Overview - For this example we consider how a connector might provide sup= port for accepting a function supported by MetaMatrix. See the following s= ection for adding support for a new function unknown to MetaMatrix. This e= xample will show you how to declare support for the function and modify how= the function is passed to the data source. - Following is a summary of all the steps in supporting a new sc= alar function: - - - Modify the capabilities class to declare support for the= function (REQUIRED) - - - Implement a FunctionModifier to change how a function is= translated (OPTIONAL) - - - Implement a SQLTranslator extension and register the new= function modifier (OPTIONAL) - - = - The capabilities class has a method getSupportedFunctions() th= at 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 t= he Connector API, BasicConnectorCapabilities). - Below is an example of an extended capabilities class to add s= upport for the =E2=80=9Cabs=E2=80=9D absolute value function: - = - In general, it is a good idea to call super.getSupportedFu= nctions() to ensure that you retain any function support provided by the co= nnector you are extending. - This may be all that is needed to support a MetaMatrix fun= ction if the JDBC data source supports the same syntax as MetaMatrix. The = built-in SQL translation will translate most functions as: =E2=80=9Cfunctio= n(arg1, arg2, =E2=80=A6)=E2=80=9D. = - - - Using FunctionModifiers - In some cases you may need to translate the function different= ly or even insert additional function calls above or below the function bei= ng translated. The JDBC Connector provides an interface FunctionModifier a= nd a base class BasicFunctionModifier that can be used to register function= translations in a SQLTranslator extension. - The FunctionModifier interface has two methods: modify and tra= nslate. 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 func= tion is represented; this is typically only necessary when using a non-stan= dard function form with special operators or ways of representing parameter= s. - Below is an example of using a FunctionModifier to modify the = incoming function. This particular example is from the Oracle JDBC Connect= or and is translating the MetaMatrix function HOUR(ts) which takes a times= tamp and returns the hour part into the Oracle equivalent TO_NUMBER(TO_CHAR= (ts, =E2=80=98HH24=E2=80=99)). It demonstrates the use of the ILanguageFac= tory to construct new functions and literal values. - TO_NUMBER(TO_CHAR(ts, 'HH24')) - */ - public class HourFunctionModifier extends BasicFunctionModifier = implements FunctionModifier { - = - private ILanguageFactory langFactory; - = - public HourFunctionModifier(ILanguageFactory langFactory) { - this.langFactory =3D langFactory; - } - = - public IExpression modify(IFunction function) { - IExpression[] args =3D function.getParameters(); - = - IFunction innerFunction =3D langFactory.createFunction("= TO_CHAR", = - new IExpression[] { = - args[0], - langFactory.createLiteral("HH24", String.class)}= , = - String.class); = - = - IFunction outerFunction =3D langFactory.createFunction("= TO_NUMBER", = - new IExpression[] { innerFunction }, - Integer.class); = - = - return outerFunction; - } - } = - ]]> = - = - 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 tra= nslator. - = - = - - In addition to building your own FunctionModifiers, there are = a number of pre-built generic function modifiers that are provided with the= connector. - = - - Connection Factories - - - - = - - Modifier - Description - - - - - AliasModifier - Handles simply renaming a function (=E2=80=9Cuc= ase=E2=80=9D to =E2=80=9Cupper=E2=80=9D for example) - - - DropFunctionModifier - Replaces a function with the function=E2=80=99s= first argument, effectively dropping the function call if it is unnecessar= y =E2=80=93 useful with unneeded type conversions - - - EscapeSyntaxModifier - Wraps a function in the standard JDBC escape sy= ntax for functions: {fn xxxx()} - = - - -
- To register the function modifiers for your supported function= s, you must implement a SQLTranslator extension class. Below is an example= that registers some functions. - = - Support for the two functions being registered (=E2=80=9Cabs= =E2=80=9D and =E2=80=9Cconcat=E2=80=9D) must be declared in the capabilitie= s class as well. Functions that do not have modifiers registered will be t= ranslated 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 ta= ke this into account to add support rather than replace those modifiers def= ined by the parent class. - - - - Pushdown Scalar Functions - =E2=80=9CPushdown=E2=80=9D scalar functions are special in that = they are functions new to MetaMatrix that can be =E2=80=9Cpushed down=E2=80= =9D to the connector. Implementing support for a pushdown scalar function = is identical to implementing support for a standard MetaMatrix function exc= ept that the function must be declared to MetaMatrix as such. This allows = MetaMatrix to properly parse and resolve queries using the pushdown functio= n. - Pushdown scalar functions are modeled as user-defined functions = with a special attribute. They differ from normal user-defined functions i= n that no code is provided and the MetaMatrix engine does not how to execut= e the function. Pushdown functions typically must be passed to the connect= or for evaluation. User-defined scalar functions have a special pushdown a= ttribute that should be set to =E2=80=9CRequired=E2=80=9D when modeling a p= ushdown function. - For more information on modeling user-defined scalar functions, = see the MetaMatrix Custom Scalar Functions Tutorial. = - - = - - Connection Pool Test Queries - The JDBCSourceConnectionFactory provides a method createConnecti= onStrategy() that allows subclasses to provide a custom implementation of t= he 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. - However, the isClosed() method does not actively test the connec= tion 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. - 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: - = - = - = - It is recommended that you for any custom JDBC Connector you sho= uld implement a custom connection factory extension as this will allow the = pool to better manage connections and detect data source failures accuratel= y. - - \ No newline at end of file Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en= -US/content/extending-jdbc-connector.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= ntent/extending-jdbc-connector.xml 2010-06-10 23:14:14 UTC (rev 2219) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= ntent/extending-jdbc-connector.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -2,47 +2,38 @@ Extending the JDBC Connector - The JDBC Connector can be extended to handle new JDBC drivers and = database versions. This chapter outlines the process by which a customer o= r consultant can modify the behavior of the JDBC Connector for a new source= + 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 = = Extension Interfaces - The JDBC Connector provides four extension interfaces that can b= e used to customize its behavior. Activate an extension by implementing th= e appropriate interface and specifying the implementation class name in the= appropriate connector binding property. - The JDBC Connector loads each of the implementations of these in= terfaces via reflection and requires that each of these classes have a no-a= rgument constructor. Each extension class will be loaded exactly once and = use for the life of a connector binding. Connector bindings never share in= stances of the extension classes. - This table summarizes the available extension points and their p= urpose. Following the table is a more detailed look at each extension type= . + To design JDBC Translator for any RDMS that are not already prov= ided by the Teiid, extend the = + org.teiid.translator.jdbc.JDBCExecutionFactory cl= ass in the "translator-jdbc" module. There = + are three types of methods that you can override from the base class t= o define the behavior of the Translator. = - Extension Interfaces - + Extension methods + - - + = Extension - Connector Property Purpose - Connection Factory - ExtensionConnectionFactoryClass - Customize connection creation and pooling. - - - Connector Capabilities - ExtensionCapabilityClass + Translator Capabilities Specify the SQL syntax and functions the source= supports. SQL Translator - ExtensionSQLTranslationClass Customize what SQL syntax is used, how source-s= pecific functions are supported, how procedures are executed. Results Translator - ExtensionResultsTranslationClass Customize how results are retrieved from JDBC a= nd translated. = @@ -50,78 +41,22 @@
= - Connection Factory Extension - The Connection Factory extension can be used to plug in a ne= w factory for creating JDBC Connection objects. The factory class is used = within the JDBC connection pool and also controls how connections are poole= d and maintained. The Connection Factory implementation class is construct= ed once and reused throughout the life of the connector. - The interface to implement is the standard connection factor= y interface from the Connector API connection pool utility: com.metamatrix.= data.pool.SourceConnectionFactory. This interface and its implementation a= re described in detail in the Connector Developer=E2=80=99s Guide chapter o= n connection pooling. - However, the JDBC Connector provides a number of useful abst= ract implementations that can make the implementation somewhat easier: - - - Connection Factories - - - - - - = - - Class - Pooling - Connection Type - Description - - - - - SourceConnection Factory - Depends on implementation - Depends on implementation - This is the basic interface =E2=80=93 implement= ing at this level gives you complete freedom to create connections and cont= rol pooling in whatever way necessary. - - - JDBCSource ConnectionFactory - Depends on implementation - Depends on implementation - Adds JDBC-specific facilities for connection ev= ents, interpreting transaction isolation levels, strategies for determing w= hether connection is alive, etc. - - - JDBCSingleIdentity ConnectionFactory - Create a single connection pool for all connect= ions in a connector binding using the connector binding connection properti= es. - DriverManager - Uses a single pool (the most common usage) and = DriverManager to obtain connections. - - - JDBCSingleIdentity DSConnectionFactory - Create a single connection pool for all connect= ions in a connector binding using the connector binding connection properti= es. - DataSource - Uses a single pool (the most common usage) and = a DataSource to obtain connections. - - - JDBCUserIdentity ConnectionFactory - Create one pool per MetaMatrix user. Subclasse= s must determine how to obtain each user=E2=80=99s authentication informati= on from the connector properties or trusted payloads. - DriverManager - Uses a per-user pool when pooling connections.<= /para> - = - - -
- For more information on how to subclass and use these abstract= classes, see the examples later in this chapter. + Translator Capabilities Extension + This extension must override the methods that begin with "su= pports" that describe translator capabilities. + For all the available translator capabilities please see this. + = + The most common example is adding = + support for a scalar function =E2=80=93 this requires both declari= ng that the translator has the capability = + to execute the function and often modifying the SQL Translator to = translate the function appropriately for the source. + Another common example is turning off unsupported SQL capabi= lities (such as outer joins or subqueries) = + for less sophisticated JDBC sources. = - = - - Connector Capabilities Extension - This extension must implement the com.metamatrix.data.api.Co= nnectorCapabilities interface, which is the standard Connector API interfac= e for describing connector capabilities. - It is strongly recommended that any implementation of the Co= nnectorCapabilities interface should subclass the JDBC version com.metamatr= ix.connector.jdbc.extension.JDBCCapabilities or minimally, the com.metamatr= ix.data.basic.BasicConnectorCapabilities base class. Subclassing these wil= l protect custom implementations from breaking when new capabilities are ad= ded to the API. - This extension often must be modified in tandem with the SQL= Translation Extension to modify the capabilities of the connector. The mo= st common example is adding support for a scalar function =E2=80=93 this re= quires both declaring that the connector has the capability to execute the = function and often modifying the SQL Translator to translate the function a= ppropriately for the source. - Another common example is turning off unsupported SQL capabi= lities (such as outer joins or subqueries) for less sophisticated JDBC sour= ces. = - = SQL Translation Extension - The com.metamatrix.connector.jdbc.extension.SQLTranslator in= terface defines this extension. It provides ways to modify the command ent= ering the JDBC Connector (in object form) before it is sent to the JDBC dri= ver (as an SQL string). The JDBC Connector defines a base class that shoul= d be subclassed when implementing this extension + It provides ways to modify the command entering the JDBC Con= nector (in object form) before it is sent to the = + JDBC driver (as an SQL string). = - com.metamatrix.connector.jdbc.extension.impl.Basic= SQLTranslator - = - The SQLTranslator implementation class is constructed once a= nd reused throughout the life of the connector, so it must not maintain any= query-specific state. Common functions that the SQLTranslator can perform are: = @@ -140,7 +75,9 @@ = Results Translation Extension - The com.metamatrix.connector.jdbc.extension.ResultsTranslato= r interface defines ways to modify the results as they are read and returne= d from the JDBC driver to the MetaMatrix Server. The ResultsTranslator imp= lementation 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: + This defines ways to modify the results = + as they are read and returned from the JDBC driver to the Teiid Se= rver. Common functions that the = + ResultsTranslator can perform are: Execute a stored procedure against the driver @@ -168,62 +105,17 @@ = Developing Extensions - 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=E2=80=99s Guide. Standard connector developmen= t requires the inclusion of the following jar: - - - metamatrix-cdk.jar =E2=80=93 This jar contains the compl= ete environment needed for developing custom connectors. It can be found i= n the MetaMatrix Tools kit. - - - jdbcconn.jar =E2=80=93 The JDBC Connector jar, which can= be found in the MetaMatrix Server=E2=80=99s installation directory under S= ERVER\config\extensions or exported from the pre-installed extension module= s in the MetaMatrix Console. - - - MetaMatrixLicense.xml =E2=80=93 A valid license for the = MetaMatrix JDBC Connector. Your classpath should include a directory conta= ining this file. - - - MJjdbc.jar =E2=80=93 OPTIONAL =E2=80=93 If extending an = existing MetaMatrix JDBC Connector for access to Oracle, SQL Server, DB2, o= r Sybase, you may need this jar that contains the actual JDBC drivers for t= hose sources. - = - = + When developing a new JDBC Translator extension, you should star= t with the development environment used to develop = + any translator, as defined in the Translator Developer=E2=80=99s Guide= . = Installing Extensions - 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 Dev= eloper=E2=80=99s Guide for instructions on creating and installing CAF file= s. - = - - Connector Archive File Contents - When creating your Connector Archive File, you need to include= the following jars: - - - jdbcconn.jar (described above) =E2=80=93 This contains t= he base JDBC Connector code. - - - JDBC drivers =E2=80=93 Any drivers needed to access the = data source must be included. If you are extending the MetaMatrix JDBC Con= nector for Oracle, SQL Server, DB2, or Sybase, you will need to include MJj= dbc.jar. - - - Connector jars =E2=80=93 Any custom code that extends th= e JDBC Connector must be compiled and placed in a JAR file for inclusion in= the CAF. - - - External libraries =E2=80=93 Any additional JAR files th= at are needed by your connector must be included. - = - - Other JDBC jars =E2=80=93 OPTIONAL =E2=80=93 If extendin= g 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 b= y that vendor. For example to extend the MySQL connector you would need th= eir mysql-connector-java-5.1.5-bin.jar (5.1.5 is the version number and wil= l vary). - = - = - - = - - Connector Type Definition - In addition to the JAR files, you will need to create a Connec= tor Type Definition file as described in the Connector Developer=E2=80=99s = Guide. This Connector Type Definition file (.cdk file extension) is an XML= file describing the properties needed by your JDBC Connector. - Typically, the easiest way to create a new Connector Type Defi= nition file to extend the JDBC Connector is to export the JDBC Connector Ty= pe from the MetaMatrix Console and modify it. When doing this, you will ne= ed to modify the following items: - - - ComponentType Name =E2=80=93 name your Connector Type - - - ComponentType SuperComponent =E2=80=93 should be an exis= ting Connector Type such as =E2=80=9CJDBC Connector=E2=80=9D. If you are e= xtending an existing connector type, that should be specified as the SuperC= omponent - - = - Property value defaults =E2=80=93 each property=E2=80=99s defa= ult value should be reviewed and updated. In particular the extension clas= s properties should be updated to activate your extension classes. - - + Once you have developed an extension to the JDBC translator, you= must install it into the Teiid Server. = + The process of packaging o= r deploying the = + extended JDBC translators is exactly as any other other translator. Si= nce 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. = + + \ No newline at end of file Copied: trunk/documentation/connector-developer-guide/src/main/docbook/en-U= S/content/jdbc-translator-examples.xml (from rev 2217, trunk/documentation/= connector-developer-guide/src/main/docbook/en-US/content/examples.xml) =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= ntent/jdbc-translator-examples.xml (rev 0) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/co= ntent/jdbc-translator-examples.xml 2010-06-11 00:22:28 UTC (rev 2220) @@ -0,0 +1,183 @@ + + + + JDBC Extension Examples + This chapter contains a series of examples showing how to extend t= he JDBC Connector for different common scenarios. + + Adding Support for a Scalar Function + + Overview + For this example we consider how a translator might provide su= pport 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 declar= e support for the function = + and modify how the function is passed to the data source. + Following is a summary of all the steps in supporting a new sc= alar function: + + + Override the capabilities method to declare support for = the function (REQUIRED) + + + Implement a FunctionModifier to change how a function is= translated (OPTIONAL) + + + Implement a SQLTranslator extension and register the new= function modifier (OPTIONAL) + + = + The capabilities class has a method getSupportedFunctions() th= at 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 t= he Connector API, BasicConnectorCapabilities). + Below is an example of an extended capabilities class to add s= upport for the =E2=80=9Cabs=E2=80=9D absolute value function: + = + In general, it is a good idea to call super.getSupportedFu= nctions() to ensure that you retain any function = + support provided by the translator you are extending. + 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 transla= te most functions as: =E2=80=9Cfunction(arg1, arg2, =E2=80=A6)=E2=80=9D. = + + + Using FunctionModifiers + In some cases you may need to translate the function different= ly or even insert = + additional function calls above or below the function being translat= ed. The JDBC translator provides = + an abstract class FunctionModifier can be used= to register function = + translations in a SQLTranslator extension. + = + 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 represent= ed; = + this is typically only necessary when using a non-standard function = form with special operators or = + ways of representing parameters. + = + 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 tra= nslator. + = + = + = + You can also extend the AliasModifier tha= t defines a method called "modify" + using which you can modify in coming function from Teiid server into= some thing that is source specific. + = + 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 Te= iid function HOUR(ts) which takes a = + timestamp and returns the hour part into the Oracle equivalent TO_NU= MBER(TO_CHAR(ts, =E2=80=98HH24=E2=80=99)). = + It demonstrates the use of the LanguageFactory to construct new func= tions and literal values. + TO_NUMBER(TO_CHAR(ts, 'HH24')) + */ + public class HourFunctionModifier extends AliasFunctionModifier { + = + private LanguageFactory langFactory; + = + public HourFunctionModifier(LanguageFactory langFactory) { + this.langFactory =3D langFactory; + } + = + public Expression modify(Function function) { + Expression[] args =3D function.getParameters(); + = + Function innerFunction =3D langFactory.createFunction("T= O_CHAR", = + new Expression[] { = + args[0], + langFactory.createLiteral("HH24", String.class)}= , String.class); = + = + Function outerFunction =3D langFactory.createFunction("T= O_NUMBER", = + new Expression[] { innerFunction },Integer.class); = + = + return outerFunction; + } + } = + ]]> = + = + In addition to building your own FunctionModifiers, there are = a number of pre-built generic = + function modifiers that are provided with the translator. + = + + Connection Factories + + + + = + + Modifier + Description + + + + + AliasModifier + Handles simply renaming a function (=E2=80=9Cuc= ase=E2=80=9D to =E2=80=9Cupper=E2=80=9D for example) + + + DropFunctionModifier + Replaces a function with the function=E2=80=99s= first argument, effectively dropping the function call if it is unnecessar= y =E2=80=93 useful with unneeded type conversions + + + EscapeSyntaxModifier + Wraps a function in the standard JDBC escape sy= ntax for functions: {fn xxxx()} + = + + +
+ To register the function modifiers for your supported function= s, = + you must implement call " public void registerFunctionModifier(Strin= g name, FunctionModifier modifier)" method. + Below is an example that registers some functions. + = + Support for the two functions being registered (=E2=80=9Cabs= =E2=80=9D and =E2=80=9Cconcat=E2=80=9D) must be declared = + in the capabilities as well. Functions that do not have modifiers r= egistered will be translated as usual. = + + + + + Pushdown Scalar Functions + =E2=80=9CPushdown=E2=80=9D scalar functions are special in that = they are functions new to Teiid that can be =E2=80=9Cpushed down=E2=80=9D = + to the translator. Implementing support for a pushdown scalar functio= n is identical to implementing support = + for a standard Teiid function except that the function must be declare= d to Teiid as such. This allows = + Teiid to properly parse and resolve queries using the pushdown functio= n. + 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 prov= ided 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 =E2=80=9CRequired=E2=80=9D when modeling a pushdown function. = + For more information on modeling user-defined scalar functions, = see the Reference manual. = + + = + \ 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 --===============7215867151602198555==--