Red Hat Training

A Red Hat training course is available for Red Hat JBoss Data Virtualization

Chapter 5. Translator Development

5.1. Developing Custom Translators

To create a new custom translator:
  1. Create a new (or reuse an existing) resource adapter for the datasource, to be used with this translator.
  2. Decide whether to use the Teiid archetype template to create your initial custom translator project and classes or manually create your environment.
  3. Create an ExecutionFactory by:
    • extending the org.teiid.translator.ExecutionFactory class or
    • extending the org.teiid.translator.jdbc.JDBCExecutionFactory class .
  4. Package the translator.
  5. Deploy your translator.
  6. Deploy a Virtual Database (VDB) that uses your translator.
  7. Execute queries via the Teiid engine.
For sample translator code, refer to the teiid/connectors directory of the JBoss Data Virtualization VERSION Source Code ZIP file which can be downloaded from the Red Hat Customer Portal at https://access.redhat.com.
To set up the environment for developing a custom translator, you can either manually configure the build environment, structure and framework classes and resources or use the Teiid Translator Archetype template to generate the initial project.
To create the build environment in Red Hat JBoss Developer Studio without any Maven integration, create a Java project and add dependencies to "teiid-common-core", "teiid-api" and JEE "connector-api" jars. However, if you wish to use Maven, add these dependencies: 
<dependencies>
    <dependency>
        <groupId>org.jboss.teiid</groupId>
        <artifactId>teiid-api</artifactId>
        <version>${teiid-version}</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.jboss.teiid</groupId>
        <artifactId>teiid-common-core</artifactId>
        <version>${teiid-version}</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>javax.resource</groupId>
        <artifactId>connector-api</artifactId>
        <version>${version.connector.api}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
In this case, the ${teiid-version} property should be set to the expected version, such as 8.9.0.Final. You can find Teiid artifacts in the JBoss maven repository .
One way to start developing a custom translator is to create a project using the Teiid archetype template. When the project is created from the template, it will contain the essential classes (in other words, the ExecutionFactory) and resources for you to begin adding your custom logic. Additionally, the maven dependencies are defined in the pom.xml file so that you can begin compiling the classes.
The first way to create a translator project is by using JBoss Developer Studio:

Procedure 5.1. Create a Project in JBDS

  1. Open the Java perspective
  2. From the menu select File - New - Other.
  3. In the tree, expand Maven and select Maven Project.
  4. Click Next.
  5. On the "Select project name and Location" window, you can accept the defaults, so click Next
  6. On the "Select an Archetype" window, click the Configure button
  7. Add the remote catalog found at https://repository.jboss.org/nexus/content/repositories/releases/ then click OK to return.
  8. Enter "teiid" in the filter to see the Teiid archetypes.
  9. Select the translator-archetype 8.7.x and then click Next.
  10. Enter all the information (such as Group ID and, Artifact ID) needed to generate the project.
  11. Click Finish.
The other method involves using the command line.

Procedure 5.2. Create a Project Using the Command Line

  1. Issue the following template command: mvn archetype:generate \ -DarchetypeGroupId=org.jboss.teiid.arche-types \ -DarchetypeArtifactId=translator-archetype \ -DarchetypeVersion=8.7.0 \ -DgroupId=${groupId} \ -DartifactId=translator-${translator-name} \ -Dpackage=org.teiid.translator.${translator-name} \ -Dversion=${version} \ -Dtranslator-name=${translator-name} \ -Dteiid-version=${teiid-version}
    This is what the instructions mean:
    • -DarchetypeGroupId - is the group ID for the archetype to use to generate
    • -DarchetypeArtifactId - is the artifact ID for the archetype to use to generate
    • -DarchetypeVersion - is the version for the archetype to use to generate
    • -DgroupId - (user defined) group ID for the new translator project pom.xml
    • -DartifactId - (user defined) artifact ID for the new translator project pom.xml
    • -Dpackage - (user defined) the package structure where the java and resource files will be created
    • -Dversion - (user defined) the version that the new connector project pom.xml will be
    • -Dtranslator-name - (user defined) the name (type) of the new translator project, used to create the java class names
    • -Dteiid-version - the Teiid version upon which the connector will depend.
    Here is a sample command: mvn archetype:generate \ -DarchetypeGroupId=org.jboss.teiid.arche-types \ -DarchetypeArtifactId=translator-archetype \ -DarchetypeVersion=8.7.0 \ -DgroupId=org.jboss.teiid.connector \ -DartifactId=translator-myType \ -Dpackage=org.teiid.translator.myType \ -Dversion=0.0.1-SNAPSHOT \ -Dtranslator-name=MyType \ -Dteiid-version=8.7.0.Final
  2. After you execute it, you will be asked to confirm the properties: 
    Confirm properties configuration:
groupId: org.jboss.teiid.connector
artifactId: translator-myType
version: 0.0.1-SNAPSHOT
package: org.teiid.translator.myType
teiid-version: 8.7.0.Final
translator-name: MyType
 Y: :
    Type Y (for Yes) and click enter.
  3. Upon creation, a directory based on the artifactId will be created, that will contain the project. Navigate to that directory.
  4. Execute a test build to confirm the project was created correctly: mvn clean install
    It should build successfully. If so, you are now ready to start adding your custom code.