Connecting to Teiid Embedded

Teiid Embedded can deployed in different ways depending upon your environment.  The Embedded kit provides flexibility for the user to choose the right deployment mechanism.  Explore the Teiid installtion for explanation of the directory structure.

 

There are currently two deployment options available for Teiid Embedded mode.

    1. "File Path" Profile
    2. "Class Path" Profile

 

Java client applications can use  either "org.teiid.jdbc.TeiidDriver" as the JDBC Driver class, or use "org.teiid.jdbc.TeiidDataSource" as data source class with both profiles. It is recommended that you use "Data Source" class, as it is XA capable data source for participating the local or global XA transactions. Also, if you are embedding under any application servers such as JBoss AS, a data source is the preferred way.

 

If you are using Teiid versions prior to 6.2 version, use "com.metamatrix.jdbc.EmbeddedDriver" 
or "com.metamatrix.jdbc.EmbeddedDataSource".

 

 

"File Path" Profile

This deployment is driven by path to the configuration file "deploy.properties", which is located in the root directory of the Teiid runtime install directory. This file defines all the configuration and resources needed by Teiid runtime  relative to the location of this file. All the configurable properties inside this file have comment describing what their intended purpose is, please take look at the contents of this file and modify accordingly to suit deployment environment. For most users it is already configured for optimal operation that they do not need to modify any properties.

 

This profile is most recommended because of the protection it provides in defining the third party jars in a separate classpath other than boot classpath. The only requirement this imposes is that the client application that is deploying knows the location of the Teiid runtime install directory.

 

Teiid comes with the "teiid-{version}-client.jar" file in the "<teiid-install>/client" directory. It contains the Java library files necessary to make JDBC connections. Teiid provides multiple ways to create JDBC connections:

 

  1. TeiidDriver - To make the JDBC connections using DriverManager class.
  2. TeiidDatasource - Make JDBC connections using DataSource class. You can use this to create JDBC XA connections.

 

Driver Based Connection

 

Add the above jar file in your application's class path and use "org.teiid.jdbc.TeiidDriver" as the driver class.  Use the following URL format for JDBC connections:

 

jdbc:teiid:<vdb-name>@</path/to/deploy.properties>;[prop-name=prop-value;]*

 

<vdb-name> - Name of the VDB you are connecting to
<path/to/deploy.properties> - defines where the Teiid runtime is installed
[prop-name=prop-value] - addtionally you can supply any number of name value pairs separated by semi-colon [;], further refining the connection. All supported URL properties are defined here.

 

Sample Code:

 

    public class Teiid {
        public Connection getConnection(String user, String password) throws Exception {
            String url = "jdbc:teiid:myVDB@mm:/teiid/deploy.properties;ApplicationName=myApp";
            Class.forName("org.teiid.jdbc.TeiidDriver");
            return DriverManager.getConnection(url, user, password);
        }
    }

 

Datasource Based Connection

 

To use a data source based connection use "org.teiid.jdbc.TeiidDataSource" as the data source class. If your JDBC connection needs to participate in an XA transaction, you must use the data source connection. This data source is XA capable.

 

Sample Code:

 

    public class Teiid {
        public Connection getConnection(String user, String password) throws Exception {
            TeiidDataSource ds = new TeiidDataSource();
            ds.setUser(user);
            ds.setPassword(password);
            ds.setEmbeddedBootStrapFile("/teiid/deploy.properties");
            ds.setPortNumber(31000);
            ds.setDatabaseName("myVDB");
            return ds.getConnection();
        }
    }

 

Please note to set the "EmbeddedBootstrapFile" property to point to the deployment configuration file as "/path/to/deploy.properties". All the Teiid DataSource supported properties are available here.

 

For deploying Teiid in "embedded" mode using "File Path" profile to JBoss AS, please follow these directions.

 

 

"Class Path" profile

This profile provides "basic" deployment structure with "ease of use". In this profile all the resources that are needed by Teiid are defined in a single classpath and Teiid runtime will find and load resources based on this specified classpath.  If you are deploying Teiid in a stand-alone Java application this can be "boot" classpath that is defined on process command line using "-cp" or "-classpath" variables or you can even define a custom classpath and load resources using a custom classloader of that classpath.

 

If you are using this profile, *you* are responsible for defining this classpath that includes all the files under

 

<teiid-install>
     /client
     /deploy
     /lib/patches
     /lib
     /extensions

 

The "deploy" directory must be in the class path, not its contents. One major issue with this profile is potential for conflict with 3rd party jar files that are already defined in the environment these files are being deployed in.  Make sure that there are no conflicts among jars in used by Teiid and your application. You also need to make your VDB available in the classpath, a recommended practice is to place the VDB file in the "deploy" directory.

 

Driver Based Connection

 

Use the following URL format for JDBC connections:

 

jdbc:teiid:<vdb-name>;[prop-name=prop-value;]*

 

<vdb-name> - Name of the VDB you are connecting to
[prop-name=prop-value] - addtionally you can supply any number of name value pairs separated by semi-colon [;], further refining the connection. All supported URL properties are defined here.

 

Sample Code:

 

    public class Teiid {
        public Connection getConnection(String user, String password) throws Exception {
            String url = "jdbc:teiid:myVDB;ApplicationName=myApp";
            Class.forName("org.teiid.jdbc.TeiidDriver");
            return DriverManager.getConnection(url, user, password);
        }
    }

 

When using this profile a directory called "teiid-workspace" directory is created in the "user.dir" system property, which will be used to hold any temporary files and log files related to the execution of Teiid.

 

Datasource Based Connection

 

To use a data source based connection use "org.teiid.jdbc.TeiidDataSource" as the data source class. If your JDBC connection needs to participate in an XA transaction, you must use the data source connection. This data source is XA capable.

 

Sample Code:

 

    public class Teiid {
        public Connection getConnection(String user, String password) throws Exception {
            TeiidDataSource ds = new TeiidDataSource();
            ds.setUser(user);
            ds.setPassword(password);
            ds.setPortNumber(31000);
            ds.setDatabaseName("myVDB");
            return ds.getConnection();
        }
    }

 

All the Teiid DataSource supported properties are available here.  Please note that setting the "EmbeddedBootstrapFile" property is NOT needed in this profile.