JBoss.orgCommunity Documentation

Chapter 3. Translator Development

3.1. Extending the ExecutionFactory Class
3.1.1. ConnectionFactory
3.1.2. Connection
3.1.3. Configuration Properties
3.1.4. Initializing the Translator
3.1.5. TranslatorCapabilities
3.1.6. Execution (and sub-interfaces)
3.1.7. Metadata
3.1.8. Logging
3.1.9. Exceptions
3.1.10. Default Name
3.2. Connections to Source
3.2.1. Obtaining connections
3.2.2. Releasing Connections
3.3. Executing Commands
3.3.1. Execution Modes
3.3.2. ResultSetExecution
3.3.3. Update Execution
3.3.4. Procedure Execution
3.3.5. Asynchronous Executions
3.3.6. Bulk Execution
3.3.7. Command Completion
3.3.8. Command Cancellation
3.4. Command Language
3.4.1. Language
3.4.2. Language Utilities
3.4.3. Runtime Metadata
3.4.4. Language Visitors
3.4.5. Translator Capabilities
3.5. Large Objects
3.5.1. Data Types
3.5.2. Why Use Large Object Support?
3.5.3. Handling Large Objects
3.5.4. Inserting or Updating Large Objects
3.6. Packaging
3.7. Deployment

A component called the Connector Manager is controlling access to your translator. This chapter reviews the basics of how the Connector Manager interacts with your translator while leaving reference details and advanced topics to be covered in later chapters.

A custom translator must extend org.teiid.translator.ExecutionFactory to connect and query an enterprise data source. This extended class must provide a no-arg constructor that can be constructed using Java reflection libraries. This Execution Factory need define/override following elements.

Every software program requires some external configuration, that defines ways user can alter the behavior of a program. If this translator needs configurable properties define a variable for every property as an attribute in the extended "ExecutionFactory" class. Then define a "get" and "set" methods for each of them. Also, annotate each "get" method with @TranslatorProperty annotation and provide the metadata about the property. For example, if you need a property called "foo",

private String foo = "balh";

@TranslatorProperty(display="Foo property", description="description about Foo") 
public String getFoo() {
    return foo;

public void setFoo(String value) {
    return this.foo = value;

by providing the annotation on these properties, the Teiid tooling will automatically interrogate and provide graphical way to configure your Translator. Only java primitive (int), primitive object wrapper (java.lang.Integer), or Enum types are supported as Translator properties. The default value will be derived from calling the getter, if available, on a newly constructed instance. All properties should have a default value. If there is no applicable default, then the property should be marked in the annotation as required. Initialization will fail if a required property value is not provided.

The @TranslatorProperty defines the following metadata that you can define about your property

Teiid sends commands to your Translator in object form. These classes are all defined in the "org.teiid.language" package. These objects can be combined to represent any possible command that Teiid may send to the Translator. However, it is possible to notify Teiid that your Translator can only accept certain kinds of constructs via the capabilities defined on the "ExecutionFactory" class. See the section on using Translator Capabilities for more information.

The language objects all extend from the LanguageObject interface. Language objects should be thought of as a tree where each node is a language object that has zero or more child language objects of types that are dependent on the current node.

All commands sent to your Translator are in the form of these language trees, where the root of the tree is a subclass of Command. Command has several sub-interfaces, namely:

  • QueryExpression

  • Insert

  • Update

  • Delete

  • BatchedUpdates

  • Call

Important components of these commands are expressions, criteria, and joins, which are examined in closer detail below. Also see the Teiid JavaDocs for more on the classes and interfaces described here.

This section covers utilities available when using, creating, and manipulating the language interfaces.

Teiid uses a library of metadata, known as "runtime metadata” for each virtual database that is deployed in Teiid. The runtime metadata is a subset of metadata as defined by models in the Teiid models that compose the virtual database.  While builing your VDB in the Designer, you can define what called "Extension Model", that defines any number of arbitary properties on a model and its objects. At runtime, using this runtime metadata interface, you get access to those set properties defined during the design time, to define/hint any execution behavior.

Translator gets access to the RuntimeMetadata interface at the time of Excecution creation. Translators can access runtime metadata by using the interfaces defined in org.teiid.metadata package.  This package defines API representing a Schema, Table, Columns and Procedures, and ways to navigate these objects.

The API provides a language visitor framework in the org.teiid.language.visitor package.  The framework provides utilities useful in navigating and extracting information from trees of language objects.

The visitor framework is a variant of the Visitor design pattern, which is documented in several popular design pattern references.  The visitor pattern encompasses two primary operations: traversing the nodes of a graph (also known as iteration) and performing some action at each node of the graph.  In this case, the nodes are language interface objects and the graph is really a tree rooted at some node.  The provided framework allows for customization of both aspects of visiting.

The base AbstractLanguageVisitor class defines the visit methods for all leaf language interfaces that can exist in the tree.  The LanguageObject interface defines an acceptVisitor() method – this method will call back on the visit method of the visitor to complete the contract.  A base class with empty visit methods is provided as AbstractLanguageVisitor.  The AbstractLanguageVisitor is just a visitor shell – it performs no actions when visiting nodes and does not provide any iteration.

The HierarchyVisitor provides the basic code for walking a language object tree.  The HierarchyVisitor performs no action as it walks the tree – it just encapsulates the knowledge of how to walk it.  If your translator wants to provide a custom iteration that walks the objects in a special order (to exclude nodes, include nodes multiple times, conditionally include nodes, etc) then you must either extend HierarchyVisitor or build your own iteration visitor.  In general, that is not necessary.

The DelegatingHierarchyVisitor is a special subclass of the HierarchyVisitor that provides the ability to perform a different visitor’s processing before and after iteration.  This allows users of this class to implement either pre- or post-order processing based on the HierarchyVisitor.  Two helper methods are provided on DelegatingHierarchyVisitor to aid in executing pre- and post-order visitors.  

The ExecutionFactory class defines all the methods that describe the capabilities of a Translator. These are used by the Connector Manager to determine what kinds of commands the translator is capable of executing. A base ExecutionFactory class implements all the basic capabilities, which says your translator does not support any cpabilities. Your extended ExecutionFactory class must override the the necessary methods to specify which capabilities your translator supports.  

The following table lists the capabilities that can be specified in the ExecutionFactory class.

Table 3.2. Available Capabilities





Translator can support SELECT DISTINCT in queries.


Translator can support SELECT of more than just column references.


Translator can support Tables in the FROM clause that have an alias.


Translator can support inner and cross joins


AliasedGroups and at least on of the join type supports.

Translator can support a self join between two aliased versions of the same Table.


Translator can support LEFT and RIGHT OUTER JOIN.


Translator can support FULL OUTER JOIN.



Translator can support a named subquery in the FROM clause.


Not currently used - between criteria is rewriten as compound comparisions.


Translator can support comparison criteria with the operator "=”.


Translator can support comparison criteria with the operator ">” or "<".


Translator can support LIKE criteria.



Translator can support LIKE criteria with an ESCAPE character clause.



Translator can support IN predicate criteria.


Translator can support IN predicate criteria where values are supplied by a subquery.


Translator can support IS NULL predicate criteria.


Translator can support the OR logical criteria.


Translator can support the NOT logical criteria. IMPORTANT: This capability also applies to negation of predicates, such as specifying IS NOT NULL, "<=" (not ">"), ">=" (not "<"), etc.


Translator can support EXISTS predicate criteria.


Translator can support a quantified comparison criteria using the ALL quantifier.


Translator can support a quantified comparison criteria using the SOME or ANY quantifier.


Translator can support the ORDER BY clause in queries.



Translator can support the ORDER BY items that are not directly specified in the select clause.


Translator can support an explict GROUP BY clause.



Translator can support the HAVING clause.


Translator can support the AVG aggregate function.


Translator can support the COUNT aggregate function.


Translator can support the COUNT(*) aggregate function.


At least one of the aggregate functions.

Translator can support the keyword DISTINCT inside an aggregate function.  This keyword indicates that duplicate values within a group of rows will be ignored.


Translator can support the MAX aggregate function.


Translator can support the MIN aggregate function.


Translator can support the SUM aggregate function.


Translator can support the use of a subquery in a scalar context (wherever an expression is valid).


At least one of the subquery pushdown capabilities.

Translator can support a correlated subquery that refers to an element in the outer query.


Not currently used - simple case is rewriten as searched case.


Translator can support "searched” CASE expressions anywhere that expressions are accepted.


Translator support UNION and UNION ALL


Translator supports INTERSECT


Translator supports Except


Unions, Intersect, or Except

Translator supports set queries with an ORDER BY


Translator can support the limit portion of the limit clause


Translator can support the offset portion of the limit clause



Not currently used - non-element expressions in the group by create an inline view.


Translator supports INSERT statements with values specified by an QueryExpression.


Translator supports a batch of INSERT, UPDATE and DELETE commands to be executed together.


Translator supports updates with multiple value sets

Note that any pushdown subquery must itself be compliant with the Translator capabilities.

The method ExecutionFactory.getSupportedFunctions() can be used to specify which scalar functions the Translator supports.  The set of possible functions is based on the set of functions supported by Teiid.  This set can be found in the Reference documentation.  If the Translator states that it supports a function, it must support all type combinations and overloaded forms of that function.

There are also five standard operators that can also be specified in the supported function list: +, -, *, /, and ||.

The constants interface SourceSystemFunctions contains the string names of all possible built-in pushdown functions. Note that not all system functions appear in this list. This is because some system functions will always be evaluted in Teiid, are simple aliases to other functions, or are rewriten to a more standard expression.

This section examines how to use facilities provided by the Teiid API to use large objects such as blobs, clobs, and xml in your Translator.

Once the "ExecutionFactory" class is implemented, package it in a JAR file. The only additional requirement is provide a file called "jboss-beans.xml" in the "META-INF" directory of the JAR file, with following contents.

<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
   <bean name="translator-${name}-template" class="org.teiid.templates.TranslatorDeploymentTemplate">
      <property name="info"><inject bean="translator-${name}"/></property>
      <property name="managedObjectFactory"><inject bean="ManagedObjectFactory"/></property>
   <bean name="translator-${name}" class="org.teiid.templates.TranslatorTemplateInfo">
      <constructor factoryMethod="createTemplateInfo">
         <factory bean="TranslatorDeploymentTemplateInfoFactory"/>
         <parameter class="java.lang.Class">org.teiid.templates.TranslatorTemplateInfo</parameter>
         <parameter class="java.lang.Class">${execution-factory-class}</parameter>
         <parameter class="java.lang.String">translator-${name}</parameter>
         <parameter class="java.lang.String">${name}</parameter>         

replace ${name} with name of your translator, and replace ${execution-factory-class} with your overridden ExecutionFactory class name. This will register the Translator for use with tooling and Admin API.

Copy the JAR file that defines the Translator into "deploy" directory of the JBoss AS's chosen profile, and the Translator will be deployed automatically. There is no restriction that, JBoss AS need to be restarted. However, if your Translator has external dependencies to other JAR libraries, they need to be placed inside the "lib" directory of the JBoss AS's profile. This will require a restart of the JBoss Server. Another option to avoid the restart is to bundle all the required JAR files into the same JAR file as the Translator. It is user's responsibility to make sure they are not running into any conflicts with their dependent libraries with those already exist in the JBoss environment.