Red Hat Training

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

Chapter 4. Translator Development

4.1. Environment Set-Up

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 Red Hat 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.12.0.Final. You can find Teiid artifacts in the JBoss maven repository .
The first way to create a translator project is by using JBoss Developer Studio:

Procedure 4.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. Uncheck Show the last version of Archetype only and enter "teiid" in the filter to see the Teiid archetypes.
  9. Select the translator-archetype 8.12.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.
You can 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.

Procedure 4.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.12.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 - this is the group ID for the archetype to use to generate
    • -DarchetypeArtifactId - this is the artifact ID for the archetype to use to generate.
    • -DarchetypeVersion - this is the version for the archetype to use to generate.
    • -DgroupId - this is a (user defined) group ID for the new translator project pom.xml.
    • -DartifactId - this is a (user defined) artifact ID for the new translator project pom.xml.
    • -Dpackage - this is a (user defined) the package structure where the java and resource files will be created.
    • -Dversion - this is a (user defined) the version that the new connector project pom.xml will be.
    • -Dtranslator-name - this is a (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.12.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.12.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.12.0.Final
translator-name: MyType
 Y: :
    Type Y (for Yes) and press 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 package
    It should build successfully. If so, you are now ready to start adding your custom code.