<!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>
    <section>
        <title>Setting up the build environment</title>
        <para>For Eclipse create a empty java project and  add dependencies to "teiid-common-core", 
        "teiid-api" and JEE "connector-api" jars.</para>
        <para>For using maven use following as your dependencies.</para>
        <programlisting language="XML" role="XML"><![CDATA[
    <dependencies>
        <dependency>
            <groupId>org.jboss.teiid</groupId>
            <artifactId>teiid-api</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.jboss.teiid</groupId>
            <artifactId>teiid-common-core</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.jboss.spec.javax.resource</groupId>
            <artifactId>jboss-connector-api_1.7_spec</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>        
        ]]></programlisting> 
        <para>You can find teiid artifacts in the 
        <ulink url="http://community.jboss.org/docs/DOC-15169">JBoss maven repository </ulink></para>
    </section>
	<section>
		<title>Extending the ExecutionFactory Class</title>
		<para>
            The main class in the translator implementation is ExecutionFactory. A base class is provided in the Teiid API, 
            so 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>
        
        <programlisting language="Java" role="JAVA"><![CDATA[
package org.teiid.translator.custom;

@Translator(name="custom", description="Connect to My EIS")
public class CustomExecutionFactory extends ExecutionFactory<MyConnectionFactory, MyConnection> {

    public CustomExecutionFactory() {
    }
}                
        ]]> </programlisting>
        
        <para>Define the annotation <code>@Translator</code> on extended "ExecutionFactory" class. This annotation defines name
        and description of your translator, and also used as identifier during the deployment. This is name you would be using
        in the VDB and else where in the configuration to refer to this translator.
        </para>        
        
        <section>
            <title>ConnectionFactory</title>
            <para>Defines the "ConnectionFactory" interface that is defined in resource adapter. 
            This defined as part of class definition of extended "ExecutionFactory" class. Refer to "MyConnectionFactory" 
            sample in the previous chapter.</para>
        </section>
        
        <section>
            <title>Connection</title>
            <para>Defines the "Connection" interface that is defined in  resource adapter. This defined as part of 
            class definition of extended "ExecutionFactory" class. Refer to "MyConnection" class sample in the previous chapter.</para>
        </section>        
        
        <section>
            <title>Configuration Properties</title>
            <para>If the translator requires external configuration, that defines ways for the user to alter the 
            behavior of a program, then define a attribute variable in the class and define "get" and "set" methods 
            for that attribute. Also, annotate each "get" method with <code>@TranslatorProperty</code> 
            annotation and provide the metadata about the property. 
            </para>
             <para>
             For example, if you need a property called "foo", by providing the annotation on 
             these properties, the Teiid tooling can automatically interrogate and provide 
             graphical way to configure your Translator while designing your VDB.   
             </para>
                    <programlisting language="Java" role="JAVA"><![CDATA[private String foo = "blah";
@TranslatorProperty(display="Foo property", description="description about Foo") 
public String getFoo() 
{
   return foo;
}

public void setFoo(String value) 
{
   return this.foo = value;
}]]> </programlisting>
                    <para>
                    Only java primitive (int, boolean), primitive object wrapper (java.lang.Integer), or Enum types 
                    are supported as Translator properties. Complex objects are not supported. The default value will be 
                    derived from calling the getter method, 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 value must 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>                
        </section> 
            
        <section>
            <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>
        </section>  
        
        <section>
            <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.  Refer to <xref linkend="translator_capabilities"/> for more on these methods.</para>
        </section>     
        
        <section>
            <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> - Override if you are doing read based operation that is 
                    returning a rows of results. For ex: select</para>
                </listitem>
                <listitem>
                    <para><code>createUpdateExecution</code> - Override if you are doing write based operations. 
                    For ex:insert, update, delete</para>
                </listitem>
                <listitem>
                    <para><code>createProcedureExecution</code> - Overide if you are doing procedure based operations. 
                    For ex; stored procedures. This works well for non-relational sources.</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>     
        </section>    
        
        <section>
            <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>
        </section>         
        
        <section>
            <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>
        </section>     
        
        <section>
            <title>Exceptions</title>
            <para>If you need to bubble up any exception use <code>org.teiid.translator.TranslatorException</code>
                class.</para>
        </section>    
	</section>
    

	<section>
		<title>Connections to Source</title>
		<section>
			<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>
		</section>
		<section>
			<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>
		</section>
	</section>
	
	<section>
	   <title>Executing Commands</title>
	   <section>
			<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 
         Command Language. Refer to <xref linkend="command_language"/>. 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>
		</section>
		
		<section>
			<title>ExecutionContext</title>
			<para>The <code>org.teiid.translator.ExecutionContext</code> provides a considerable amount of information related to the current execution.  
			An <code>ExecutionContext</code> instance is made available to each <code>Execution</code>.  Specific usage is highlighted in this guide where applicable, but you may use any informational getter method as desired.
			Example usage would include calling <code>ExecutionContext.getRequestId()</code>, <code>ExecutionContext.getSession()</code>, etc. for logging purposes.</para>
			
			<section>
				<title>Source Hints</title>
				<para>The Teiid source meta-hint is used to provide hints directly to source executions via user or transformation queries.  See the reference for more on source hints.  If specified and applicable, the general and source specific
				hint will be supplied via the ExecutionContext methods <code>getGeneralHint</code> and <code>getSourceHint</code>.  See the source for the <code>OracleExecutionFactory</code> for an example of how this source hint information
				can be utilized.</para>
			</section>
			
		</section>
		
		<section>
			<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
				<code>ExecutionContext.getBatchSize()</code> method and used as a hint in fetching results from the EIS.
			</para>
		</section>
		<section>
			<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 <code>ExecutionContext.isTransactional()</code> method can be used to determine if the execution is already under a transaction.</para>
		</section>
		<section>
			<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>
		</section>

		<section id="asynchronous_executions">
			<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 <code>DataNotAvailableExecption</code>
				during a retrival method, rather than explicitly waiting or sleeping
				for the results.
				<note>
					<para>
						A <code>DataNotAvailableException</code>
						should not be thrown by the execute method. The
						<code>DataNotAvailableException</code>
						may take a delay parameter in its
						constructor to indicate how long the system should wait befor polling
						for results. Any non-negative value indicates a time until the next
						polling should be performed.
						The <code>DataNotAvailableException.NO_POLLING</code>
						exception (or any DataNotAvailableException with a negative delay)
						can be thrown to indicate that
						the execution will call
						<code>ExecutionContext.dataAvailable()</code>
						to indicate processing should resume.
					</para>
				</note>
			</para>
			<note>
				<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>
			</note>
		</section>
		
		<section>
			<title>Reusable Executions</title>
			<para>
				A translator may return instances of <code>ReusableExecution</code>s for the expected <code>Execution</code> objects.
				There can be one <code>ReusableExecution</code> per query execting node in the processing plan. 
				The lifecycle of a <code>ReusableExecution</code> is different that a normal <code>Execution</code>.
				After a normal creation/execute/close cycle the <code>ReusableExecution.reset</code> is called for another execution cycle.
				This may occur indefinitely dependin on how many times a processing node executes its query.  
				The behavior of the <code>close</code> is no different than a regular <code>Execution</code>, 
				that is it may not be called until the end of the statement if lobs are detected and any connection associated with the 
				<code>Execution</code> will also be closed.  When the user command is finished, the <code>ReusableExecution.dispose()</code> 
				method will be called.
			</para>
			<para>				
				In general <code>ReusableExecution</code>s are most useful for continuous query execution and will also be implemented using the
				<code>ExecutionCotext.dataAvailable()</code> method for <xref linkend="asynchronous_executions"/>.
				See the Client Developer's Guide for executing continuous statements.  In continuous mode the user query will be continously re-executed.  
				A ReusableExecution allows the same Execution object to be associated with the processing plan for a given processing node for the lifetime
				of the user query.  This can simplify asynch resource management, such as establishing queue listeners.
			</para>
		</section>
        
		<section>
			<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>
		</section>
		<section>
			<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>
		</section>
		<section>
			<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>
		</section>
				
	</section>
	
	<section id="command_language">
  <title>Command Language</title>
  
  <section>
    <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. Refer to 
		<xref linkend="translator_capabilities"/> 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: 
   </para>     
        <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>        

      <para>
      Important components of	these commands are expressions, criteria, and joins, 
      which are examined in closer detail below. For more on the classes and interfaces 
      described here, refer to the Teiid JavaDocs <ulink url="&javaDocUrl;"/>.
      </para>
	
    <section>
      <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.
		</para>
	</listitem>
		<listitem>
		<para>
			<code>Parameter</code>
			– represents a parameter with multiple values.  The command should be an instance of BatchedCommand, which provides all values via getParameterValues.
		</para>
	</listitem>
	<listitem>
		<para>
			<code>Function</code>
			– represents a scalar function with parameters that are also Expressions
		</para>
	</listitem>
	<listitem>
		<para>
			<code>AggregateFunction</code>
			– represents an aggregate function which can hold a single expression
		</para>
	</listitem>
	<listitem>
		<para>
			<code>WindowFunction</code>
			– represents an window function which holds an AggregateFunction (which is also used to represent analytical functions) and a WindowSpecification
		</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>
    </section>
    <section>
      <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 =, &gt;, &lt;, 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/SIMILAR TO/LIKE_REGEX criteria that compares string values</para></listitem>
      </itemizedlist>                  
    </section>
    
    <section>
      <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. Refer to 
        <xref linkend="command_form_capabilities"/> for more information.
    </para>
    </section>
	<section>
		<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), a <code>Limit</code> (represent a SQL LIMIT clause), or a <code>With</code> (represents a SQL WITH clause).</para>
    </section>      

    <section>
      <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>
    </section>
    
    <section>
      <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>
    </section>
    
    <section>
      <title>With Structure</title>
      
      <para>A <code>With</code> clause contains named <code>QueryExpressions</code> held by <code>WithItem</code>s that can be 
      referenced as tables in the main <code>QueryExpression</code>.</para>
    
    </section>
        
    <section>    
      <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 be a list of 
            Expressions (<code>ExpressionValueSource</code>) or a <code>QueryExpression</code></para>
    </section>

    <section>
      <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>
    </section>

    <section>
      <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>
    </section>

    <section>
      <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>
    </section>
    
    <section>
      <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>    
    </section>
  </section>

  <section>
    <title>Language Utilities</title>
    <para>This section covers utilities available when using, creating, and manipulating the language interfaces.</para>
    
    <section>
      <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>
    </section>

    <section>
      <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>
    </section>      
  </section>  
    
  <section>
    <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>

    <section>
      <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>
    </section>
    <section>
      <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 language="Java" role="JAVA"><![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>
      
    </section>
  </section>
  
  <section>
    <title>Language Visitors</title>
    
    <section>
      <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>
    </section>
    <section>
      <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>
    </section>
    <section>
      <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 language="Java" role="JAVA"><![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>      
    </section>
  </section>
  <section 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 methods, which says
        your translator does not support any capabilities. Your extended 
        <code>ExecutionFactory</code> class must override the the necessary methods to specify which
		capabilities your translator supports.  You should consult the debug log of query planning (set showplan debug) to see if desired pushdown requires additional capabilities.</para>
    <section>
      <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>
    </section>
    <section>
      <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*" />
            <colspec colname='c2' colwidth="1*" />
            <colspec colname='c3' colwidth="3*" />
            <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>DependentJoins</para>
                </entry>
                <entry>
                  <para>Base join and criteria support</para>
                </entry>
                <entry>
                  <para>Translator supports dependent join pushdown.  See <xref linkend="dependent_joins"/>.  When set the MaxDependentInPredicates and MaxInCriteriaSize values are not used by the engine, rather all
                  independent values are made available to the pushdown command.</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 "&gt;" or "&lt;".</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>SimilarTo</para>
                </entry>
                <entry>
                  <para/>
                </entry>
                <entry>
                  <para>Translator can support SIMILAR TO criteria.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>LikeRegexCriteria</para>
                </entry>
                <entry>
                  <para/>
                </entry>
                <entry>
                  <para>Translator can support LIKE_REGEX criteria.</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, "&lt;=" (not "&gt;"), "&gt;=" (not "&lt;"), 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>OnlyLiteralComparison</para>
                </entry>
                <entry>
                  <para></para>
                </entry>
                <entry>
                  <para>Translator if only Literal comparisons (equality, ordered, like, etc.) are supported for non-join conditions.</para>
                </entry>
              </row>              
              <row>
                <entry>
                  <para>Convert(int fromType, int toType)</para>
                </entry>
                <entry>
                  <para></para>
                </entry>
                <entry>
                  <para>Used for fine grained control of convert/cast pushdown.  If <code>ExecutionFactory.getSupportedFunctions()</code> contains <code>SourceSystemFunctions.CONVERT</code>, then all of the default Teiid pushdown conversions are supported.
	 			  So typically this method will be implemented when <code>ExecutionFactory.getSupportedFunctions()</code> contains <code>SourceSystemFunctions.CONVERT</code>.  See <code>TypeFacility.RUNTIME_CODES</code> for the possible type codes. 
	 			  The engine will does not care about an unnecessary conversion where fromType == toType.</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 ORDER BY items that are not directly specified in the select clause.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>OrderByNullOrdering</para>
                </entry>
                <entry>
                  <para>OrderBy</para>
                </entry>
                <entry>
                  <para>Translator can support ORDER BY items with NULLS FIRST/LAST.</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>OnlySingleTableGroupBy</para>
                </entry>
                <entry>
                  <para>GroupBy</para>
                </entry>
                <entry>
                  <para>GROUP BY is restricted to only non-join queries.</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>AggregatesEnhancedNumeric</para>
                </entry>
                <entry>
                  <para/>
                </entry>
                <entry>
                  <para>Translator can support the VAR_SAMP, VAR_POP, STDDEV_SAMP, STDDEV_POP aggregate functions.</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>Translator can support non-column reference grouping expressions.</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>BulkUpdate</para>
                </entry>
                <entry>
                  <para/>
                </entry>
                <entry>
                  <para>Translator supports updates with multiple value sets</para>
                </entry>
              </row>         
              <row>
                <entry>
                  <para>CommonTableExpressions</para>
                </entry>
                <entry>
                  <para/>
                </entry>
                <entry>
                  <para>Translator supports the WITH clause.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>ElementaryOlapOperations</para>
                </entry>
                <entry>
                  <para/>
                </entry>
                <entry>
                  <para>Translator supports window functions and analytic functions RANK, DENSE_RANK, and ROW_NUMBER.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>WindowOrderByWithAggregates</para>
                </entry>
                <entry>
                  <para>ElementaryOlapOperations</para>
                </entry>
                <entry>
                  <para>Translator supports windowed aggregates with a window order by clause.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>WindowDistinctAggregates</para>
                </entry>
                <entry>
                  <para>ElementaryOlapOperations, AggregatesDistinct</para>
                </entry>
                <entry>
                  <para>Translator supports windowed distinct aggregates.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>AdvancedOlapOperations</para>
                </entry>
                <entry>
                  <para>ElementaryOlapOperations</para>
                </entry>
                <entry>
                  <para>Translator supports aggregate conditions.</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
		<para>Note that any pushdown subquery must itself be compliant with the	Translator capabilities.</para>
      </section>
      
      <section 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>
      </section>
      
      <section>
        <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 Reference documentation at
            <ulink url="&docUrl;"/>.  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>
      </section>

      <section>
        <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.getMaxDependentInPredicates()</code> is
			used to specify the maximum number of IN predicates (of at most MaxInCriteriaSize) that can be passed
			as part of a dependent join.  For example if there are 10000 values to pass as part of the dependent join
			and a MaxInCriteriaSize of 1000 and a MaxDependentInPredicates setting of 5, then the 
			dependent join logic will form two source queries each with 5 IN predicates of 1000 values each combined by OR.</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>
      </section>
      
      <section>
        <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>
      </section>
      
      <section>
      	<title>Default Behavior</title>
      	<para>The method <code>ExecutionFactory.getDefaultNullOrder()</code> specifies the default null order.  Can be one of UNKNOWN, LOW, HIGH, FIRST, LAST.  This is only used if ORDER BY is supported, but null ordering is not.</para>
      </section>
      
   </section>

</section>
    	<section>
		<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>
		<section>
			<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>
		</section>
		<section>
			<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>
		</section>
		
			<section>
		<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 via the
			<code>ExecutionContext.keepAlive</code> 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 language="Java" role="JAVA"><![CDATA[executionContext.keepExecutionAlive(true);]]></programlisting>

	</section>

	<section>
		<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>
	</section>
		
	</section>
	
	<section id="dependent_joins">
		<title>Dependent Join Pushdown</title>
		<para>Dependent joins are a technique used in federation to reduce the cost of cross source joins.  Join values from one side of a join are made available 
		to the other side which reduces the number of tuples needed to preform the join.  Translators may indicate support for dependent join pushdown via the supportsDependentJoin capability.  The
		handling of pushdown dependent join queries can be quite complicated.  The ordering (if present) and all of the non-dependent criteria constructs on the pushdown command must be honored, but if needed
		the dependent criteria, which will be a <code>Comparison</code> with a <code>Parameter</code>, may be ignored in part or in total.  Pushdown dependent join queries will be instances of 
		<code>Select</code> with the relevant dependent sets available via <code>Select.getDependentSets()</code>.  The dependent set is associated to Parameters by id via the <code>Parameter.getDepenentValueId()</code>
		 identifier.  The dependent set tuple iterators provide rows that are referenced by the column positions (available via <code>Parameter.getValueIndex()</code>) on the dependent join Comparison 
		criteria right expression.  Care should be taken with the tuple values as they may guareenteed to be unique or ordered.  
		</para>
		<note><para>There is no reference implementation of this functionality as all built-in translators
		rely on the engine to handle breaking up dependent joins into simplier queries.</para></note>
	</section>
	
	<section id="delegating_translator">
		<title>Delegating Translator</title>
		<para>In some instances you may wish to extend several differnt kinds of translators with the same functionality.  
		Rather than create separate subclasses for each extension, you can use the delegating translator framework which provides you with a proxying mechanism to override translator behavior.
		Your common translator logic can be added to a subclass of <code>BaseDelegatingExecutionFactory</code> where you can override any of the delegation methods to perform whatever logic you want.
        <example>
        	<title>Example BaseDelegatingExecutionFactory Subclass</title>
        	<programlisting language="JAVA"><![CDATA[@Translator(name="custom-delegator")
public class MyTranslator extends BaseDelegatingExecutionFactory<Object, Object> {
	
	@Override
	public Execution createExecution(Command command,
			ExecutionContext executionContext, RuntimeMetadata metadata,
			Object connection) throws TranslatorException {
		if (command instanceof Select) {
			//modify the command or return a different execution
			...
			
		}
		//the super call will be to the delegate instance
		return super.createExecution(command, executionContext, metadata, connection);
	}
	...	
}]]></programlisting>
		</example>
		</para>
		<para>You will bundle and deploy your custom delegating translator is just like any other custom translator development.  
		To you use your delegating translator in a vdb, you define a translator override that wires in the delegate.
        <example>
        	<title>Example Translator Override</title>
        	<programlisting language="JAVA"><![CDATA[<translator type="custom-delegator" name="my-translator">

     <property value="delegateName" name="name of the delegate instance"/>

     <!-- any custom properties you may have on your custom translator -->

</translator>]]></programlisting>
			<para>From the previous example the translator type is custom-delegator.  Now my-translator can be used as a translator-name on a source and will proxy all calls to whatever delegate instance you assign.</para>
		</example>
		<note><para>The delegate instance can be any translator instance whether configured by it's own translator entry or just the name of a standard translator type.  Using a <code>BaseDelegatingExecutionFactory</code> by default means that standard override translator property settings on your instance will have no effect, since the underlying delegate is called instead.</para></note>
		<para>You may also wish to use a different class hierarchy and instead make your custom translator just implement <code>DelegatingExecutionFactory</code> instead.</para>
		</para>
	</section>
    
    <section>
        <title>Adding Dependent Libraries</title>
        <para>Add MANIFEST.MF file in the MATA-INF directory, and the following line to add the core Teiid API dependencies for 
        resource adapter. <emphasis>Dependencies: org.jboss.teiid.common-core,org.jboss.teiid.api,javax.api</emphasis> 
        If your translator depends upon any other third party jar files, then those jar files need to be defined under a module
        and then you can add the module name to the above MANIFEST.MF file to define as dependency.
        </para>
    </section>
        
    <section id="translator_package">
        <title>Packaging</title>
        <para>
        Once the "ExecutionFactory" class is implemented, package it in a JAR file. Then add the following named file in 
        "META-INF/services/org.teiid.translator.ExecutionFactory" with contents specifying the name of your main Translator file.
        Note that, the name must exactly match to above. This is java's standard service loader pattern.
        This will register the Translator for deployment when the jar is deployed into JBoss AS.
        </para>
        <programlisting role="XML" language="XML"><![CDATA[
org.teiid.translator.custom.CustomExecutionFactory        
        ]]></programlisting>
    </section>
    
    <section 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 modules, they need to be placed inside the "modules" directory of the JBoss AS. 
        This will require a restart of the JBoss Server. You can also use JBoss CLI, Admin API, admin-consle
        to deploy the jar file into JBoss AS server.</para>
    </section>    
</chapter>