JBoss.orgCommunity Documentation
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.
Defines the "ConnectionFactory" interface that is expected from resource adapter. This defined as part of class definition using generics while extending the "ExecutionFactory" class
Defines the "Connection" interface that is expected from resource adapter. This defined as part of class definition using generics while extending the "ExecutionFactory" class
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", by providing the annotation on these properties, the Teiid tooling will automatically interrogate and provide graphical way to configure your Translator.
private String foo = "blah";
@TranslatorProperty(display="Foo property", description="description about Foo")
public String getFoo()
{
return foo;
}
public void setFoo(String value)
{
return this.foo = value;
}
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
display: Display name of the property
description: Description about the property
required: The property is a required property
advanced: This is advanced property; A default should be provided. A property can not be "advanced" and "required" at same time.
masked: The tools need to mask the property; Do not show in plain text; used for passwords
Override and implement the start method (be sure to call
"super.start()") if your translator needs to do any initializing before it is used by the Teiid engine. This method
will be called by Teiid, once after all the configuration properties set above are injected into the class.
These are various methods that typically begin with method signature "supports" on the "ExecutionFactory" class. These methods need to be overridden to describe the execution capabilities of the Translator. Refer to Section 3.4.5, “Translator Capabilities” for more on these methods.
Based on types of executions you are supporting, the following methods need to be overridden and need to provide implementations for these methods by extending respective interfaces.
createResultSetExecution - Define if you are doing read based operation that is
returning a rows of results.
createUpdateExecution - Define if you are doing write based operations.
createProcedureExecution - Define if you are doing procedure based operations.
You can choose to implement all the execution modes or just what you need. See more details on this below.
Override and implement the method getMetadata(), if you want to expose the
metadata about the source for use in Dynamic VDBs. This defines the tables, column names, procedures, parameters, etc. for use in the query engine.
This method is not yet used by Designer tooling.
Teiid provides org.teiid.logging.LogManager class for logging purposes.
Create a logging context and use the LogManager to log your messages. These will be automatically
sent to the main Teiid logs. You can edit the "jboss-log4j.xml" inside "conf" directory of the JBoss AS's profile
to add the custom context. Teiid uses Log4J as its underlying logging system.
If you need to bubble up any exception use org.teiid.translator.TranslatorException
class.
Finally, you can define a default instance of your Translator by defining the
annotation @Translator on the "ExecutionFactory". When you define this, and after deployment
a default instance of this
Translator is available any VDB that would like to use by just mentioning its name in its "vdb.xml" configuration file.
VDB can also override the default properties and define another instance of this Translator too. The name you give here is the short
name used every where else in the Teiid configuration to refer to this translator.
The extended "ExecutionFactory" must implement the getConnection() method to
allow the Connector Manager to obtain a connection.
Once the Connector Manager has obtained a connection, it will use that connection only for the lifetime of the request. When the request has completed, the closeConnection() method called on the "ExecutionFactory". You must also override this method to properly close the connection.
In cases (such as when a connection is stateful and expensive to create), connections should be pooled. If the resource adapter is JEE JCA connector based, then pooling is automatically provided by the JBoss AS container. If your resource adapter does not implement the JEE JCA, then connection pooling semantics are left to the user to define on their own.
The Teiid query engine uses the "ExecutionFactory" class to obtain the "Execution" interface for the command it is executing. The actual queries themselves are sent to translators in the form of a set of objects, which are further described in Command Language. Refer to Section 3.4, “Command Language”. Translators are allowed to support any subset of the available execution modes.
Table 3.1. Types of Execution Modes
| Execution Interface | Command interface(s) | Description |
|---|---|---|
ResultSetExecution
|
QueryExpression
| A query corresponding to a SQL SELECT or set query statement. |
UpdateExecution
|
Insert, Update, Delete, BatchedUpdates
| An insert, update, or delete, corresponding to a SQL INSERT, UPDATE, or DELETE command |
ProcedureExecution
|
Call
| A procedure execution that may return a result set and/or output values. |
All of the execution interfaces extend the base Execution
interface that defines how executions are
cancelled and closed. ProcedureExecution also extends ResultSetExecution, since procedures may also return resultsets.
Typically most commands executed against translators are QueryExpression. While the command is being executed, the translator provides results via the ResultSetExecution's "next" method. The "next" method should return null to indicate the end of results. Note: the expected batch size can be obtained from the ExecutionContext and used as a hint in fetching results from the EIS.
Each execution returns the update count(s) expected by the update command. If possible BatchedUpdates should be executed atomically. The ExecutionContext can be used to determine if the execution is already under a transaction.
Procedure commands correspond to the execution of a stored procedure or some other functional construct. A procedure takes zero or more input values and can return a result set and zero or more output values. Examples of procedure execution would be a stored procedure in a relational database or a call to a web service.
If a result set is expected when a procedure is executed, all rows from it will be retrieved via the ResultSetExecution interface first. Then, if any output values are expected, they will be retrieved via the getOutputParameterValues() method.
In some scenarios, a translator needs to execute asynchronously and allow the executing thread to perform other work. To allow this, you should Throw a DataNotAvailableExecption during a retrival method, rather than explicitly waiting or sleeping for the results. The DataNotAvailableException may take a delay parameter in its constructor to indicate how long the system should wait befor polling for results. Any non-negative value is allowed.
Since the exection and the associated connection are not closed until the work has completed, care should be taken if using asynchronous executions that hold a lot of state.
Non batched Insert, Update, Delete
commands may have Literal values marked as multiValued if the
capabilities shows support for BulkUpdate. Commands with
multiValued Literals represent multiple executions of the same
command with different values. As with BatchedUpdates, bulk operations should be executed atomically if possible.
All normal command executions end with the calling of close() on the Execution object. Your
implementation of this method should do the appropriate clean-up work for all state created in the Execution object.
Commands submitted to Teiid may be aborted in several scenarios:
Client cancellation via the JDBC API (or other client APIs)
Administrative cancellation
Clean-up during session termination
Clean-up if a query fails during processing
Unlike the other execution methods, which are handled in a single-threaded manner, calls to cancel happen asynchronously with respect to the execution thread.
Your connector implementation may choose to do nothing in response to this cancellation message. In this instance, Teiid will call close() on the execution object after current processing has completed. Implementing the cancel() method allows for faster termination of queries being processed and may allow the underlying data source to terminate its operations faster as well.
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. Refer to Section 3.4.5, “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. For more on the classes and interfaces described here, refer to the Teiid JavaDocs http://docs.jboss.org/teiid/7.4/apidocs.
An expression represents a single value in context, although in some cases that value may change as the query is evaluated. For example, a literal value, such as 5 represents an integer value. An column reference such as "table.EmployeeName" represents a column in a data source and may take on many values while the command is being evaluated.
Expression
– base expression interface
ColumnReference
– represents an column in the data source
Literal
– represents a literal scalar value, but may also be multi-valued in
the case of bulk updates.
Function
– represents a scalar function with parameters that are also Expressions
Aggregate
– represents an aggregate function which holds a single expression
ScalarSubquery
– represents a subquery that returns a single value
SearchedCase, SearchedWhenClause
– represents a searched CASE expression. The searched CASE
expression evaluates the criteria in WHEN clauses till one evaluates
to TRUE, then evaluates the associated THEN clause.
A criteria is a combination of expressions and operators that evaluates to true, false, or unknown. Criteria are most commonly used in the WHERE or HAVING clauses.
Condition – the base criteria interface
Not – used to NOT another criteria
AndOr – used to combine other criteria via AND or OR
SubuqeryComparison – represents a comparison criteria with a subquery including a quantifier such as SOME or ALL
Comparison – represents a comparison criteria with =, >, <, etc.
BaseInCondition – base class for an IN criteria
In – represents an IN criteria that has a set of expressions for values
SubqueryIn – represents an IN criteria that uses a subquery to produce the value set
IsNull – represents an IS NULL criteria
Exists – represents an EXISTS criteria that determines whether a subquery will return any values
Like – represents a LIKE criteria that compares string values
The FROM clause contains a list of TableReference's.
NamedTable – represents a single Table
Join – has a left and right TableReference and information on the join between the items
DerivedTable – represents a table defined by an inline QueryExpression
A list of TableReference
are used by default, in the pushdown query
when no outer joins are used. If an outer join is used anywhere in the
join tree, there will be a tree of
Join
s with a single root. This latter form
is the ANSI perfered style. If you wish all pushdown queries containing joins to be in ANSI style have the
capability "useAnsiJoin" return true. Refer to
Section 3.4.5.3, “Command Form” for more information.
QueryExpression is the base for both SELECT queries and set queries. It may optionally take an
OrderBy (representing a SQL ORDER BY clause), a Limit (represent a SQL LIMIT clause), or a With (represents a SQL WITH clause).
Each QueryExpression can be a Select describing the expressions
(typically elements) being selected and an TableReference specifying the table
or tables being selected from, along with any join information. The
Select may optionally also supply an Condition (representing a SQL
WHERE clause), a GroupBy (representing a SQL GROUP BY clause), an
an Condition (representing a SQL HAVING clause).
A QueryExpression can also be a SetQuery that represents on of the SQL set operations (UNION,
INTERSECT, EXCEPT) on two QueryExpression. The all flag may be set to
indicate UNION ALL (currently INTERSECT and EXCEPT ALL are not allowed in Teiid)
A With clause contains named QueryExpressions held by WithItems that can be
referenced as tables in the main QueryExpression.
Each Insert will have a single NamedTable specifying the table being
inserted into. It will also has a list of ColumnReference specifying the columns
of the NamedTable that are being inserted into. It also has
InsertValueSource, which will be a list of
Expressions (ExpressionValueSource), or a QueryExpression, or an Iterator (IteratorValueSource)
Each Update will have a single NamedTable specifying the table being
updated and list of SetClause entries that specify ColumnReference
and Expression pairs for the update. The Update may optionally provide a criteria
Condition specifying which rows should be updated.
Each Delete will have a single NamedTable specifying the table being
deleted from. It may also optionally have a criteria specifying which rows should be deleted.
Each Call has zero or more Argument objects. The
Argument objects describe the input parameters, the output result
set, and the output parameters.
This section covers utilities available when using, creating, and manipulating the language interfaces.
The Translator API contains an interface TypeFacility that defines
data types and provides value translation facilities. This interface can be obtained from calling "getTypeFacility()"
method on the "ExecutionFactory" class.
The TypeFacitlity interface has methods that support data type
transformation and detection of appropriate runtime or JDBC types.
The TypeFacility.RUNTIME_TYPES and TypeFacility.RUNTIME_NAMES
interfaces defines constants for all Teiid runtime data types. All
Expression instances define a data type based on this set of types.
These constants are often needed in understanding or creating language interfaces.
In Translators that support a fuller set of capabilities (those that generally are translating to a language of comparable to SQL), there is often a need to manipulate or create language interfaces to move closer to the syntax of choice. Some utilities are provided for this purpose:
Similar to the TypeFacility, you can call "getLanguageFactory()" method on
the "ExecutionFactory"
to get a reference to the LanguageFactory instance for your
translator. This interface is a factory that can be used to create new
instances of all the concrete language interface objects.
Some helpful utilities for working with Condition objects are
provided in the LanguageUtil class. This class has methods to combine
Condition with AND or to break an Condition apart based on AND
operators. These utilities are helpful for breaking apart a criteria
into individual filters that your translator can implement.
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.
All the language objects extend AbstractMetadataRecord class
Column - returns Column metadata record
Table - returns a Table metadata record
Procedure - returns a Procedure metadata record
ProcedureParameter - returns a Procedure Parameter metadata record
Once a metadata record has been obtained, it is possible to use its metadata about that object or to find other related metadata.
The RuntimeMetadata interface is passed in for the creation of an "Execution". See "createExecution" method on the "ExecutionFactory" class. It provides the ability to look up metadata records based on their fully qualified names in the VDB.
Example 3.1. Obtaining Metadata Properties
The process of getting a Table's properties is sometimes needed for translator development. For example to get the "NameInSource" property or all extension properties:
//getting the Table metadata from an Table is straight-forward
Table table = runtimeMetadata.getTable("table-name");
String contextName = table.getNameInSource();
//The props will contain extension properties
Map<String, String> props = table.getProperties();
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 SQLStringVisitor is a special visitor that can traverse a
tree of language interfaces and output the equivalent Teiid SQL. This
visitor can be used to print language objects for debugging and
logging. The SQLStringVisitor does not use the HierarchyVisitor
described in the last section; it provides both iteration and
processing type functionality in a single custom visitor.
The CollectorVisitor is a handy utility to collect all language
objects of a certain type in a tree. Some additional helper methods
exist to do common tasks such as retrieving all elements in a tree,
retrieving all groups in a tree, and so on.
Writing your own visitor can be quite easy if you use the provided facilities. If the normal method of iterating the language tree is sufficient, then just follow these steps:
Create a subclass of AbstractLanguageVisitor. Override any visit
methods needed for your processing. For instance, if you wanted to
count the number of elements in the tree, you need only override the
visit(ColumnReference) method. Collect any state in local variables and
provide accessor methods for that state.
Decide whether to use pre-order or post-order iteration. Note that visitation order is based upon syntax ordering of SQL clauses - not processing order.
Write code to execute your visitor using the utility methods on DelegatingHierarchyVisitor:
// Get object tree
LanguageObject objectTree = &
// Create your visitor initialize as necessary
MyVisitor visitor = new MyVisitor();
// Call the visitor using pre-order visitation
DelegatingHierarchyVisitor.preOrderVisit(visitor, objectTree);
// Retrieve state collected while visiting
int count = visitor.getCount();
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 methods, which says
your translator does not support any capabilities. Your extended
ExecutionFactory class must override the the necessary methods to specify which
capabilities your translator supports. You should consult the debug log of query planning (set showplan debug) to see if desired pushdown requires additional capabilities.
Note that if your capabilities will remain unchanged for the lifetime of the translator, since the engine will cache them for reuse by all instances of that translator. Capabilities based on connection/user are not supported.
The following table lists the capabilities that can be specified in the ExecutionFactory class.
Table 3.2. Available Capabilities
|
Capability |
Requires |
Description |
|---|---|---|
|
SelectDistinct |
Translator can support SELECT DISTINCT in queries. | |
|
SelectExpression |
Translator can support SELECT of more than just column references. | |
|
AliasedTable |
Translator can support Tables in the FROM clause that have an alias. | |
|
InnerJoins |
Translator can support inner and cross joins | |
|
SelfJoins |
AliasedGroups and at least on of the join type supports. |
Translator can support a self join between two aliased versions of the same Table. |
|
OuterJoins |
Translator can support LEFT and RIGHT OUTER JOIN. | |
|
FullOuterJoins |
Translator can support FULL OUTER JOIN. | |
|
InlineViews |
AliasedTable |
Translator can support a named subquery in the FROM clause. |
|
BetweenCriteria |
Not currently used - between criteria is rewriten as compound comparisions. | |
|
CompareCriteriaEquals |
Translator can support comparison criteria with the operator "=". | |
|
CompareCriteriaOrdered |
Translator can support comparison criteria with the operator ">" or "<". | |
|
LikeCriteria |
Translator can support LIKE criteria. | |
|
LikeCriteriaEscapeCharacter |
LikeCriteria |
Translator can support LIKE criteria with an ESCAPE character clause. |
|
InCriteria |
MaxInCriteria |
Translator can support IN predicate criteria. |
|
InCriteriaSubquery |
Translator can support IN predicate criteria where values are supplied by a subquery. | |
|
IsNullCriteria |
Translator can support IS NULL predicate criteria. | |
|
OrCriteria |
Translator can support the OR logical criteria. | |
|
NotCriteria |
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. | |
|
ExistsCriteria |
Translator can support EXISTS predicate criteria. | |
|
QuantifiedCompareCriteriaAll |
Translator can support a quantified comparison criteria using the ALL quantifier. | |
|
QuantifiedCompareCriteriaSome |
Translator can support a quantified comparison criteria using the SOME or ANY quantifier. | |
|
OrderBy |
Translator can support the ORDER BY clause in queries. | |
|
OrderByUnrelated |
OrderBy |
Translator can support ORDER BY items that are not directly specified in the select clause. |
|
OrderByNullOrdering |
OrderBy |
Translator can support ORDER BY items with NULLS FIRST/LAST. |
|
GroupBy |
Translator can support an explict GROUP BY clause. | |
|
Having |
GroupBy |
Translator can support the HAVING clause. |
|
AggregatesAvg |
Translator can support the AVG aggregate function. | |
|
AggregatesCount |
Translator can support the COUNT aggregate function. | |
|
AggregatesCountStar |
Translator can support the COUNT(*) aggregate function. | |
|
AggregatesDistinct |
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. |
|
AggregatesMax |
Translator can support the MAX aggregate function. | |
|
AggregatesMin |
Translator can support the MIN aggregate function. | |
|
AggregatesSum |
Translator can support the SUM aggregate function. | |
|
AggregatesEnhancedNumeric |
Translator can support the VAR_SAMP, VAR_POP, STDDEV_SAMP, STDDEV_POP aggregate functions. | |
|
ScalarSubqueries |
Translator can support the use of a subquery in a scalar context (wherever an expression is valid). | |
|
CorrelatedSubqueries |
At least one of the subquery pushdown capabilities. |
Translator can support a correlated subquery that refers to an element in the outer query. |
|
CaseExpressions |
Not currently used - simple case is rewriten as searched case. | |
|
SearchedCaseExpressions |
Translator can support "searched" CASE expressions anywhere that expressions are accepted. | |
|
Unions |
Translator support UNION and UNION ALL | |
|
Intersect |
Translator supports INTERSECT | |
|
Except |
Translator supports Except | |
|
SetQueryOrderBy |
Unions, Intersect, or Except |
Translator supports set queries with an ORDER BY |
|
RowLimit |
Translator can support the limit portion of the limit clause | |
|
RowOffset |
Translator can support the offset portion of the limit clause | |
|
FunctionsInGroupBy |
GroupBy |
Not currently used - non-element expressions in the group by create an inline view. |
|
InsertWithQueryExpression |
Translator supports INSERT statements with values specified by an QueryExpression. | |
|
supportsBatchedUpdates |
Translator supports a batch of INSERT, UPDATE and DELETE commands to be executed together. | |
|
BulkUpdate |
Translator supports updates with multiple value sets | |
|
InsertWithIterator |
Translator supports inserts with an iterator of values. The values would typically be from an evaluated QueryExpression. | |
|
CommonTableExpressions |
Translator supports the WITH clause. |
Note that any pushdown subquery must itself be compliant with the Translator capabilities.
The method ExecutionFactory.useAnsiJoin() should return true
if the Translator prefers the use of ANSI style join structure for
join trees that contain only INNER and CROSS joins.
The method ExecutionFactory.requiresCriteria() should return
true if the Translator requires criteria for any Query, Update, or
Delete. This is a replacement for the model support property "Where
All".
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 at
http://www.jboss.org/teiid//docs.html. 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.
The method ExecutionFactory.getMaxInCriteriaSize() can be
used to specify the maximum number of values that can be passed in an
IN criteria. This is an important constraint as an IN criteria is
frequently used to pass criteria between one source and another using
a dependent join.
The method ExecutionFactory.getMaxDependentInPredicates() is
used to specify the maximum number of IN predicates (of at most MaxInCriteriaSize) that can be passed
as part of a dependent join. For example if there are 10000 values to pass as part of the dependent join
and a MaxInCriteriaSize of 1000 and a MaxDependentInPredicates setting of 5, then the
dependent join logic will form two source queries each with 5 IN predicates of 1000 values each combined by OR.
The method ExecutionFactory.getMaxFromGroups() can be used
to specify the maximum number of FROM Clause groups that can used in a
join. -1 indicates there is no limit.
The method ExecutionFactory.supportsBatchedUpdates() can be
used to indicate that the Translator supports executing the BatchedUpdates command.
The method ExecutionFactory.supportsBulkUpdate() can be used
to indicate that the Translator accepts update commands containg multi valued Literals.
Note that if the translator does not support either of these update modes, the query engine will compensate by issuing the updates individually.
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.
Teiid supports three large object runtime data types: blob, clob, and xml. A blob is a "binary large object", a clob is a "character large object", and "xml" is a "xml document". Columns modeled as a blob, clob, or xml are treated similarly by the translator framework to support memory-safe streaming.
Teiid allows a Translator to return a large object through the Teiid translator API by just returning a reference to the actual large object. Access to that LOB will be streamed as appropriate rather than retrieved all at once. This is useful for several reasons:
Reduces memory usage when returning the result set to the user.
Improves performance by passing less data in the result set.
Allows access to large objects when needed rather than assuming that users will always use the large object data.
Allows the passing of arbitrarily large data values.
However, these benefits can only truly be gained if the Translator itself does not materialize an entire large object all at once. For example, the Java JDBC API supports a streaming interface for blob and clob data.
The Translator API automatically handles large objects (Blob/Clob/SQLXML) through the creation of special purpose wrapper objects when it retrieves results.
Once the wrapped object is returned, the streaming of LOB is automatically supported. These LOB objects then can for example appear in client results, in user defined functions, or sent to other translators.
A Execution is usually closed and the underlying connection is either closed/released as soon as all rows for that execution have been retrieved. However, LOB objects may need to be read after their initial retrieval of results. When LOBs are detected the default closing behavior is prevented by setting a flag on the ExecutionContext. See ExecutionContext.keepAlive() method.
When the "keepAlive" alive flag is set, then the execution object is only closed when user's Statement is closed.
executionContext.keepExecutionAlive(true);
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. 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.
<?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>
<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>
</constructor>
</bean>
</deployment>
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.