Quick Start Example Using "Connector supplied Metadata"

Version 4

    WARNING this article is out of date - please refer to more recent documentation.

     

    This article is an extension of the document Quick Start Example, that shows an example how data from two or more disparate sources can be integrated using Teiid and its tools.

     

    Starting with Teiid 6.2 release, Teiid provides a simple alternate solution to collect metadata for data integration purposes without the need for Teiid Designer, thus cutting down on time spent in building a VDB using a new feature called "Connector Supplied Metadata".  The metadata needed by the Teiid data integration modules will be dynamically imported at runtime from source system directly instead of building a static design time model using  Teiid Designer.

     

    To build the "portfolio" example

    • Follow the directions described in Quick Start Example.
    • Skip chapter  "Using Teiid Designer using to build a VDB", and continue the direction below in this article to define a DEF file for defining a VDB.
    • Continue the Quick Start Example again for "deployment".

     

    This example integrates  "account" information from a "derby" database, and "stock" quote information from a comma separated file. The following XML file shows how the both data sources can be defined to form a DEF file based VDB.

     

    portfolio.def (attached below)

     

    <?xml version="1.0" encoding="UTF-8"?>
    <VDB>
        <VDBInfo>
            <Property Name="Name" Value="portfolio" />
            <Property Name="Version" Value="1" />        
            <Property Name="UseConnectorMetadata" Value="cached" />
        </VDBInfo>
              
        <Model>
            <Property Name="Name" Value="MarketData" />
            <ConnectorBindings>
                <Connector Name="Text Connector" />
            </ConnectorBindings>
        </Model>
    
        <Model>
            <Property Name="Name" Value="Accounts" />
            <Property Name="importer.useFullSchemaName" Value="false"/>
    
            <ConnectorBindings>
                <Connector Name="Derby Connector" />
            </ConnectorBindings>
        </Model>
         
        <ConnectorBindings>
            <Connector Name="Text Connector" ComponentType="Text File Connector">
                <Properties>
                    <Property Name="Immutable">true</Property>
                    <Property Name="DescriptorFile">${teiid.home}/examples/portfolio/marketdata-def.txt</Property>
                </Properties>
            </Connector>
            <Connector Name="Derby Connector" ComponentType="Apache Derby Network Connector">
                <Properties>
                    <Property Name="URL">jdbc:derby://localhost:1527/teiid/accounts</Property>
                    <Property Name="ConnectorClassPath">extensionjar:derbyclient.jar</Property>
                </Properties>
            </Connector>
        </ConnectorBindings>
    </VDB>
    

     

    The details of the XML format is defined here, however below sections explain the specifics related to this example

     

        <VDBInfo>
            <Property Name="Name" Value="portfolio" />
            <Property Name="Version" Value="1" />       
            <Property Name="UseConnectorMetadata" Value="cached" />
        </VDBInfo>
    

     

    This section defines the "name" of your VDB and its "version". UseConnectorMetadata is the flag that instructs Teiid runtime to use the dynamic metadata capabilities for working with your VDB.

     

        <Model>
            <Property Name="Name" Value="Accounts" />
            <Property Name="importer.useFullSchemaName" Value="false"/>
    
            <ConnectorBindings>
                <Connector Name="Derby Connector" />
            </ConnectorBindings>
        </Model>

     

    A <Model> represents a schema of a  source that is defined. In above example the model "Accounts" represents the schema imported from the "Derby Connector". A model name also acts scope qualifier for the imported tables. The tables in "derby" database [customer, account, product, holdings] can now be qualified as

     

    Accounts.customer

    Accounts.account

    Accounts.product

    Accounts.holdings

     

    in your Teiid application. Using this scoping  any conflicts in the table names can be avoided between multiple sources. You can have as many models as you like in single DEF file each one representing a distinct physical source.

     

    importer.*: All the properties under <model> that start with "importer." define the connector metadata importer settings that need to be honered while importing the metadata. Using these properties you can restrict/expand the kind of information you want to download as part of metadata.

     

    ConnectorBindings: This section defines a reference to the "physical sources" that make up this model. Like "derby" or "text file" etc. The actual Connector Binding is defined in the section below.

     

        <ConnectorBindings>
            <Connector Name="Derby Connector" ComponentType="Apache Derby Network Connector">
                <Properties>
                    <Property Name="URL">jdbc:derby://localhost:1527/teiid/accounts</Property>
                    <Property Name="ConnectorClassPath">extensionjar:derbyclient.jar</Property>
                </Properties>
            </Connector>
        </ConnectorBindings>

     

    This section of the XML actually defines the Connectors and their connection properties. This is similar to defining data sources in a application server such as JBoss AS. Depending upon the "type" of the source the required properties for a Connector will change. This example shows a Derby Connector requires a connection URL and its JDBC client jar file name in its settings to sucessfully make a Connector connection in Teiid runtime.

     

    ComponentType: This defines the "type" of the source. Based on the type, capabilities of individual source can be inferred at runtime.   The "Connector supplied metadata" feature currently only supports JDBC and Text Connectors.

     

    For complete list of supported types along with sample XML fragments that show the required properties see "Connectors" for DEF File.

     

    It is easy to switch the source from Derby to Oracle,DB2 etc using one of these other connector types along with their connection properties.

     

    Once you are done defining all your models and connector bindings save the xml file with .def extension and copy into Teiid runtime "deploy" directory to deploy the VDB. To see how to access your VDB using your application see directions in either Quick Start Example, or on WIKI.