[teiid-commits] teiid SVN: r2239 - in trunk/documentation: developer-guide/src/main/docbook/en-US and 3 other directories.
teiid-commits at lists.jboss.org
teiid-commits at lists.jboss.org
Thu Jun 17 12:09:26 EDT 2010
Author: shawkins
Date: 2010-06-17 12:09:26 -0400 (Thu, 17 Jun 2010)
New Revision: 2239
Added:
trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml
trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml
Removed:
trunk/documentation/developer-guide/src/main/docbook/en-US/content/connector-api.xml
trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml
Modified:
trunk/documentation/developer-guide/
trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml
trunk/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml
trunk/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml
trunk/documentation/developer-guide/src/main/docbook/en-US/main.xml
trunk/documentation/docbook/en-US/legal_notice.xml
trunk/documentation/reference/
Log:
TEIID-315 revisions to the developers guide
Property changes on: trunk/documentation/developer-guide
___________________________________________________________________
Name: svn:ignore
- target
.settings
.classpath
.project
+ target
.settings
.classpath
.project
Legal_Notice.html
Modified: trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml
===================================================================
--- trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-17 13:44:55 UTC (rev 2238)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -54,5 +54,4 @@
</resourceadapter>
</connector>]]></programlisting>
<para>${...} indicates a value to be supplied by the developer.</para>
- <para>The description entry can utilize a special format in {}, where extended metadata properties can be supplied. This use of the special format and all properties is optional. Property names begin with $ and are separated from the value with :. Double quotes identifies a single value. A pair of square brackets [] containing comma separated double quoted entries denotes a list value.</para>
</appendix>
\ No newline at end of file
Deleted: trunk/documentation/developer-guide/src/main/docbook/en-US/content/connector-api.xml
===================================================================
--- trunk/documentation/developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-17 13:44:55 UTC (rev 2238)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -1,1406 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
-%CustomDTD;
-]>
-<chapter id="translator_api">
- <title>Translator Development</title>
- <sect1>
- <title>Extending the ExecutionFactory Class</title>
- <para>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.</para>
- <para>
- A custom translator must extend <code>org.teiid.translator.ExecutionFactory</code>
- 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.
- </para>
-
- <sect2>
- <title>ConnectionFactory</title>
- <para>Defines the "ConnectionFactory" interface that is expected from resource adapter. This defined as part of
- class definition using generics while extending the "ExecutionFactory" class</para>
- </sect2>
-
- <sect2>
- <title>Connection</title>
- <para>Defines the "Connection" interface that is expected from resource adapter. This defined as part of
- class definition using generics while extending the "ExecutionFactory" class</para>
- </sect2>
-
- <sect2>
- <title>Configuration Properties</title>
- <para>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
- <code>@TranslatorProperty</code> annotation and provide the metadata about the property. For example, if you need a
- property called "foo",
- <programlisting><![CDATA[String foo = "balh";
-
- at TranslatorProperty(display="Foo property", description="description about Foo")
-public String getFoo() {
- return foo;
-}
-
-public void setFoo(String value) {
- return this.foo = value;
-}]]> </programlisting>
-
- 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 <emphasis>should</emphasis> 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.
- </para>
-
- <para>The <code>@TranslatorProperty</code> defines the following metadata that you can define about your property</para>
- <itemizedlist>
- <listitem>
- <para>display: Display name of the property</para>
- </listitem>
- <listitem>
- <para>description: Description about the property</para>
- </listitem>
- <listitem>
- <para>required: The property is a required property</para>
- </listitem>
- <listitem>
- <para>advanced: This is advanced property; A default should be provided. A property can not be "advanced" and "required" at same time.</para>
- </listitem>
- <listitem>
- <para>masked: The tools need to mask the property; Do not show in plain text; used for passwords</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>Initializing the Translator</title>
- <para>Override and implement the <code>start</code> 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. </para>
- </sect2>
-
- <sect2>
- <title>TranslatorCapabilities</title>
- <para>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. See <link linkend="translator_capabilities">Translator Capabilities</link> for more on these methods.</para>
- </sect2>
-
- <sect2>
- <title>Execution (and sub-interfaces)</title>
- <para>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.</para>
-
- <itemizedlist>
- <listitem>
- <para><code>createResultSetExecution</code> - Define if you are doing read based operation that is
- returning a rows of results.</para>
- </listitem>
- <listitem>
- <para><code>createUpdateExecution</code> - Define if you are doing write based operations.</para>
- </listitem>
- <listitem>
- <para><code>createProcedureExecution</code> - Define if you are doing procedure based operations.</para>
- </listitem>
- </itemizedlist>
- <para>You can choose to implement all the execution modes or just what you need. See more details on this below.</para>
- </sect2>
-
- <sect2>
- <title>Metadata</title>
- <para>Override and implement the method <code>getMetadata()</code>, 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. </para>
- </sect2>
-
- <sect2>
- <title>Logging</title>
- <para>Teiid provides <code>org.teiid.logging.LogManager</code> 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.</para>
- </sect2>
-
- <sect2>
- <title>Exceptions</title>
- <para>If you need to bubble up any exception use <code>org.teiid.translator.TranslatorException</code>
- class.</para>
- </sect2>
-
- <sect2>
- <title>Default Name</title>
- <para>Finally, you can define a default instance of your Translator by defining the
- annotation <code>@Translator</code> 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.</para>
- </sect2>
-
- </sect1>
-
-
- <sect1>
- <title>Connections to Source</title>
- <sect2>
- <title>Obtaining connections</title>
- <para>The extended "ExecutionFactory" must implement the <code>getConnection()</code> method to
- allow the Connector Manager to obtain a connection. </para>
- </sect2>
- <sect2>
- <title>Releasing Connections</title>
- <para>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.</para>
- <para>
- 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.
- </para>
- </sect2>
- </sect1>
- <sect1>
- <title>Executing Commands</title>
- <sect2>
- <title>Execution Modes</title>
- <para>
- 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 <link linkend="command_language">Command Language</link>.
- translators are allowed to support any subset of the available execution modes.
- </para>
- <table frame='all'>
- <title>Types of Execution Modes</title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*" />
- <colspec colname='c2' colwidth="1*" />
- <colspec colname='c3' colwidth="2*" />
- <thead>
- <row>
- <entry>Execution Interface</entry>
- <entry>Command interface(s)</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <code>ResultSetExecution</code>
- </entry>
- <entry>
- <code>QueryExpression</code>
- </entry>
- <entry>A query corresponding to a SQL SELECT or set query statement.</entry>
- </row>
- <row>
- <entry>
- <code>UpdateExecution</code>
- </entry>
- <entry>
- <code>Insert, Update, Delete, BatchedUpdates</code>
- </entry>
- <entry>An insert, update, or delete, corresponding to a SQL INSERT, UPDATE, or DELETE command
- </entry>
- </row>
- <row>
- <entry>
- <code>ProcedureExecution</code>
- </entry>
- <entry>
- <code>Call</code>
- </entry>
- <entry>A procedure execution that may return a result set and/or output values.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>All of the execution interfaces extend the base <code>Execution</code>
- interface that defines how executions are
- cancelled and closed. ProcedureExecution also extends ResultSetExecution, since procedures may also return resultsets.</para>
- </sect2>
- <sect2>
- <title>ResultSetExecution</title>
- <para>
- 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.
- </para>
- </sect2>
- <sect2>
- <title>Update Execution</title>
- <para>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.</para>
- </sect2>
- <sect2>
- <title>Procedure Execution</title>
- <para>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.</para>
- <para>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.
- </para>
- </sect2>
-
- <sect2>
- <title>Asynchronous Executions</title>
- <para>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.
- </para>
- <para>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.</para>
- </sect2>
-
- <sect2>
- <title>Bulk Execution</title>
- <para> Non batched <code>Insert, Update, Delete</code>
- commands may have <code>Literal</code> values marked as multiValued if the
- capabilities shows support for BulkUpdate. Commands with
- multiValued <code>Literal</code>s represent multiple executions of the same
- command with different values. As with BatchedUpdates, bulk operations should be executed atomically if possible.
- </para>
- </sect2>
- <sect2>
- <title>Command Completion</title>
- <para>All normal command executions end with the calling of <code>close()</code> on the Execution object. Your
- implementation of this method should do the appropriate clean-up work for all state created in the Execution object.</para>
- </sect2>
- <sect2>
- <title>Command Cancellation</title>
- <para>Commands submitted to Teiid may be aborted in several scenarios:</para>
- <itemizedlist>
- <listitem>
- <para>Client cancellation via the JDBC API (or other client APIs)
- </para>
- </listitem>
- <listitem>
- <para>Administrative cancellation</para>
- </listitem>
- <listitem>
- <para>Clean-up during session termination</para>
- </listitem>
- <listitem>
- <para>Clean-up if a query fails during processing</para>
- </listitem>
- </itemizedlist>
- <para>Unlike the other execution methods, which are handled in a single-threaded manner,
- calls to cancel happen asynchronously with respect to the execution thread.</para>
- <para>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.</para>
- </sect2>
- </sect1>
-
- <sect1 id="command_language">
- <title>Command Language</title>
-
- <sect2>
- <title>Language </title>
- <para>
- 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
- <link linkend="translator_capabilities">Translator Capabilities</link>
- for more information.
- </para>
- <para>The language objects all extend from the <code>LanguageObject</code> 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.</para>
- <para>All commands sent to your Translator are in the form of these
- language trees, where the root of the tree is a subclass of <code>Command</code>.
- Command has several sub-interfaces, namely:
-
- <itemizedlist>
- <listitem><para><code>QueryExpression</code></para></listitem>
- <listitem><para><code>Insert</code></para></listitem>
- <listitem><para><code>Update</code></para></listitem>
- <listitem><para><code>Delete</code></para></listitem>
- <listitem><para><code>BatchedUpdates</code></para></listitem>
- <listitem><para><code>Call</code></para></listitem>
- </itemizedlist>
-
- Important components of these commands are expressions, criteria, and joins, which are examined
- in closer detail below. Also see the <ulink url="&javaDocUrl;">Teiid JavaDocs</ulink>
- for more on the classes and interfaces described here.
- </para>
- <sect3>
- <title>Expressions</title>
- <para>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.</para>
- <itemizedlist>
- <listitem>
- <para>
- <code>Expression</code>
- – base expression interface
- </para>
- </listitem>
- <listitem>
- <para>
- <code>ColumnReference</code>
- – represents an column in the data source
- </para>
- </listitem>
- <listitem>
- <para>
- <code>Literal</code>
- – represents a literal scalar value, but may also be multi-valued in
- the case of bulk updates.
- </para>
- </listitem>
- <listitem>
- <para>
- <code>Function</code>
- – represents a scalar function with parameters that are also Expressions
- </para>
- </listitem>
- <listitem>
- <para>
- <code>Aggregate</code>
- – represents an aggregate function which holds a single expression
- </para>
- </listitem>
- <listitem>
- <para>
- <code>ScalarSubquery</code>
- – represents a subquery that returns a single value
- </para>
- </listitem>
- <listitem>
- <para>
- <code>SearchedCase, SearchedWhenClause</code>
- – 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.
- </para>
- </listitem>
- </itemizedlist>
- </sect3>
- <sect3>
- <title>Condition</title>
- <para>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.</para>
-
- <itemizedlist>
- <listitem><para><code>Condition</code> – the base criteria interface</para></listitem>
- <listitem><para><code>Not</code> – used to NOT another criteria</para></listitem>
- <listitem><para><code>AndOr</code> – used to combine other criteria via AND or OR</para></listitem>
- <listitem><para><code>SubuqeryComparison</code> – represents a comparison criteria with a subquery including a quantifier such as SOME or ALL</para></listitem>
- <listitem><para><code>Comparison</code> – represents a comparison criteria with =, >, <, etc.</para></listitem>
- <listitem><para><code>BaseInCondition</code> – base class for an IN criteria</para></listitem>
- <listitem><para><code>In</code> – represents an IN criteria that has a set of expressions for values</para></listitem>
- <listitem><para><code>SubqueryIn</code> – represents an IN criteria that uses a subquery to produce the value set</para></listitem>
- <listitem><para><code>IsNull</code> – represents an IS NULL criteria</para></listitem>
- <listitem><para><code>Exists</code> – represents an EXISTS criteria that determines whether a subquery will return any values</para></listitem>
- <listitem><para><code>Like</code> – represents a LIKE criteria that compares string values</para></listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>The FROM Clause</title>
- <para>The FROM clause contains a list of <code>TableReference</code>'s. </para>
-
- <itemizedlist>
- <listitem><para><code>NamedTable</code> – represents a single Table</para></listitem>
- <listitem><para><code>Join</code> – has a left and right <code>TableReference</code> and information on the join between the items</para></listitem>
- <listitem><para><code>DerivedTable</code> – represents a table defined by an inline <code>QueryExpression</code></para></listitem>
- </itemizedlist>
- <para>
- A list of <code>TableReference</code>
- 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
- <code>Join</code>
- 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. See
- <link linkend="command_form_capabilities">Command Form Capabilities</link>
- for more information.
- </para>
- </sect3>
- <sect3>
- <title>QueryExpression Structure</title>
- <para><code>QueryExpression</code> is the base for both SELECT queries and set queries. It may optionally take an
- <code>OrderBy</code> (representing a SQL ORDER BY clause) and a <code>Limit</code> (represent a SQL LIMIT clause)</para>
- </sect3>
-
- <sect3>
- <title>Select Structure</title>
-
- <para>Each <code>QueryExpression</code> can be a <code>Select</code> describing the expressions
- (typically elements) being selected and an <code>TableReference</code> specifying the table
- or tables being selected from, along with any join information. The
- <code>Select</code> may optionally also supply an <code>Condition</code> (representing a SQL
- WHERE clause), a <code>GroupBy</code> (representing a SQL GROUP BY clause), an
- an <code>Condition</code> (representing a SQL HAVING clause).</para>
- </sect3>
-
- <sect3>
- <title>SetQuery Structure</title>
-
- <para>A <code>QueryExpression</code> can also be a <code>SetQuery</code> that represents on of the SQL set operations (UNION,
- INTERSECT, EXCEPT) on two <code>QueryExpression</code>. The all flag may be set to
- indicate UNION ALL (currently INTERSECT and EXCEPT ALL are not allowed in Teiid)</para>
- </sect3>
-
- <sect3>
- <title>Insert Structure</title>
-
- <para>Each <code>Insert</code> will have a single <code>NamedTable</code> specifying the table being
- inserted into. It will also has a list of <code>ColumnReference</code> specifying the columns
- of the <code>NamedTable</code> that are being inserted into. It also has
- <code>InsertValueSource</code>, which will either be a list of
- <code>Expression(ExpressionValueSource)</code> or <code>QueryExpression</code></para>
- </sect3>
-
- <sect3>
- <title>Update Structure</title>
-
- <para>Each <code>Update</code> will have a single <code>NamedTable</code> specifying the table being
- updated and list of <code>SetClause</code> entries that specify <code>ColumnReference</code>
- and <code>Expression</code> pairs for the update. The Update may optionally provide a criteria
- <code>Condition</code> specifying which rows should be updated.</para>
- </sect3>
-
- <sect3>
- <title>Delete Structure</title>
-
- <para>Each <code>Delete</code> will have a single <code>NamedTable</code> specifying the table being
- deleted from. It may also optionally have a criteria specifying which rows should be deleted. </para>
- </sect3>
-
- <sect3>
- <title>Call Structure</title>
-
- <para>Each <code>Call</code> has zero or more <code>Argument</code> objects. The
- <code>Argument</code> objects describe the input parameters, the output result
- set, and the output parameters. </para>
- </sect3>
-
- <sect3>
- <title>BatchedUpdates Structure </title>
- <para>Each <code>BatchedUpdates</code> has a list of <code>Command</code> objects (which must be either
- <code>Insert</code>, <code>Update</code> or <code>Delete</code>) that compose the batch. </para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Language Utilities</title>
- <para>This section covers utilities available when using, creating, and manipulating the language interfaces.</para>
-
- <sect3>
- <title>Data Types</title>
- <para>The Translator API contains an interface <code>TypeFacility</code> that defines
- data types and provides value translation facilities. This interface can be obtained from calling "getTypeFacility()"
- method on the "ExecutionFactory" class.</para>
-
- <para>
- 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
- <code>Expression</code> instances define a data type based on this set of types.
- These constants are often needed in understanding or creating language interfaces.</para>
- </sect3>
-
- <sect3>
- <title>Language Manipulation</title>
- <para>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:</para>
- <para>Similar to the TypeFacility, you can call "getLanguageFactory()" method on
- the "ExecutionFactory"
- to get a reference to the <code>LanguageFactory</code> instance for your
- translator. This interface is a factory that can be used to create new
- instances of all the concrete language interface objects. </para>
- <para>Some helpful utilities for working with <code>Condition</code> objects are
- provided in the <code>LanguageUtil</code> class. This class has methods to combine
- <code>Condition</code> with AND or to break an <code>Condition</code> apart based on AND
- operators. These utilities are helpful for breaking apart a criteria
- into individual filters that your translator can implement.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Runtime Metadata</title>
- <para>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.</para>
-
- <para>Translator gets access to the <code>RuntimeMetadata</code> interface at the time of <code>Excecution</code> creation.
- Translators can access runtime metadata by using the interfaces
- defined in <code>org.teiid.metadata</code> package. This package defines
- API representing a Schema, Table, Columns and Procedures, and ways to navigate these objects.</para>
-
- <sect3>
- <title>Metadata Objects</title>
- <para>All the language objects extend <code>AbstractMetadataRecord</code> class</para>
- <itemizedlist>
- <listitem><para>Column - returns Column metadata record</para></listitem>
- <listitem><para>Table - returns a Table metadata record</para></listitem>
- <listitem><para>Procedure - returns a Procedure metadata record</para></listitem>
- <listitem><para>ProcedureParameter - returns a Procedure Parameter metadata record</para></listitem>
- </itemizedlist>
-
- <para>Once a metadata record has been obtained, it is possible to use its metadata about that object or to find other related metadata.</para>
- </sect3>
- <sect3>
- <title>Access to Runtime Metadata</title>
-
- <para>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.</para>
-
- <example>
- <title>Obtaining Metadata Properties</title>
- <para>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:</para>
- <programlisting><![CDATA[
-//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();
- ]]></programlisting>
- </example>
-
- </sect3>
- </sect2>
-
- <sect2>
- <title>Language Visitors</title>
-
- <sect3>
- <title>Framework</title>
- <para>The API provides a language visitor framework in the
- <code>org.teiid.language.visitor</code> package. The framework
- provides utilities useful in navigating and extracting information
- from trees of language objects.</para>
-
- <para>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.</para>
- <para>The base <code>AbstractLanguageVisitor</code> 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.</para>
- <para>The <code>HierarchyVisitor</code> provides the basic code for walking a
- language object tree. <code>The HierarchyVisitor</code> 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.</para>
- <para>The <code>DelegatingHierarchyVisitor</code> 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
- <code>DelegatingHierarchyVisitor</code> to aid in executing pre- and post-order
- visitors. </para>
- </sect3>
- <sect3>
- <title>Provided Visitors</title>
- <para>The <code>SQLStringVisitor</code> 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 <code>SQLStringVisitor</code> does not use the <code>HierarchyVisitor</code>
- described in the last section; it provides both iteration and
- processing type functionality in a single custom visitor. </para>
- <para>The <code>CollectorVisitor</code> 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. </para>
- </sect3>
- <sect3>
- <title>Writing a Visitor</title>
- <para>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:</para>
- <para>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
- <code>visit(ColumnReference)</code> method. Collect any state in local variables and
- provide accessor methods for that state.</para>
- <para>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.</para>
- <para>Write code to execute your visitor using the utility methods on
- DelegatingHierarchyVisitor:</para>
- <programlisting><![CDATA[
-// 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();
- ]]></programlisting>
- </sect3>
- </sect2>
- <sect2 id="translator_capabilities">
- <title>Translator Capabilities</title>
- <para>The <code>ExecutionFactory</code> 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 <code>ExecutionFactory</code> class implements all the basic capabilities, which says
- your translator does not support any cpabilities. Your extended
- <code>ExecutionFactory</code> class must override the the necessary methods to specify which
- capabilities your translator supports. </para>
- <sect3>
- <title>Capability Scope</title>
- <para>
- 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.
- </para>
- </sect3>
- <sect3>
- <title>Capabilities</title>
- <para>The following table lists the capabilities that can be specified in the <code>ExecutionFactory</code> class.</para>
- <table frame='all'>
- <title>Available Capabilities</title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1.5*" />
- <colspec colname='c2' colwidth="1*" />
- <colspec colname='c3' colwidth="2*" />
- <thead>
- <row>
- <entry>
- <para>Capability</para>
- </entry>
- <entry>
- <para>Requires</para>
- </entry>
- <entry>
- <para>Description</para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>SelectDistinct</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Translator can support SELECT DISTINCT in queries.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>SelectExpression</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Translator can support SELECT of more than just column references.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>AliasedTable</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Translator can support Tables in the FROM clause that have an alias.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>InnerJoins</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support inner and cross joins</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>SelfJoins</para>
- </entry>
- <entry>
- <para>AliasedGroups and at least on of the join type supports.</para>
- </entry>
- <entry>
- <para>Translator can support a self join between two aliased versions of the
- same Table.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>OuterJoins</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support LEFT and RIGHT OUTER JOIN.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>FullOuterJoins</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support FULL OUTER JOIN.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>InlineViews</para>
- </entry>
- <entry>
- <para>AliasedTable</para>
- </entry>
- <entry>
- <para>Translator can support a named subquery in the FROM clause.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>BetweenCriteria</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Not currently used - between criteria is rewriten as compound comparisions.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>CompareCriteriaEquals</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support comparison criteria with the operator "=”.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>CompareCriteriaOrdered</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support comparison criteria with the operator ">” or "<".</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>LikeCriteria</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support LIKE criteria.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>LikeCriteriaEscapeCharacter</para>
- </entry>
- <entry>
- <para>LikeCriteria</para>
- </entry>
- <entry>
- <para>Translator can support LIKE criteria with an ESCAPE character clause.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>InCriteria</para>
- </entry>
- <entry>
- <para>MaxInCriteria</para>
- </entry>
- <entry>
- <para>Translator can support IN predicate criteria.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>InCriteriaSubquery</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support IN predicate criteria where values are supplied by a
- subquery.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>IsNullCriteria</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support IS NULL predicate criteria.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>OrCriteria</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the OR logical criteria.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>NotCriteria</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>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.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>ExistsCriteria</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support EXISTS predicate criteria.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>QuantifiedCompareCriteriaAll</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support a quantified comparison criteria using the ALL
- quantifier.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>QuantifiedCompareCriteriaSome</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support a quantified comparison criteria using the SOME or ANY
- quantifier.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>OrderBy</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Translator can support the ORDER BY clause in queries.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>OrderByUnrelated</para>
- </entry>
- <entry>
- <para>OrderBy</para>
- </entry>
- <entry>
- <para>Translator can support the ORDER BY items that are not directly specified in the select clause.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>GroupBy</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Translator can support an explict GROUP BY clause.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Having</para>
- </entry>
- <entry>
- <para>GroupBy</para>
- </entry>
- <entry>
- <para>Translator can support the HAVING clause.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>AggregatesAvg</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the AVG aggregate function.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>AggregatesCount</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the COUNT aggregate function.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>AggregatesCountStar</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the COUNT(*) aggregate function.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>AggregatesDistinct</para>
- </entry>
- <entry>
- <para>At least one of the aggregate functions.</para>
- </entry>
- <entry>
- <para>Translator can support the keyword DISTINCT inside an aggregate function. This
- keyword indicates that duplicate values within a group of rows will be ignored.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>AggregatesMax</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the MAX aggregate function.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>AggregatesMin</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the MIN aggregate function.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>AggregatesSum</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the SUM aggregate function.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>ScalarSubqueries</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Translator can support the use of a subquery in a scalar context (wherever an
- expression is valid).</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>CorrelatedSubqueries</para>
- </entry>
- <entry>
- <para>At least one of the subquery pushdown capabilities.</para>
- </entry>
- <entry>
- <para>Translator can support a correlated subquery that refers to an element in
- the outer query.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>CaseExpressions</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Not currently used - simple case is rewriten as searched case.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>SearchedCaseExpressions</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Translator can support "searched” CASE expressions anywhere that expressions are
- accepted.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Unions</para>
- </entry>
- <entry>
- <para />
- </entry>
- <entry>
- <para>Translator support UNION and UNION ALL</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Intersect</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator supports INTERSECT</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Except</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator supports Except</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>SetQueryOrderBy</para>
- </entry>
- <entry>
- <para>Unions, Intersect, or Except</para>
- </entry>
- <entry>
- <para>Translator supports set queries with an ORDER BY</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>RowLimit</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the limit portion of the limit clause</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>RowOffset</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator can support the offset portion of the limit clause</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>FunctionsInGroupBy</para>
- </entry>
- <entry>
- <para>GroupBy</para>
- </entry>
- <entry>
- <para>Not currently used - non-element expressions in the group by create an inline view.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>InsertWithQueryExpression</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator supports INSERT statements with values specified by an QueryExpression.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>supportsBatchedUpdates</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator supports a batch of INSERT, UPDATE and DELETE commands to be executed together.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>supportsBulkUpdate</para>
- </entry>
- <entry>
- <para/>
- </entry>
- <entry>
- <para>Translator supports updates with multiple value sets</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>Note that any pushdown subquery must itself be compliant with the Translator capabilities.</para>
- </sect3>
-
- <sect3 id="command_form_capabilities">
- <title>Command Form</title>
- <para>The method <code>ExecutionFactory.useAnsiJoin()</code> should return true
- if the Translator prefers the use of ANSI style join structure for
- join trees that contain only INNER and CROSS joins.</para>
- <para>The method <code>ExecutionFactory.requiresCriteria()</code> 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".</para>
- </sect3>
-
- <sect3>
- <title>Scalar Functions</title>
- <para>The method <code>ExecutionFactory.getSupportedFunctions()</code> 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 <ulink url="&docUrl;">Reference</ulink>
- documentation. If the Translator states that it supports a function,
- it must support all type combinations and overloaded forms of that
- function.</para>
- <para>There are also five standard operators that can also be specified in the
- supported function list: +, -, *, /, and ||.</para>
- <para>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.</para>
- </sect3>
-
- <sect3>
- <title>Physical Limits</title>
- <para>The method <code>ExecutionFactory.getMaxInCriteriaSize()</code> 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.</para>
- <para>The method <code>ExecutionFactory.getMaxFromGroups()</code> can be used
- to specify the maximum number of FROM Clause groups that can used in a
- join. -1 indicates there is no limit.</para>
- </sect3>
-
- <sect3>
- <title>Update Execution Modes</title>
- <para>The method <code>ExecutionFactory.supportsBatchedUpdates()</code> can be
- used to indicate that the Translator supports executing the <code>BatchedUpdates</code> command.
- </para>
- <para>The method <code>ExecutionFactory.supportsBulkUpdate()</code> can be used
- to indicate that the Translator accepts update commands containg multi valued Literals.</para>
- <para>Note that if the translator does not support either of these
- update modes, the query engine will compensate by issuing the updates individually.</para>
- </sect3>
-
- </sect2>
-
-</sect1>
- <sect1>
- <title>Large Objects</title>
- <para>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.</para>
- <sect2>
- <title>Data Types</title>
- <para>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. </para>
- </sect2>
- <sect2>
- <title>Why Use Large Object Support?</title>
- <para>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:</para>
- <orderedlist>
- <listitem>
- <para>Reduces memory usage when returning the result set to the user.</para>
- </listitem>
- <listitem>
- <para>Improves performance by passing less data in the result set.</para>
- </listitem>
- <listitem>
- <para>Allows access to large objects when needed rather than assuming that users will
- always use the large object data.</para>
- </listitem>
- <listitem>
- <para>Allows the passing of arbitrarily large data values.</para>
- </listitem>
- </orderedlist>
- <para>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.</para>
- </sect2>
-
- <sect2>
- <title>Handling Large Objects</title>
- <para>The Translator API automatically handles large objects (Blob/Clob/SQLXML) through
- the creation of special purpose wrapper objects when it retrieves results.
- </para>
-
- <para>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.</para>
-
- <para>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. </para>
-
- <para>When the "keepAlive" alive flag is set, then the execution object is only closed when user's Statement is closed.</para>
-
- <programlisting><![CDATA[executionContext.keepExecutionAlive(true);]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Inserting or Updating Large Objects</title>
- <para>LOBs will be passed to the Translator in the
- language objects as Literal containing a java.sql.Blob, java.sql.Clob, or
- java.sql.SQLXML. You can use these interfaces to retrieve the data in
- the large object and use it for insert or update.</para>
- </sect2>
-
- </sect1>
-
- <sect1 id="translator_package">
- <title>Packaging</title>
- <para>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.
- <programlisting><![CDATA[<?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>]]></programlisting>
-
- 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.</para>
- </sect1>
-
- <sect1 id="translator_deploy">
- <title>Deployment</title>
- <para>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.</para>
- </sect1>
-</chapter>
\ No newline at end of file
Modified: trunk/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml
===================================================================
--- trunk/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml 2010-06-17 13:44:55 UTC (rev 2238)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -5,9 +5,9 @@
<chapter id="develop_adapter">
<title>Developing JEE Connectors</title>
<para>This chapter examines how to use facilities provided by the Teiid
- API to develop a JEE JCA Connector that can be used with the Teiid Translator. Please note that these are
+ API to develop a JEE JCA Connector. Please note that these are
standard JEE JCA connectors, nothing special needs to be done for Teiid. As an aid to our Translator
- developers, we provided some base implementation framework to ease the development of these Connectors.
+ developers, we provided a base implementation framework.
If you already have a JCA Connector or some other mechanism to get data from your source system, you can skip this chapter.</para>
<para>If you are not familiar with JCA API, please read the <ulink url="http://java.sun.com/j2ee/connector/">JCA 1.5 Specification</ulink>.
@@ -19,8 +19,7 @@
<sect1>
<title>Using the Teiid Framework</title>
<para>If you are going to use the Teiid framework for developing a JCA connector, follow these steps. The required classes are in
- <code>org.teiid.resource.api</code> package. Please note that Teiid framework does not make use JCA's CCI framework. It
- only uses the JCA's SPI interfaces. </para>
+ <code>org.teiid.resource.api</code> package. Please note that Teiid framework does not make use JCA's CCI framework, only the JCA's SPI interfaces. </para>
<itemizedlist>
<listitem>
@@ -145,11 +144,9 @@
<config-property-value>${optioal-property-value}</config-property-value>
</config-property>]]></programlisting>
- <para>The format and contents of "<description>" element is a Teiid extension to provide the extended metadata for tooling purpose. The
- JCA specification does not define enough metadata on these properties so Teiid fills in the gap with its own extension.
- For every property define the following properties
-
+ <para>The format and contents of "<description>" element may be used as extended metadata for tooling. The special format must begin and end with curly braces e.g. {...}. This use of the special format and all properties is optional. Property names begin with '$' and are separated from the value with ':'. Double quotes identifies a single value. A pair of square brackets, e.g. [...], containing comma separated double quoted entries denotes a list value.
<itemizedlist>
+ <para>Extended metadata properties</para>
<listitem>
<para>$display: Display name of the property</para>
</listitem>
@@ -173,13 +170,13 @@
</listitem>
</itemizedlist>
- Note that all these are optional properties; however in the absence of this metadata, tooling will not work as expected.
+ Note that all these are optional properties; however in the absence of this metadata, Teiid tooling may not work as expected.
</para>
</sect2>
</sect1>
- <sect1>
+ <sect1 id="ra_package">
<title>Packaging the Adapter</title>
<para>Once all the required code is developed, it is time to package them into a RAR artifact, that can be deployed
into a Conainer. A RAR artifact is lot more similar to a WAR. To put together a RAR file it really depends upon
@@ -230,7 +227,7 @@
you can embed the JAR file containing your connector code and any dependent library JAR files. </para>
</sect1>
- <sect1>
+ <sect1 id="ra_deploy">
<title>Deploying the Adapter</title>
<para>Once the RAR file is built, deploy it by copying the RAR file into "deploy" directory of JBoss AS's choosen profile.
Typically the server does not need to be restarted when a new RAR file is being added. Alternatively, you can also use
Deleted: trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml
===================================================================
--- trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml 2010-06-17 13:44:55 UTC (rev 2238)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -1,201 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="extendingjdbc">
- <title>Extending The JDBC Translator</title>
- <para>The JDBC Translator can be extended to handle new JDBC drivers and database versions. This is one of the most common needs of custom Translator development. This chapter
- outlines the process by which a user can modify the behavior of the JDBC Translator for a new source, rather than starting from scratch.</para>
-
- <para>To design a JDBC Translator for any RDMS that is not already provided by the Teiid, extend the
- <code>org.teiid.translator.jdbc.JDBCExecutionFactory</code> class in the "translator-jdbc" module. There
- are three types of methods that you can override from the base class to define the behavior of the Translator.</para>
-
- <table frame='all'>
- <title>Extensions</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth="2*"/>
- <thead>
- <row>
- <entry><para>Extension</para></entry>
- <entry><para>Purpose</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>Capabilities</para></entry>
- <entry><para>Specify the SQL syntax and functions the source supports.</para></entry>
- </row>
- <row>
- <entry><para>SQL Translation</para></entry>
- <entry><para>Customize what SQL syntax is used, how source-specific functions are supported, how procedures are executed.</para></entry>
- </row>
- <row>
- <entry><para>Results Translation</para></entry>
- <entry><para>Customize how results are retrieved from JDBC and translated.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <sect1>
- <title>Capabilities Extension</title>
- <para>This extension must override the methods that begin with "supports" that describe translator capabilities.
- For all the available translator capabilities please see <link linkend="translator_capabilities">this</link>.</para>
-
- <para>The most common example is adding
- support for a scalar function – this requires both declaring that the translator has the capability
- to execute the function and often modifying the SQL Translator to translate the function appropriately for the source.</para>
- <para>Another common example is turning off unsupported SQL capabilities (such as outer joins or subqueries)
- for less sophisticated JDBC sources. </para>
- </sect1>
-
- <sect1>
- <title>SQL Translation Extension</title>
- <para>The JDBCExcecutionFactory provides several methods to modify the command and the string form of the resulting syntax before it is sent to the
- JDBC driver, including:</para>
-
- <itemizedlist>
- <listitem>
- <para>Change basic SQL syntax options. See the useXXX methods, e.g. useSelectLimit returns true for SQLServer to indicate that limits are applied in the SELECT clause.</para>
- </listitem>
- <listitem>
- <para>Register one or more <link linkend="function_modifiers">FunctionModifiers</link> that define how a scalar function should be modified or transformed.</para>
- </listitem>
- <listitem>
- <para>Modify a LanguageObject. - see the translate, translateXXX, and <link linkend="function_modifiers">FunctionModifiers</link>.translate methods. Modify the passed in object and return null to indicate that the standard syntax output should be used.</para>
- </listitem>
- <listitem>
- <para>Change the way SQL strings are formed for a LanguageObject. - - see the translate, translateXXX, and <link linkend="function_modifiers">FunctionModifiers</link>.translate methods. Return a list of parts, which can contain strings and LanguageObjects, that will be appended in order to the SQL string. If the in coming LanguageObject appears in the returned list it will not be translated again.</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1>
- <title>Results Translation Extension</title>
- <para>The JDBCExecutionFactory provides several methods to modify the java.sql.Statement and java.sql.ResultSet interactions, including:</para>
- <orderedlist>
- <listitem>
- <para>Overriding the createXXXExecution to subclass the corresponding JDBCXXXExecution. The JDBCBaseExecution has protected methods to get the appropriate statement (getStatement, getPreparedStatement, getCallableStatement) and to bind prepared statement values bindPreparedStatementValues.</para>
- </listitem>
- <listitem>
- <para>Retrieve values from the JDBC ResultSet or CallableStatement - see the retrieveValue methods.</para>
- </listitem>
- </orderedlist>
-
- </sect1>
-
- <sect1>
- <title>Adding Function Support</title>
- <para>See <link linkend="udfs">User Defined Functions</link> for adding new functions to Teiid. This example will show you how to declare support for the function
- and modify how the function is passed to the data source.</para>
- <para>Following is a summary of all coding steps in supporting a new scalar function:</para>
- <orderedlist>
- <listitem>
- <para>Override the capabilities method to declare support for the function (REQUIRED)</para>
- </listitem>
- <listitem>
- <para>Implement a FunctionModifier to change how a function is translated and register it for use (OPTIONAL)</para>
- </listitem>
- </orderedlist>
- <para>There is a capabilities method getSupportedFunctions() that declares all supported scalar functions.</para>
- <informalexample>
- <para>An example of an extended capabilities class to add support for the “abs” absolute value function:</para>
- <programlisting><![CDATA[package my.connector;
-
-import java.util.ArrayList;
-import java.util.List;
-
-public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory {
- @Override
- public List getSupportedFunctions() {
- List supportedFunctions = new ArrayList();
- supportedFunctions.addAll(super.getSupportedFunctions());
- supportedFunctions.add("ABS");
- return supportedFunctions;
- }
-}]]></programlisting></informalexample>
- <para>In general, it is a good idea to call super.getSupportedFunctions() to ensure that you retain any function
- support provided by the translator you are extending.</para>
- <para>This may be all that is needed to support a Teiid function if the JDBC data source supports the
- same syntax as Teiid. The built-in SQL translation will translate most functions as: “function(arg1, arg2, …)”.</para>
- <sect2 id="function_modifiers">
- <title>Using FunctionModifiers</title>
- <para>In some cases you may need to translate the function differently or even insert
- additional function calls above or below the function being translated. The JDBC translator provides
- an abstract class <code>FunctionModifier</code> for this purpose.</para>
- <para>During the start method a modifier instance can be registered against a given function name via a call to <code>JDBCExecutionFactory.registerFunctionModifier</code>.</para>
- <para>The FunctionModifier has a method called <code>translate</code>. Use the translate method to change the way the function is represented.</para>
-
-<informalexample>
- <para>An example of overriding the translate method to change the MOD(a, b) function into an infix operator for Sybase (a % b). The translate method returns a list of strings and language objects that will be assembled by the translator into a final string. The strings will be used as is and the language objects will be further processed by the translator.</para>
-
- <programlisting><![CDATA[public class ModFunctionModifier implements FunctionModifier {
-
- public List translate(Function function) {
- List parts = new ArrayList();
- parts.add("(");
- Expression[] args = function.getParameters();
- parts.add(args[0]);
- parts.add(" % ");
- parts.add(args[1]);
- parts.add(")");
- return parts;
- }
-}]]></programlisting>
-</informalexample>
-
- <para>In addition to building your own FunctionModifiers, there are a number of pre-built generic
- function modifiers that are provided with the translator. </para>
-
- <table frame='all'>
- <title>Common Modifiers</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth=".4*"/>
- <colspec colname='c2' colwidth="1*"/>
- <thead>
- <row>
- <entry><para>Modifier</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>AliasModifier</para></entry>
- <entry><para>Handles simply renaming a function (“ucase” to “upper” for example)</para></entry>
- </row>
- <row>
- <entry><para>EscapeSyntaxModifier</para></entry>
- <entry><para>Wraps a function in the standard JDBC escape syntax for functions: {fn xxxx()}</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>To register the function modifiers for your supported functions,
- you must call the <code>ExecutionFactory.registerFunctionModifier(String name, FunctionModifier modifier)</code> method.
- <programlisting><![CDATA[public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory
-
- @Override
- public void start() {
- super.start();
-
- // register functions.
- registerFunctionModifier("abs", new MyAbsModifier());
- registerFunctionModifier("concat", new AliasModifier(“concat2”));
- }
-}]]></programlisting></para>
- <para>Support for the two functions being registered (“abs” and “concat”) must be declared
- in the capabilities as well. Functions that do not have modifiers registered will be translated as usual.
- </para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Installing Extensions</title>
- <para>Once you have developed an extension to the JDBC translator, you must install it into the Teiid Server.
- The process of <link linkend="translator_package">packaging</link> or <link linkend="translator_deploy">deploying</link> the
- extended JDBC translators is exactly as any other other translator. Since the RDMS is accessible already through its JDBC
- driver, there is no need to develop a resource adapter for this source as JBoss AS provides a wrapper JCA connector (DataSource)
- for any JDBC driver.
- </para>
- </sect1>
-</chapter>
Copied: trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml (from rev 2238, trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml)
===================================================================
--- trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml (rev 0)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -0,0 +1,201 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="extendingjdbc">
+ <title>Extending The JDBC Translator</title>
+ <para>The JDBC Translator can be extended to handle new JDBC drivers and database versions. This is one of the most common needs of custom Translator development. This chapter
+ outlines the process by which a user can modify the behavior of the JDBC Translator for a new source, rather than starting from scratch.</para>
+
+ <para>To design a JDBC Translator for any RDMS that is not already provided by the Teiid, extend the
+ <code>org.teiid.translator.jdbc.JDBCExecutionFactory</code> class in the "translator-jdbc" module. There
+ are three types of methods that you can override from the base class to define the behavior of the Translator.</para>
+
+ <table frame='all'>
+ <title>Extensions</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="2*"/>
+ <thead>
+ <row>
+ <entry><para>Extension</para></entry>
+ <entry><para>Purpose</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Capabilities</para></entry>
+ <entry><para>Specify the SQL syntax and functions the source supports.</para></entry>
+ </row>
+ <row>
+ <entry><para>SQL Translation</para></entry>
+ <entry><para>Customize what SQL syntax is used, how source-specific functions are supported, how procedures are executed.</para></entry>
+ </row>
+ <row>
+ <entry><para>Results Translation</para></entry>
+ <entry><para>Customize how results are retrieved from JDBC and translated.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect1>
+ <title>Capabilities Extension</title>
+ <para>This extension must override the methods that begin with "supports" that describe translator capabilities.
+ For all the available translator capabilities please see <link linkend="translator_capabilities">this</link>.</para>
+
+ <para>The most common example is adding
+ support for a scalar function – this requires both declaring that the translator has the capability
+ to execute the function and often modifying the SQL Translator to translate the function appropriately for the source.</para>
+ <para>Another common example is turning off unsupported SQL capabilities (such as outer joins or subqueries)
+ for less sophisticated JDBC sources. </para>
+ </sect1>
+
+ <sect1>
+ <title>SQL Translation Extension</title>
+ <para>The JDBCExcecutionFactory provides several methods to modify the command and the string form of the resulting syntax before it is sent to the
+ JDBC driver, including:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Change basic SQL syntax options. See the useXXX methods, e.g. useSelectLimit returns true for SQLServer to indicate that limits are applied in the SELECT clause.</para>
+ </listitem>
+ <listitem>
+ <para>Register one or more <link linkend="function_modifiers">FunctionModifiers</link> that define how a scalar function should be modified or transformed.</para>
+ </listitem>
+ <listitem>
+ <para>Modify a LanguageObject. - see the translate, translateXXX, and <link linkend="function_modifiers">FunctionModifiers</link>.translate methods. Modify the passed in object and return null to indicate that the standard syntax output should be used.</para>
+ </listitem>
+ <listitem>
+ <para>Change the way SQL strings are formed for a LanguageObject. - - see the translate, translateXXX, and <link linkend="function_modifiers">FunctionModifiers</link>.translate methods. Return a list of parts, which can contain strings and LanguageObjects, that will be appended in order to the SQL string. If the in coming LanguageObject appears in the returned list it will not be translated again.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Results Translation Extension</title>
+ <para>The JDBCExecutionFactory provides several methods to modify the java.sql.Statement and java.sql.ResultSet interactions, including:</para>
+ <orderedlist>
+ <listitem>
+ <para>Overriding the createXXXExecution to subclass the corresponding JDBCXXXExecution. The JDBCBaseExecution has protected methods to get the appropriate statement (getStatement, getPreparedStatement, getCallableStatement) and to bind prepared statement values bindPreparedStatementValues.</para>
+ </listitem>
+ <listitem>
+ <para>Retrieve values from the JDBC ResultSet or CallableStatement - see the retrieveValue methods.</para>
+ </listitem>
+ </orderedlist>
+
+ </sect1>
+
+ <sect1>
+ <title>Adding Function Support</title>
+ <para>See <link linkend="udfs">User Defined Functions</link> for adding new functions to Teiid. This example will show you how to declare support for the function
+ and modify how the function is passed to the data source.</para>
+ <para>Following is a summary of all coding steps in supporting a new scalar function:</para>
+ <orderedlist>
+ <listitem>
+ <para>Override the capabilities method to declare support for the function (REQUIRED)</para>
+ </listitem>
+ <listitem>
+ <para>Implement a FunctionModifier to change how a function is translated and register it for use (OPTIONAL)</para>
+ </listitem>
+ </orderedlist>
+ <para>There is a capabilities method getSupportedFunctions() that declares all supported scalar functions.</para>
+ <informalexample>
+ <para>An example of an extended capabilities class to add support for the “abs” absolute value function:</para>
+ <programlisting><![CDATA[package my.connector;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory {
+ @Override
+ public List getSupportedFunctions() {
+ List supportedFunctions = new ArrayList();
+ supportedFunctions.addAll(super.getSupportedFunctions());
+ supportedFunctions.add("ABS");
+ return supportedFunctions;
+ }
+}]]></programlisting></informalexample>
+ <para>In general, it is a good idea to call super.getSupportedFunctions() to ensure that you retain any function
+ support provided by the translator you are extending.</para>
+ <para>This may be all that is needed to support a Teiid function if the JDBC data source supports the
+ same syntax as Teiid. The built-in SQL translation will translate most functions as: “function(arg1, arg2, …)”.</para>
+ <sect2 id="function_modifiers">
+ <title>Using FunctionModifiers</title>
+ <para>In some cases you may need to translate the function differently or even insert
+ additional function calls above or below the function being translated. The JDBC translator provides
+ an abstract class <code>FunctionModifier</code> for this purpose.</para>
+ <para>During the start method a modifier instance can be registered against a given function name via a call to <code>JDBCExecutionFactory.registerFunctionModifier</code>.</para>
+ <para>The FunctionModifier has a method called <code>translate</code>. Use the translate method to change the way the function is represented.</para>
+
+<informalexample>
+ <para>An example of overriding the translate method to change the MOD(a, b) function into an infix operator for Sybase (a % b). The translate method returns a list of strings and language objects that will be assembled by the translator into a final string. The strings will be used as is and the language objects will be further processed by the translator.</para>
+
+ <programlisting><![CDATA[public class ModFunctionModifier implements FunctionModifier {
+
+ public List translate(Function function) {
+ List parts = new ArrayList();
+ parts.add("(");
+ Expression[] args = function.getParameters();
+ parts.add(args[0]);
+ parts.add(" % ");
+ parts.add(args[1]);
+ parts.add(")");
+ return parts;
+ }
+}]]></programlisting>
+</informalexample>
+
+ <para>In addition to building your own FunctionModifiers, there are a number of pre-built generic
+ function modifiers that are provided with the translator. </para>
+
+ <table frame='all'>
+ <title>Common Modifiers</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth=".4*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry><para>Modifier</para></entry>
+ <entry><para>Description</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>AliasModifier</para></entry>
+ <entry><para>Handles simply renaming a function (“ucase” to “upper” for example)</para></entry>
+ </row>
+ <row>
+ <entry><para>EscapeSyntaxModifier</para></entry>
+ <entry><para>Wraps a function in the standard JDBC escape syntax for functions: {fn xxxx()}</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>To register the function modifiers for your supported functions,
+ you must call the <code>ExecutionFactory.registerFunctionModifier(String name, FunctionModifier modifier)</code> method.
+ <programlisting><![CDATA[public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory
+
+ @Override
+ public void start() {
+ super.start();
+
+ // register functions.
+ registerFunctionModifier("abs", new MyAbsModifier());
+ registerFunctionModifier("concat", new AliasModifier(“concat2”));
+ }
+}]]></programlisting></para>
+ <para>Support for the two functions being registered (“abs” and “concat”) must be declared
+ in the capabilities as well. Functions that do not have modifiers registered will be translated as usual.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Installing Extensions</title>
+ <para>Once you have developed an extension to the JDBC translator, you must install it into the Teiid Server.
+ The process of <link linkend="translator_package">packaging</link> or <link linkend="translator_deploy">deploying</link> the
+ extended JDBC translators is exactly as any other other translator. Since the RDMS is accessible already through its JDBC
+ driver, there is no need to develop a resource adapter for this source as JBoss AS provides a wrapper JCA connector (DataSource)
+ for any JDBC driver.
+ </para>
+ </sect1>
+</chapter>
Property changes on: trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Modified: trunk/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml
===================================================================
--- trunk/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-06-17 13:44:55 UTC (rev 2238)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -1,6 +1,13 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
+%CustomDTD;
+]>
<chapter id="introduction">
- <title>Translators and Resource Adapters</title>
+ <title>Developing For Teiid</title>
+ <sect1>
+ <title>Introduction to the Teiid Connector Architecture</title>
+
<itemizedlist>
<para>Integrating data from a Enterprise Information System (EIS) into Teiid, is separated into two parts.</para>
<listitem>
@@ -40,6 +47,7 @@
</itemizedlist>
<para>Given a combination of a Translator + Resource Adapter, one can connect any EIS system to Teiid for their data integration needs.</para>
+ </sect1>
<sect1>
<title>Do You Need a New Translator?</title>
@@ -79,64 +87,32 @@
</para>
</listitem>
</itemizedlist>
-
- </sect1>
- <sect1>
- <title>Do You Need a New Resource Adapter?</title>
- <para>As mentioned above, for every Translator that needs to gather data from external source systems, it requires a resource adapter.
- </para>
-
- <itemizedlist>
- <para>The following resource adapters are available to Teiid.</para>
- <listitem>
- <para><emphasis>Data Source:</emphasis> This is provided by the JBoss AS container. This is used by the JDBC Translator.</para>
- </listitem>
- <listitem>
- <para><emphasis>File:</emphasis> Provides a JEE JCA based Connector to access defined directory on the file system. This is used by the File Translator</para>
- </listitem>
- <listitem>
- <para><emphasis>WS:</emphasis> Provides JEE JCA Connector to invoke Web Services using JBoss Web services stack. This is used by the WS Translator</para>
- </listitem>
- <listitem>
- <para>
- <emphasis>LDAP:</emphasis> Provides JEE JCA connector to access LDAP; Used by the LDAP Translator.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Salesforce:</emphasis> Provides JEE JCA connector to access Salesforce by invoking their Web Service interface. Used by the SalesForce Translator.
- </para>
- </listitem>
- </itemizedlist>
- <para></para>
- </sect1>
-
- <sect1>
+ <sect2>
<title>Custom Translators</title>
- <para>To write a translator, follow this procedure:</para>
<orderedlist numeration="arabic">
+ <para>High-level Translator development procedure:</para>
<listitem>
- <para>Create a new or use a Resource Adapater for the EIS system, to be used with this Translator</para>
+ <para><link linkend="custom_ra_intro"></link>Create a new or reuse an existing Resource Adapater for the EIS system, to be used with this Translator</para>
</listitem>
<listitem>
- <para>Implement the required interfaces defined by the Translator API.</para>
+ <para>Implement the required classes defined by the <link linkend="translator_api">Translator API</link>.</para>
<itemizedlist>
<listitem>
- <para>ExecutionFactory – Extend org.teiid.translator.ExecutionFactory class</para>
+ <para>Create an ExecutionFactory – Extend the <code>org.teiid.translator.ExecutionFactory</code> class</para>
</listitem>
<listitem>
- <para>Execution (and sub-interfaces) – specifies how to execute each type of command</para>
+ <para>Create relevant Executions (and sub-interfaces) – specifies how to execute each type of command</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
- <para>Define the Template for exposing configuration properties</para>
+ <para>Define the <link linkend="translator_package">template</link> for exposing configuration properties.</para>
</listitem>
<listitem>
- <para>Deploy your Translator into Teiid.</para>
+ <para><link linkend="translator_deploy">Deploy</link> your Translator.</para>
<itemizedlist>
<listitem>
- <para>Deploy a Virtual Database (VDB) with metadata corresponding to your Translator</para>
+ <para>Deploy a Virtual Database (VDB) utilizing your Translator.</para>
</listitem>
</itemizedlist>
</listitem>
@@ -146,18 +122,45 @@
</orderedlist>
<para>
This guide covers how to do each of these steps in detail. It also provides additional information for
- advanced topics, such as connection pooling, streaming large objects, and transactions. For a sample
+ advanced topics, such as streaming large objects. For sample
Translator code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">Teiid source code</ulink>
</para>
+ </sect2>
</sect1>
-
<sect1>
- <title>Required Items to write a JEE JCA based Custom Resource Adaptor</title>
- <para>To write a resource adaptor, follow this procedure:</para>
+ <title>Do You Need a New Resource Adapter?</title>
+ <para>As mentioned above, for every Translator that needs to gather data from external source systems, it requires a resource adapter.
+ </para>
+
+ <itemizedlist>
+ <para>The following resource adapters are available to Teiid.</para>
+ <listitem>
+ <para><emphasis>DataSource:</emphasis> This is provided by the JBoss AS container. This is used by the JDBC Translator.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>File:</emphasis> Provides a JEE JCA based Connector to access defined directory on the file system. This is used by the File Translator</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>WS:</emphasis> Provides JEE JCA Connector to invoke Web Services using JBoss Web services stack. This is used by the WS Translator</para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>LDAP:</emphasis> Provides JEE JCA connector to access LDAP; Used by the LDAP Translator.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Salesforce:</emphasis> Provides JEE JCA connector to access Salesforce by invoking their Web Service interface. Used by the SalesForce Translator.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <sect2 id="custom_ra_intro">
+ <title>Custom Resource Adapters</title>
<orderedlist numeration="arabic">
+ <para>High-level Resource Adapter development procedure:</para>
<listitem>
- <para>The specification is defined by the <ulink url="http://java.sun.com/j2ee/connector/">JEE JCA Connector</ulink>.
- You need to have basic idea about what JCA connectors are how they are developed and packaged.</para>
+ <para>Understand the <ulink url="http://java.sun.com/j2ee/connector/">JEE Connector</ulink> specification to have basic idea about what JCA connectors are how they are developed and packaged.</para>
</listitem>
<listitem>
<para>Gather all necessary information about your Enterprise Information System (EIS). You will need
@@ -181,7 +184,7 @@
</itemizedlist>
</listitem>
<listitem>
- <para>All the required supporting JCA SPI classes provided by the Teiid API. The JCA CCI support is not provided from Teiid</para>
+ <para>Base classes for all of the required supporting JCA SPI classes are provided by the Teiid API. The JCA CCI support is not provided from Teiid, since Teiid uses the Translator API as it's common client interface. You will want to extend:</para>
<itemizedlist>
<listitem>
<para>BasicConnectionFactory – Defines the Connection Factory</para>
@@ -195,16 +198,34 @@
</itemizedlist>
</listitem>
<listitem>
- <para>Package your resource adapter.</para>
+ <para><link linkend="ra_package">Package</link> your resource adapter.</para>
</listitem>
<listitem>
- <para>Deploy your resource adapter into Teiid.</para>
+ <para><link linkend="ra_package">Deploy</link> your resource adapter.</para>
</listitem>
</orderedlist>
<para>
This guide covers how to do each of these steps in detail. It also provides additional information for
- advanced topics such as streaming large objects and transactions. For a sample
- connector code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">Teiid Source code</ulink>
+ advanced topics, such as transactions. For a sample
+ resource adapter code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">Teiid Source code</ulink>
</para>
- </sect1>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Other Teiid Development</title>
+ <para>Teiid is highly extensible in other ways:</para>
+ <itemizedlist>
+ <listitem>
+ <para>You may add <link linkend="udfs">User Defined Functions</link>.</para>
+ </listitem>
+ <listitem>
+ <para>You may adapt <link linkend="logging">logging</link> to your needs, which is especially useful for custom audit or command logging.</para>
+ </listitem>
+ <listitem>
+ <para>You may change the <link linkend="custom_security">security</link> subsystem for custom authentication and authorization.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
</chapter>
\ No newline at end of file
Copied: trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml (from rev 2238, trunk/documentation/developer-guide/src/main/docbook/en-US/content/connector-api.xml)
===================================================================
--- trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml (rev 0)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -0,0 +1,1406 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
+%CustomDTD;
+]>
+<chapter id="translator_api">
+ <title>Translator Development</title>
+ <sect1>
+ <title>Extending the ExecutionFactory Class</title>
+ <para>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.</para>
+ <para>
+ A custom translator must extend <code>org.teiid.translator.ExecutionFactory</code>
+ 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.
+ </para>
+
+ <sect2>
+ <title>ConnectionFactory</title>
+ <para>Defines the "ConnectionFactory" interface that is expected from resource adapter. This defined as part of
+ class definition using generics while extending the "ExecutionFactory" class</para>
+ </sect2>
+
+ <sect2>
+ <title>Connection</title>
+ <para>Defines the "Connection" interface that is expected from resource adapter. This defined as part of
+ class definition using generics while extending the "ExecutionFactory" class</para>
+ </sect2>
+
+ <sect2>
+ <title>Configuration Properties</title>
+ <para>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
+ <code>@TranslatorProperty</code> annotation and provide the metadata about the property. For example, if you need a
+ property called "foo",
+ <programlisting><![CDATA[private String foo = "balh";
+
+ at TranslatorProperty(display="Foo property", description="description about Foo")
+public String getFoo() {
+ return foo;
+}
+
+public void setFoo(String value) {
+ return this.foo = value;
+}]]> </programlisting>
+
+ 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 <emphasis>should</emphasis> 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.
+ </para>
+
+ <para>The <code>@TranslatorProperty</code> defines the following metadata that you can define about your property</para>
+ <itemizedlist>
+ <listitem>
+ <para>display: Display name of the property</para>
+ </listitem>
+ <listitem>
+ <para>description: Description about the property</para>
+ </listitem>
+ <listitem>
+ <para>required: The property is a required property</para>
+ </listitem>
+ <listitem>
+ <para>advanced: This is advanced property; A default should be provided. A property can not be "advanced" and "required" at same time.</para>
+ </listitem>
+ <listitem>
+ <para>masked: The tools need to mask the property; Do not show in plain text; used for passwords</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Initializing the Translator</title>
+ <para>Override and implement the <code>start</code> 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. </para>
+ </sect2>
+
+ <sect2>
+ <title>TranslatorCapabilities</title>
+ <para>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. See <link linkend="translator_capabilities">Translator Capabilities</link> for more on these methods.</para>
+ </sect2>
+
+ <sect2>
+ <title>Execution (and sub-interfaces)</title>
+ <para>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.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><code>createResultSetExecution</code> - Define if you are doing read based operation that is
+ returning a rows of results.</para>
+ </listitem>
+ <listitem>
+ <para><code>createUpdateExecution</code> - Define if you are doing write based operations.</para>
+ </listitem>
+ <listitem>
+ <para><code>createProcedureExecution</code> - Define if you are doing procedure based operations.</para>
+ </listitem>
+ </itemizedlist>
+ <para>You can choose to implement all the execution modes or just what you need. See more details on this below.</para>
+ </sect2>
+
+ <sect2>
+ <title>Metadata</title>
+ <para>Override and implement the method <code>getMetadata()</code>, 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. </para>
+ </sect2>
+
+ <sect2>
+ <title>Logging</title>
+ <para>Teiid provides <code>org.teiid.logging.LogManager</code> 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.</para>
+ </sect2>
+
+ <sect2>
+ <title>Exceptions</title>
+ <para>If you need to bubble up any exception use <code>org.teiid.translator.TranslatorException</code>
+ class.</para>
+ </sect2>
+
+ <sect2>
+ <title>Default Name</title>
+ <para>Finally, you can define a default instance of your Translator by defining the
+ annotation <code>@Translator</code> 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.</para>
+ </sect2>
+
+ </sect1>
+
+
+ <sect1>
+ <title>Connections to Source</title>
+ <sect2>
+ <title>Obtaining connections</title>
+ <para>The extended "ExecutionFactory" must implement the <code>getConnection()</code> method to
+ allow the Connector Manager to obtain a connection. </para>
+ </sect2>
+ <sect2>
+ <title>Releasing Connections</title>
+ <para>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.</para>
+ <para>
+ 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.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>Executing Commands</title>
+ <sect2>
+ <title>Execution Modes</title>
+ <para>
+ 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 <link linkend="command_language">Command Language</link>.
+ translators are allowed to support any subset of the available execution modes.
+ </para>
+ <table frame='all'>
+ <title>Types of Execution Modes</title>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1*" />
+ <colspec colname='c2' colwidth="1*" />
+ <colspec colname='c3' colwidth="2*" />
+ <thead>
+ <row>
+ <entry>Execution Interface</entry>
+ <entry>Command interface(s)</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <code>ResultSetExecution</code>
+ </entry>
+ <entry>
+ <code>QueryExpression</code>
+ </entry>
+ <entry>A query corresponding to a SQL SELECT or set query statement.</entry>
+ </row>
+ <row>
+ <entry>
+ <code>UpdateExecution</code>
+ </entry>
+ <entry>
+ <code>Insert, Update, Delete, BatchedUpdates</code>
+ </entry>
+ <entry>An insert, update, or delete, corresponding to a SQL INSERT, UPDATE, or DELETE command
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <code>ProcedureExecution</code>
+ </entry>
+ <entry>
+ <code>Call</code>
+ </entry>
+ <entry>A procedure execution that may return a result set and/or output values.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>All of the execution interfaces extend the base <code>Execution</code>
+ interface that defines how executions are
+ cancelled and closed. ProcedureExecution also extends ResultSetExecution, since procedures may also return resultsets.</para>
+ </sect2>
+ <sect2>
+ <title>ResultSetExecution</title>
+ <para>
+ 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.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Update Execution</title>
+ <para>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.</para>
+ </sect2>
+ <sect2>
+ <title>Procedure Execution</title>
+ <para>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.</para>
+ <para>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.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Asynchronous Executions</title>
+ <para>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.
+ </para>
+ <para>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.</para>
+ </sect2>
+
+ <sect2>
+ <title>Bulk Execution</title>
+ <para> Non batched <code>Insert, Update, Delete</code>
+ commands may have <code>Literal</code> values marked as multiValued if the
+ capabilities shows support for BulkUpdate. Commands with
+ multiValued <code>Literal</code>s represent multiple executions of the same
+ command with different values. As with BatchedUpdates, bulk operations should be executed atomically if possible.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Command Completion</title>
+ <para>All normal command executions end with the calling of <code>close()</code> on the Execution object. Your
+ implementation of this method should do the appropriate clean-up work for all state created in the Execution object.</para>
+ </sect2>
+ <sect2>
+ <title>Command Cancellation</title>
+ <para>Commands submitted to Teiid may be aborted in several scenarios:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Client cancellation via the JDBC API (or other client APIs)
+ </para>
+ </listitem>
+ <listitem>
+ <para>Administrative cancellation</para>
+ </listitem>
+ <listitem>
+ <para>Clean-up during session termination</para>
+ </listitem>
+ <listitem>
+ <para>Clean-up if a query fails during processing</para>
+ </listitem>
+ </itemizedlist>
+ <para>Unlike the other execution methods, which are handled in a single-threaded manner,
+ calls to cancel happen asynchronously with respect to the execution thread.</para>
+ <para>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.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="command_language">
+ <title>Command Language</title>
+
+ <sect2>
+ <title>Language </title>
+ <para>
+ 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
+ <link linkend="translator_capabilities">Translator Capabilities</link>
+ for more information.
+ </para>
+ <para>The language objects all extend from the <code>LanguageObject</code> 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.</para>
+ <para>All commands sent to your Translator are in the form of these
+ language trees, where the root of the tree is a subclass of <code>Command</code>.
+ Command has several sub-interfaces, namely:
+
+ <itemizedlist>
+ <listitem><para><code>QueryExpression</code></para></listitem>
+ <listitem><para><code>Insert</code></para></listitem>
+ <listitem><para><code>Update</code></para></listitem>
+ <listitem><para><code>Delete</code></para></listitem>
+ <listitem><para><code>BatchedUpdates</code></para></listitem>
+ <listitem><para><code>Call</code></para></listitem>
+ </itemizedlist>
+
+ Important components of these commands are expressions, criteria, and joins, which are examined
+ in closer detail below. Also see the <ulink url="&javaDocUrl;">Teiid JavaDocs</ulink>
+ for more on the classes and interfaces described here.
+ </para>
+ <sect3>
+ <title>Expressions</title>
+ <para>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.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <code>Expression</code>
+ – base expression interface
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>ColumnReference</code>
+ – represents an column in the data source
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>Literal</code>
+ – represents a literal scalar value, but may also be multi-valued in
+ the case of bulk updates.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>Function</code>
+ – represents a scalar function with parameters that are also Expressions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>Aggregate</code>
+ – represents an aggregate function which holds a single expression
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>ScalarSubquery</code>
+ – represents a subquery that returns a single value
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>SearchedCase, SearchedWhenClause</code>
+ – 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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+ <sect3>
+ <title>Condition</title>
+ <para>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.</para>
+
+ <itemizedlist>
+ <listitem><para><code>Condition</code> – the base criteria interface</para></listitem>
+ <listitem><para><code>Not</code> – used to NOT another criteria</para></listitem>
+ <listitem><para><code>AndOr</code> – used to combine other criteria via AND or OR</para></listitem>
+ <listitem><para><code>SubuqeryComparison</code> – represents a comparison criteria with a subquery including a quantifier such as SOME or ALL</para></listitem>
+ <listitem><para><code>Comparison</code> – represents a comparison criteria with =, >, <, etc.</para></listitem>
+ <listitem><para><code>BaseInCondition</code> – base class for an IN criteria</para></listitem>
+ <listitem><para><code>In</code> – represents an IN criteria that has a set of expressions for values</para></listitem>
+ <listitem><para><code>SubqueryIn</code> – represents an IN criteria that uses a subquery to produce the value set</para></listitem>
+ <listitem><para><code>IsNull</code> – represents an IS NULL criteria</para></listitem>
+ <listitem><para><code>Exists</code> – represents an EXISTS criteria that determines whether a subquery will return any values</para></listitem>
+ <listitem><para><code>Like</code> – represents a LIKE criteria that compares string values</para></listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>The FROM Clause</title>
+ <para>The FROM clause contains a list of <code>TableReference</code>'s. </para>
+
+ <itemizedlist>
+ <listitem><para><code>NamedTable</code> – represents a single Table</para></listitem>
+ <listitem><para><code>Join</code> – has a left and right <code>TableReference</code> and information on the join between the items</para></listitem>
+ <listitem><para><code>DerivedTable</code> – represents a table defined by an inline <code>QueryExpression</code></para></listitem>
+ </itemizedlist>
+ <para>
+ A list of <code>TableReference</code>
+ 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
+ <code>Join</code>
+ 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. See
+ <link linkend="command_form_capabilities">Command Form Capabilities</link>
+ for more information.
+ </para>
+ </sect3>
+ <sect3>
+ <title>QueryExpression Structure</title>
+ <para><code>QueryExpression</code> is the base for both SELECT queries and set queries. It may optionally take an
+ <code>OrderBy</code> (representing a SQL ORDER BY clause) and a <code>Limit</code> (represent a SQL LIMIT clause)</para>
+ </sect3>
+
+ <sect3>
+ <title>Select Structure</title>
+
+ <para>Each <code>QueryExpression</code> can be a <code>Select</code> describing the expressions
+ (typically elements) being selected and an <code>TableReference</code> specifying the table
+ or tables being selected from, along with any join information. The
+ <code>Select</code> may optionally also supply an <code>Condition</code> (representing a SQL
+ WHERE clause), a <code>GroupBy</code> (representing a SQL GROUP BY clause), an
+ an <code>Condition</code> (representing a SQL HAVING clause).</para>
+ </sect3>
+
+ <sect3>
+ <title>SetQuery Structure</title>
+
+ <para>A <code>QueryExpression</code> can also be a <code>SetQuery</code> that represents on of the SQL set operations (UNION,
+ INTERSECT, EXCEPT) on two <code>QueryExpression</code>. The all flag may be set to
+ indicate UNION ALL (currently INTERSECT and EXCEPT ALL are not allowed in Teiid)</para>
+ </sect3>
+
+ <sect3>
+ <title>Insert Structure</title>
+
+ <para>Each <code>Insert</code> will have a single <code>NamedTable</code> specifying the table being
+ inserted into. It will also has a list of <code>ColumnReference</code> specifying the columns
+ of the <code>NamedTable</code> that are being inserted into. It also has
+ <code>InsertValueSource</code>, which will either be a list of
+ <code>Expression(ExpressionValueSource)</code> or <code>QueryExpression</code></para>
+ </sect3>
+
+ <sect3>
+ <title>Update Structure</title>
+
+ <para>Each <code>Update</code> will have a single <code>NamedTable</code> specifying the table being
+ updated and list of <code>SetClause</code> entries that specify <code>ColumnReference</code>
+ and <code>Expression</code> pairs for the update. The Update may optionally provide a criteria
+ <code>Condition</code> specifying which rows should be updated.</para>
+ </sect3>
+
+ <sect3>
+ <title>Delete Structure</title>
+
+ <para>Each <code>Delete</code> will have a single <code>NamedTable</code> specifying the table being
+ deleted from. It may also optionally have a criteria specifying which rows should be deleted. </para>
+ </sect3>
+
+ <sect3>
+ <title>Call Structure</title>
+
+ <para>Each <code>Call</code> has zero or more <code>Argument</code> objects. The
+ <code>Argument</code> objects describe the input parameters, the output result
+ set, and the output parameters. </para>
+ </sect3>
+
+ <sect3>
+ <title>BatchedUpdates Structure </title>
+ <para>Each <code>BatchedUpdates</code> has a list of <code>Command</code> objects (which must be either
+ <code>Insert</code>, <code>Update</code> or <code>Delete</code>) that compose the batch. </para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Language Utilities</title>
+ <para>This section covers utilities available when using, creating, and manipulating the language interfaces.</para>
+
+ <sect3>
+ <title>Data Types</title>
+ <para>The Translator API contains an interface <code>TypeFacility</code> that defines
+ data types and provides value translation facilities. This interface can be obtained from calling "getTypeFacility()"
+ method on the "ExecutionFactory" class.</para>
+
+ <para>
+ 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
+ <code>Expression</code> instances define a data type based on this set of types.
+ These constants are often needed in understanding or creating language interfaces.</para>
+ </sect3>
+
+ <sect3>
+ <title>Language Manipulation</title>
+ <para>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:</para>
+ <para>Similar to the TypeFacility, you can call "getLanguageFactory()" method on
+ the "ExecutionFactory"
+ to get a reference to the <code>LanguageFactory</code> instance for your
+ translator. This interface is a factory that can be used to create new
+ instances of all the concrete language interface objects. </para>
+ <para>Some helpful utilities for working with <code>Condition</code> objects are
+ provided in the <code>LanguageUtil</code> class. This class has methods to combine
+ <code>Condition</code> with AND or to break an <code>Condition</code> apart based on AND
+ operators. These utilities are helpful for breaking apart a criteria
+ into individual filters that your translator can implement.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Runtime Metadata</title>
+ <para>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.</para>
+
+ <para>Translator gets access to the <code>RuntimeMetadata</code> interface at the time of <code>Excecution</code> creation.
+ Translators can access runtime metadata by using the interfaces
+ defined in <code>org.teiid.metadata</code> package. This package defines
+ API representing a Schema, Table, Columns and Procedures, and ways to navigate these objects.</para>
+
+ <sect3>
+ <title>Metadata Objects</title>
+ <para>All the language objects extend <code>AbstractMetadataRecord</code> class</para>
+ <itemizedlist>
+ <listitem><para>Column - returns Column metadata record</para></listitem>
+ <listitem><para>Table - returns a Table metadata record</para></listitem>
+ <listitem><para>Procedure - returns a Procedure metadata record</para></listitem>
+ <listitem><para>ProcedureParameter - returns a Procedure Parameter metadata record</para></listitem>
+ </itemizedlist>
+
+ <para>Once a metadata record has been obtained, it is possible to use its metadata about that object or to find other related metadata.</para>
+ </sect3>
+ <sect3>
+ <title>Access to Runtime Metadata</title>
+
+ <para>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.</para>
+
+ <example>
+ <title>Obtaining Metadata Properties</title>
+ <para>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:</para>
+ <programlisting><![CDATA[
+//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();
+ ]]></programlisting>
+ </example>
+
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Language Visitors</title>
+
+ <sect3>
+ <title>Framework</title>
+ <para>The API provides a language visitor framework in the
+ <code>org.teiid.language.visitor</code> package. The framework
+ provides utilities useful in navigating and extracting information
+ from trees of language objects.</para>
+
+ <para>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.</para>
+ <para>The base <code>AbstractLanguageVisitor</code> 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.</para>
+ <para>The <code>HierarchyVisitor</code> provides the basic code for walking a
+ language object tree. <code>The HierarchyVisitor</code> 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.</para>
+ <para>The <code>DelegatingHierarchyVisitor</code> 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
+ <code>DelegatingHierarchyVisitor</code> to aid in executing pre- and post-order
+ visitors. </para>
+ </sect3>
+ <sect3>
+ <title>Provided Visitors</title>
+ <para>The <code>SQLStringVisitor</code> 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 <code>SQLStringVisitor</code> does not use the <code>HierarchyVisitor</code>
+ described in the last section; it provides both iteration and
+ processing type functionality in a single custom visitor. </para>
+ <para>The <code>CollectorVisitor</code> 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. </para>
+ </sect3>
+ <sect3>
+ <title>Writing a Visitor</title>
+ <para>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:</para>
+ <para>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
+ <code>visit(ColumnReference)</code> method. Collect any state in local variables and
+ provide accessor methods for that state.</para>
+ <para>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.</para>
+ <para>Write code to execute your visitor using the utility methods on
+ DelegatingHierarchyVisitor:</para>
+ <programlisting><![CDATA[
+// 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();
+ ]]></programlisting>
+ </sect3>
+ </sect2>
+ <sect2 id="translator_capabilities">
+ <title>Translator Capabilities</title>
+ <para>The <code>ExecutionFactory</code> 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 <code>ExecutionFactory</code> class implements all the basic capabilities, which says
+ your translator does not support any cpabilities. Your extended
+ <code>ExecutionFactory</code> class must override the the necessary methods to specify which
+ capabilities your translator supports. </para>
+ <sect3>
+ <title>Capability Scope</title>
+ <para>
+ 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.
+ </para>
+ </sect3>
+ <sect3>
+ <title>Capabilities</title>
+ <para>The following table lists the capabilities that can be specified in the <code>ExecutionFactory</code> class.</para>
+ <table frame='all'>
+ <title>Available Capabilities</title>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1.5*" />
+ <colspec colname='c2' colwidth="1*" />
+ <colspec colname='c3' colwidth="2*" />
+ <thead>
+ <row>
+ <entry>
+ <para>Capability</para>
+ </entry>
+ <entry>
+ <para>Requires</para>
+ </entry>
+ <entry>
+ <para>Description</para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>SelectDistinct</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Translator can support SELECT DISTINCT in queries.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>SelectExpression</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Translator can support SELECT of more than just column references.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>AliasedTable</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Translator can support Tables in the FROM clause that have an alias.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>InnerJoins</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support inner and cross joins</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>SelfJoins</para>
+ </entry>
+ <entry>
+ <para>AliasedGroups and at least on of the join type supports.</para>
+ </entry>
+ <entry>
+ <para>Translator can support a self join between two aliased versions of the
+ same Table.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>OuterJoins</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support LEFT and RIGHT OUTER JOIN.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>FullOuterJoins</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support FULL OUTER JOIN.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>InlineViews</para>
+ </entry>
+ <entry>
+ <para>AliasedTable</para>
+ </entry>
+ <entry>
+ <para>Translator can support a named subquery in the FROM clause.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>BetweenCriteria</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Not currently used - between criteria is rewriten as compound comparisions.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>CompareCriteriaEquals</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support comparison criteria with the operator "=”.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>CompareCriteriaOrdered</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support comparison criteria with the operator ">” or "<".</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>LikeCriteria</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support LIKE criteria.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>LikeCriteriaEscapeCharacter</para>
+ </entry>
+ <entry>
+ <para>LikeCriteria</para>
+ </entry>
+ <entry>
+ <para>Translator can support LIKE criteria with an ESCAPE character clause.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>InCriteria</para>
+ </entry>
+ <entry>
+ <para>MaxInCriteria</para>
+ </entry>
+ <entry>
+ <para>Translator can support IN predicate criteria.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>InCriteriaSubquery</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support IN predicate criteria where values are supplied by a
+ subquery.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>IsNullCriteria</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support IS NULL predicate criteria.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>OrCriteria</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the OR logical criteria.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>NotCriteria</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>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.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>ExistsCriteria</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support EXISTS predicate criteria.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>QuantifiedCompareCriteriaAll</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support a quantified comparison criteria using the ALL
+ quantifier.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>QuantifiedCompareCriteriaSome</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support a quantified comparison criteria using the SOME or ANY
+ quantifier.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>OrderBy</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Translator can support the ORDER BY clause in queries.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>OrderByUnrelated</para>
+ </entry>
+ <entry>
+ <para>OrderBy</para>
+ </entry>
+ <entry>
+ <para>Translator can support the ORDER BY items that are not directly specified in the select clause.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>GroupBy</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Translator can support an explict GROUP BY clause.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Having</para>
+ </entry>
+ <entry>
+ <para>GroupBy</para>
+ </entry>
+ <entry>
+ <para>Translator can support the HAVING clause.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>AggregatesAvg</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the AVG aggregate function.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>AggregatesCount</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the COUNT aggregate function.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>AggregatesCountStar</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the COUNT(*) aggregate function.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>AggregatesDistinct</para>
+ </entry>
+ <entry>
+ <para>At least one of the aggregate functions.</para>
+ </entry>
+ <entry>
+ <para>Translator can support the keyword DISTINCT inside an aggregate function. This
+ keyword indicates that duplicate values within a group of rows will be ignored.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>AggregatesMax</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the MAX aggregate function.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>AggregatesMin</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the MIN aggregate function.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>AggregatesSum</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the SUM aggregate function.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>ScalarSubqueries</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Translator can support the use of a subquery in a scalar context (wherever an
+ expression is valid).</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>CorrelatedSubqueries</para>
+ </entry>
+ <entry>
+ <para>At least one of the subquery pushdown capabilities.</para>
+ </entry>
+ <entry>
+ <para>Translator can support a correlated subquery that refers to an element in
+ the outer query.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>CaseExpressions</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Not currently used - simple case is rewriten as searched case.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>SearchedCaseExpressions</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Translator can support "searched” CASE expressions anywhere that expressions are
+ accepted.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Unions</para>
+ </entry>
+ <entry>
+ <para />
+ </entry>
+ <entry>
+ <para>Translator support UNION and UNION ALL</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Intersect</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator supports INTERSECT</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Except</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator supports Except</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>SetQueryOrderBy</para>
+ </entry>
+ <entry>
+ <para>Unions, Intersect, or Except</para>
+ </entry>
+ <entry>
+ <para>Translator supports set queries with an ORDER BY</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>RowLimit</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the limit portion of the limit clause</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>RowOffset</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator can support the offset portion of the limit clause</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>FunctionsInGroupBy</para>
+ </entry>
+ <entry>
+ <para>GroupBy</para>
+ </entry>
+ <entry>
+ <para>Not currently used - non-element expressions in the group by create an inline view.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>InsertWithQueryExpression</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator supports INSERT statements with values specified by an QueryExpression.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>supportsBatchedUpdates</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator supports a batch of INSERT, UPDATE and DELETE commands to be executed together.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>supportsBulkUpdate</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator supports updates with multiple value sets</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Note that any pushdown subquery must itself be compliant with the Translator capabilities.</para>
+ </sect3>
+
+ <sect3 id="command_form_capabilities">
+ <title>Command Form</title>
+ <para>The method <code>ExecutionFactory.useAnsiJoin()</code> should return true
+ if the Translator prefers the use of ANSI style join structure for
+ join trees that contain only INNER and CROSS joins.</para>
+ <para>The method <code>ExecutionFactory.requiresCriteria()</code> 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".</para>
+ </sect3>
+
+ <sect3>
+ <title>Scalar Functions</title>
+ <para>The method <code>ExecutionFactory.getSupportedFunctions()</code> 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 <ulink url="&docUrl;">Reference</ulink>
+ documentation. If the Translator states that it supports a function,
+ it must support all type combinations and overloaded forms of that
+ function.</para>
+ <para>There are also five standard operators that can also be specified in the
+ supported function list: +, -, *, /, and ||.</para>
+ <para>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.</para>
+ </sect3>
+
+ <sect3>
+ <title>Physical Limits</title>
+ <para>The method <code>ExecutionFactory.getMaxInCriteriaSize()</code> 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.</para>
+ <para>The method <code>ExecutionFactory.getMaxFromGroups()</code> can be used
+ to specify the maximum number of FROM Clause groups that can used in a
+ join. -1 indicates there is no limit.</para>
+ </sect3>
+
+ <sect3>
+ <title>Update Execution Modes</title>
+ <para>The method <code>ExecutionFactory.supportsBatchedUpdates()</code> can be
+ used to indicate that the Translator supports executing the <code>BatchedUpdates</code> command.
+ </para>
+ <para>The method <code>ExecutionFactory.supportsBulkUpdate()</code> can be used
+ to indicate that the Translator accepts update commands containg multi valued Literals.</para>
+ <para>Note that if the translator does not support either of these
+ update modes, the query engine will compensate by issuing the updates individually.</para>
+ </sect3>
+
+ </sect2>
+
+</sect1>
+ <sect1>
+ <title>Large Objects</title>
+ <para>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.</para>
+ <sect2>
+ <title>Data Types</title>
+ <para>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. </para>
+ </sect2>
+ <sect2>
+ <title>Why Use Large Object Support?</title>
+ <para>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:</para>
+ <orderedlist>
+ <listitem>
+ <para>Reduces memory usage when returning the result set to the user.</para>
+ </listitem>
+ <listitem>
+ <para>Improves performance by passing less data in the result set.</para>
+ </listitem>
+ <listitem>
+ <para>Allows access to large objects when needed rather than assuming that users will
+ always use the large object data.</para>
+ </listitem>
+ <listitem>
+ <para>Allows the passing of arbitrarily large data values.</para>
+ </listitem>
+ </orderedlist>
+ <para>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.</para>
+ </sect2>
+
+ <sect2>
+ <title>Handling Large Objects</title>
+ <para>The Translator API automatically handles large objects (Blob/Clob/SQLXML) through
+ the creation of special purpose wrapper objects when it retrieves results.
+ </para>
+
+ <para>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.</para>
+
+ <para>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. </para>
+
+ <para>When the "keepAlive" alive flag is set, then the execution object is only closed when user's Statement is closed.</para>
+
+ <programlisting><![CDATA[executionContext.keepExecutionAlive(true);]]></programlisting>
+
+ </sect2>
+
+ <sect2>
+ <title>Inserting or Updating Large Objects</title>
+ <para>LOBs will be passed to the Translator in the
+ language objects as Literal containing a java.sql.Blob, java.sql.Clob, or
+ java.sql.SQLXML. You can use these interfaces to retrieve the data in
+ the large object and use it for insert or update.</para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="translator_package">
+ <title>Packaging</title>
+ <para>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.
+ <programlisting><![CDATA[<?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>]]></programlisting>
+
+ 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.</para>
+ </sect1>
+
+ <sect1 id="translator_deploy">
+ <title>Deployment</title>
+ <para>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.</para>
+ </sect1>
+</chapter>
\ No newline at end of file
Modified: trunk/documentation/developer-guide/src/main/docbook/en-US/main.xml
===================================================================
--- trunk/documentation/developer-guide/src/main/docbook/en-US/main.xml 2010-06-17 13:44:55 UTC (rev 2238)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/main.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -47,8 +47,8 @@
<xi:include href="content/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/develop-adapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/connector-api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/extending-jdbc-connector.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/translator-api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/extending-jdbc.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/udf.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Modified: trunk/documentation/docbook/en-US/legal_notice.xml
===================================================================
--- trunk/documentation/docbook/en-US/legal_notice.xml 2010-06-17 13:44:55 UTC (rev 2238)
+++ trunk/documentation/docbook/en-US/legal_notice.xml 2010-06-17 16:09:26 UTC (rev 2239)
@@ -37,7 +37,7 @@
<phone>Phone: +1 919 754 3700</phone>
<phone>Phone: 888 733 4281</phone>
<fax>Fax: +1 919 754 3701</fax>
- <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country>
+ <pob>PO Box 13588 </pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country>
</address>
</para>
<para>
Property changes on: trunk/documentation/reference
___________________________________________________________________
Name: svn:ignore
- target
.classpath
.project
.settings
+ target
.classpath
.project
.settings
Legal_Notice.html
More information about the teiid-commits
mailing list