Author: rareddy Date: 2009-03-06 12:01:15 -0500 (Fri, 06 Mar 2009) New Revision: 538 Added: trunk/documentation/jdbc-connector-guide/ trunk/documentation/jdbc-connector-guide/pom.xml trunk/documentation/jdbc-connector-guide/src/ trunk/documentation/jdbc-connector-guide/src/main/ trunk/documentation/jdbc-connector-guide/src/main/docbook/ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/examples.xml trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/images/ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/images/logo.png trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml Log: TEIID-315: Adding the old document in the DOC book format Added: trunk/documentation/jdbc-connector-guide/pom.xml =================================================================== --- trunk/documentation/jdbc-connector-guide/pom.xml (rev 0) +++ trunk/documentation/jdbc-connector-guide/pom.xml 2009-03-06 17:01:15 UTC (rev 538) @@ -0,0 +1,70 @@ +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + <parent> + <groupId>org.jboss.teiid.documentation</groupId> + <artifactId>documentation</artifactId> + <version>6.0.0-SNAPSHOT</version> + </parent> + <modelVersion>4.0.0</modelVersion> + <artifactId>jdbc-connector</artifactId> + <packaging>jdocbook</packaging> + <name>JDBC Connector Guide</name> + <description>How JDBC Connector works and how to extend for other types of JDBC sources</description> + <build> + <plugins> + <plugin> + <groupId>org.jboss.maven.plugins</groupId> + <artifactId>maven-jdocbook-plugin</artifactId> + <version>2.1.2</version> + <extensions>true</extensions> + <dependencies> + <dependency> + <groupId>org.jboss</groupId> + <artifactId>jbossorg-docbook-xslt</artifactId> + <version>1.1.0</version> + </dependency> + <dependency> + <groupId>org.jboss</groupId> + <artifactId>jbossorg-jdocbook-style</artifactId> + <version>1.1.0</version> + <type>jdocbook-style</type> + </dependency> + </dependencies> + <configuration> + <sourceDocumentName>jdbc-connector.xml</sourceDocumentName> + <imageResource> + <directory>${basedir}/src/main/docbook/en-US</directory> + <excludes> + <exclude>*.xml</exclude> + <exclude>**/*.xml</exclude> + <exclude>*.zargo</exclude> + <exclude>**/*.zargo</exclude> + </excludes> + </imageResource> + <formats> + <format> + <formatName>pdf</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource> + <finalName>teiid_admin_guide.pdf</finalName> + </format> + <!-- <format> + <formatName>html_single</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource> + <finalName>index.html</finalName> + </format> --> + <format> + <formatName>html</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource> + <finalName>index.html</finalName> + </format> + </formats> + <options> + <xincludeSupported>true</xincludeSupported> + <localeSeparator>-</localeSeparator> + <useRelativeImageUris>false</useRelativeImageUris> + </options> + </configuration> + </plugin> + </plugins> + </build> +</project> Property changes on: trunk/documentation/jdbc-connector-guide/pom.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/examples.xml =================================================================== --- trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/examples.xml (rev 0) +++ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/examples.xml 2009-03-06 17:01:15 UTC (rev 538) @@ -0,0 +1,212 @@ +<?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>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 Property changes on: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/examples.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml =================================================================== --- trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml (rev 0) +++ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml 2009-03-06 17:01:15 UTC (rev 538) @@ -0,0 +1,229 @@ +<?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="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> + + + <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> + + <table frame='all'> + <title>Extension Interfaces</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth=".5*"/> + <colspec colname='c3' 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>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> + </tgroup> + </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> + </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><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> + <listitem> + <para>Arbitrarily modify the object form of a command before translation </para> + </listitem> + <listitem> + <para>Register one or more “function modifiers” that define how a scalar function should be modified or transformed</para> + </listitem> + <listitem> + <para>Change the way SQL strings are formed from the object for m of a command</para> + </listitem> + </orderedlist> + <para>For more information on how these functions can be performed, see the examples later in this chapter.</para> + </sect2> + + <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> + <orderedlist> + <listitem> + <para>Execute a stored procedure against the driver</para> + </listitem> + <listitem> + <para>Execute a prepared statement with large objects against the driver</para> + </listitem> + <listitem> + <para>Execute a statement for bulk insert</para> + </listitem> + <listitem> + <para>Retrieve values from the JDBC ResultSet</para> + </listitem> + <listitem> + <para>Translate values returned from JDBC into the types expected by MetaMatrix</para> + </listitem> + <listitem> + <para>Arbitrarily modify a batch of results</para> + </listitem> + </orderedlist> + + <para>For more information on how these functions can be performed, see the examples later in this chapter.</para> + </sect2> + </sect1> + + <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> + </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> +</chapter> \ No newline at end of file Property changes on: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/images/logo.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/images/logo.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml =================================================================== --- trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml (rev 0) +++ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml 2009-03-06 17:01:15 UTC (rev 538) @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + + JBoss, Home of Professional Open Source. + Copyright (C) 2008 Red Hat, Inc. + Licensed to Red Hat, Inc. under one or more contributor + license agreements. See the copyright.txt file in the + distribution for a full listing of individual contributors. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301 USA. + +--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY versionNumber "6.0.0 GA"> + <!ENTITY copyrightYear "2008"> + <!ENTITY copyrightHolder "Red Hat, Inc."> +]> + +<book> + <bookinfo> + <title>Teiid - Scalable Information Integration</title> + <subtitle>Teiid JDBC Connector Guide</subtitle> + <releaseinfo>&versionNumber;</releaseinfo> + <productnumber>&versionNumber;</productnumber> + <issuenum>1</issuenum> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/logo.png" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/logo.png" depth="3cm" /> + </imageobject> + </mediaobject> + <copyright> + <year>&copyrightYear;</year> + <holder>&copyrightHolder;</holder> + </copyright> + <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </bookinfo> + + <toc/> + + <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" /> + +</book> + Property changes on: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml (rev 0) +++ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml 2009-03-06 17:01:15 UTC (rev 538) @@ -0,0 +1,58 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + + JBoss, Home of Professional Open Source. + Copyright (C) 2008 Red Hat, Inc. + Licensed to Red Hat, Inc. under one or more contributor + license agreements. See the copyright.txt file in the + distribution for a full listing of individual contributors. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301 USA. + +--> +<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<legalnotice id="Legal_Notice"> + <title>Legal Notice</title> + <para> + <address> + <street>1801 Varsity Drive</street> + <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> + <phone>Phone: +1 919 754 3700</phone> + <phone>Phone: 888 733 4281</phone> + <fax>Fax: +1 919 754 3701</fax> + <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> + </address> + </para> + <para> + Copyright <trademark class="copyright"/> 2008 by Red Hat, Inc. This copyrighted material is made available to + anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the + GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published + by the Free Software Foundation. + </para> + <para> + Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. + </para> + <para> + All other trademarks referenced herein are the property of their respective owners. + </para> + <para> + The GPG fingerprint of the security(a)redhat.com key is: + </para> + <para> + CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E + </para> +</legalnotice> Property changes on: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml ___________________________________________________________________ Name: svn:mime-type + text/plain