<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
%CustomDTD;
]>
<chapter id="introduction">
  <title>Developing For Teiid</title>
  
  <section>
  <title>Introduction to the Teiid Connector Architecture</title>
  
  <orderedlist>
  	<para>Integrating data from a Enterprise Information System (EIS) into Teiid, is separated into two parts.</para>
  	<listitem>
      <para>A Translator, which is required.</para>
    </listitem>
    <listitem>
      <para>An optional Resource Adapter, which will typically be a JCA Resource Adapter (also called a JEE Connector) </para>
    </listitem>
  </orderedlist>  
  
  <para>A Translator is used to:</para>
  <orderedlist>
    <listitem>
      <para>Translate a Teiid-specific command into a native command,</para>
    </listitem>
    <listitem>
      <para>Execute the command,</para>
    </listitem>
    <listitem>
      <para>Return batches of results translated to expected Teiid types.</para>
    </listitem>
  </orderedlist>
  
  <para>A Resource Adapter is used to:</para>
  <itemizedlist>
    <listitem>
      <para>Handles all communications with individual enterprise information system (EIS), which can include databases, data feeds, flat files, etc.</para>
    </listitem>
    <listitem>
      <para>Can be a JCA Connector or any other custom connection provider. 
      The reason Teiid recommends and uses JCA is this specification defines how one can write, package, and configure access to EIS system in consistent manner.
      There are also various commercial/open source software vendors already providing JCA Connectors to access a variety of back-end systems.</para>
      <para>
      Refer to <ulink url="http://java.sun.com/j2ee/connector/"/>.</para>
    </listitem>
    <listitem>
      <para>Abstracts Translators from many common concerns, such as connection information, resource pooling, or authentication.</para>
    </listitem>    
  </itemizedlist>
      
  <para>Given a combination of a Translator + Resource Adapter, one can connect any EIS system to Teiid for their data integration needs.</para>
  </section>
  
  <section>
    <title>Do You Need a New Translator?</title>
    <para>Teiid provides several translators for common enterprise information system types. If
      you can use one of these enterprise information systems, you do not need to develop a custom one.
    </para>
    <para>Teiid offers the following translators:</para>

      <variablelist>
         <varlistentry>
            <term>JDBC Translator</term>
            <listitem>
               <para>
               Works with many relational databases. The JDBC translator is validated 
               against the following database systems: Oracle, Microsoft SQL Server, 
               IBM DB2, MySQL, Postgres, Derby, Sybase, H2, and HSQL. In addition, the 
               JDBC Translator can often be used with other 3rd-party drivers and provides 
               a wide range of extensibility options to specialize behavior against those 
               drivers.
               </para>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>File Translator</term>
            <listitem>
               <para>
               Provides a procedural way to access the file system to handle text files.
               </para>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>WS Translator</term>
            <listitem>
               <para>
               Provides procedural access to XML content using Web Services.
               </para>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>LDAP Translator</term>
            <listitem>
               <para>
               Accesses to LDAP directory services.
               </para>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>Salesforce Translator</term>
            <listitem>
               <para>
               Works with Salesforce interfaces.
               </para>
            </listitem>
         </varlistentry>
      </variablelist>
      
    <section>
    <title>Custom Translators</title>

     <para>
      Below are the high-level steps for creating custom Translators.  This guide covers 
      how to do each of these steps in detail. It also provides additional information for
      advanced topics, such as streaming large objects. 
    </para>

    <para>
    For sample Translator code, refer to the Teiid source code at 
    <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/"/>.
    </para>
    
    <orderedlist>
      <listitem>
        <para>Create a new or reuse an existing Resource Adapater for the EIS system, to be used with this Translator.</para>
        <para>Refer to <xref linkend="custom_ra_intro"/>.</para>
      </listitem>
      <listitem>
        <para>Implement the required classes defined by the Translator API.</para>
        <itemizedlist>
          <listitem>
            <para>Create an ExecutionFactory – Extend the <code>org.teiid.translator.ExecutionFactory</code> class</para>
          </listitem>
          <listitem>
            <para>Create relevant Executions (and sub-interfaces) – specifies how to execute each type of command</para>
          </listitem>
        </itemizedlist>
       <para>Refer to <xref linkend="translator_api"/>.</para>
      </listitem>
      <listitem>
        <para>Define the template for exposing configuration properties.
        Refer to <xref linkend="translator_package"/>.</para>
      </listitem>
      <listitem>
        <para>Deploy your Translator.
       Refer to <xref linkend="translator_deploy"/>.</para>
      </listitem>
       <listitem>
         <para>Deploy a Virtual Database (VDB) that uses your Translator.</para>
       </listitem>
      <listitem>
        <para>Execute queries via Teiid.</para>
      </listitem>
    </orderedlist>


    </section>
  </section>
  <section>
    <title>Do You Need a New Resource Adapter?</title>
    <para>As mentioned above, for every Translator that needs to gather data from external source systems, it requires a resource adapter.
    </para>
    
    <itemizedlist>
    <para>The following resource adapters are available to Teiid.</para>
      <listitem>
        <para><emphasis>DataSource:</emphasis> This is provided by the JBoss AS container. This is used by the JDBC Translator.</para>
      </listitem>
      <listitem>
        <para><emphasis>File:</emphasis> Provides a JEE JCA based Connector to access defined directory on the file system.  This is used by the File Translator</para>
      </listitem>
      <listitem>
        <para><emphasis>WS:</emphasis> Provides JEE JCA Connector to invoke Web Services using JBoss Web services stack. This is used by the WS Translator</para>
      </listitem>
      <listitem>
        <para>
          <emphasis>LDAP:</emphasis> Provides JEE JCA connector to access LDAP; Used by the LDAP Translator.
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis>Salesforce:</emphasis> Provides JEE JCA connector to access Salesforce by invoking their Web Service interface. Used by the SalesForce Translator.
        </para>
      </listitem>
    </itemizedlist>
    
    <section id="custom_ra_intro">
    <title>Custom Resource Adapters</title>
    <orderedlist numeration="arabic">
    	<para>High-level Resource Adapter development procedure:</para>
        <listitem>
            <para>Understand the JEE Connector specification to have basic idea about what JCA connectors are how they are developed and packaged.</para>
            <para>Refer to <ulink url="http://java.sun.com/j2ee/connector/"/>.</para>
        </listitem>
      <listitem>
        <para>Gather all necessary information about your Enterprise Information System (EIS). You will need
          to know:</para>
        <itemizedlist>
          <listitem>
            <para>API for accessing the system</para>
          </listitem>
          <listitem>
            <para>Configuration and connection information for the system</para>
          </listitem>
          <listitem>
            <para>Expectation for incoming queries/metadata</para>
          </listitem>
          <listitem>
            <para>The processing constructs, or capabilities, supported by information system.</para>
          </listitem>
          <listitem>
            <para>Required properties for the connection, such as URL, user name, etc.</para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>Base classes for all of the required supporting JCA SPI classes are provided by the Teiid API. The JCA CCI support is not provided from Teiid, since Teiid uses the Translator API as it's common client interface.  You will want to extend:</para>
        <itemizedlist>
          <listitem>
            <para>BasicConnectionFactory – Defines the Connection Factory</para>
          </listitem>
          <listitem>
            <para>BasicConnection – represents a connection to the source.</para>
          </listitem>
          <listitem>
            <para>BasicResourceAdapter – Specifies the resource adapter class</para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>Package your resource adapter.  Refer to <xref linkend="ra_package"/>.</para>
      </listitem>      
      <listitem>
        <para>Deploy your resource adapter.  Refer to <xref linkend="ra_package"/>.</para>
      </listitem>
    </orderedlist>
    <para>
      This guide covers how to do each of these steps in detail. It also provides additional information for
      advanced topics, such as transactions. For sample
      resource adapter code refer to the Teiid Source code at <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/"/>.
    </para>
  </section>    
  </section>
  
  <section>
  	<title>Other Teiid Development</title>
  	<para>Teiid is highly extensible in other ways:</para>
  	<itemizedlist>
  		<listitem>
  			<para>You may add User Defined Functions.  Refer to <xref linkend="udfs"/>.</para>
  		</listitem>
  		<listitem>
  			<para>You may adapt logging to your needs, which is especially useful for custom audit or command logging.  Refer to <xref linkend="logging"/>.</para>
  		</listitem>
  		<listitem>
  			<para>You may change the subsystem for custom authentication and authorization.  Refer to <xref linkend="custom_login_modules"/>.</para>
  		</listitem>
  	</itemizedlist>
  </section>
  
</chapter>