Author: shawkins Date: 2010-06-17 09:44:55 -0400 (Thu, 17 Jun 2010) New Revision: 2238 Added: trunk/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml Removed: trunk/documentation/developer-guide/src/main/docbook/en-US/content/command-language.xml trunk/documentation/developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml trunk/documentation/developer-guide/src/main/docbook/en-US/content/lob-support.xml Modified: trunk/connectors/connector-ldap/src/main/rar/META-INF/ra.xml trunk/connectors/connector-ws/src/main/rar/META-INF/ra.xml trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/JDBCBaseExecution.java trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-b.xml trunk/documentation/developer-guide/src/main/docbook/en-US/content/connector-api.xml trunk/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.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/reference/src/main/docbook/en-US/content/datatypes.xml trunk/documentation/reference/src/main/docbook/en-US/content/scalar_functions.xml trunk/documentation/reference/src/main/docbook/en-US/content/sql_support.xml trunk/documentation/reference/src/main/docbook/en-US/content/translators.xml Log: TEIID-315 initial revisions to the developers guide Modified: trunk/connectors/connector-ldap/src/main/rar/META-INF/ra.xml =================================================================== --- trunk/connectors/connector-ldap/src/main/rar/META-INF/ra.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/connectors/connector-ldap/src/main/rar/META-INF/ra.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -68,7 +68,7 @@ </config-property> <config-property> - <description>{$display:"Ldap Context Factory",$description:"LDAP Context factory Class",$required:"true", readOnly="true"}</description> + <description>{$display:"Ldap Context Factory",$description:"LDAP Context factory Class",$required:"true", readOnly:"true"}</description> <config-property-name>LdapContextFactory</config-property-name> <config-property-type>java.lang.String</config-property-type> <config-property-value>com.sun.jndi.ldap.LdapCtxFactory</config-property-value> Modified: trunk/connectors/connector-ws/src/main/rar/META-INF/ra.xml =================================================================== --- trunk/connectors/connector-ws/src/main/rar/META-INF/ra.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/connectors/connector-ws/src/main/rar/META-INF/ra.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -41,13 +41,13 @@ <managedconnectionfactory-class>org.teiid.resource.adapter.ws.WSManagedConnectionFactory</managedconnectionfactory-class> <config-property> - <description>{$display:"URL, End Point",$description:"URL for HTTP, Service Endpoint for SOAP",$required="true"}</description> + <description>{$display:"URL, End Point",$description:"URL for HTTP, Service Endpoint for SOAP",$required:"true"}</description> <config-property-name>EndPoint</config-property-name> <config-property-type>java.lang.String</config-property-type> </config-property> <config-property> - <description>{$display:"WebService Security Used(None, HTTPBasic, WS-Security)",$allowed="None,HTTPBasic,WSSecurity", $description:"Type of Authentication to used with the web service; If WS-Secuirty is being used, then WS-Secuirty type must be defined", $required:"true", $defaultValue="None"}</description> + <description>{$display:"WebService Security Used",$allowed:["None","HTTPBasic","WSSecurity"], $description:"Type of Authentication to used with the web service.", $required:"true", $defaultValue:"None"}</description> <config-property-name>SecurityType</config-property-name> <config-property-type>java.lang.String</config-property-type> <config-property-value>None</config-property-value> Modified: trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/JDBCBaseExecution.java =================================================================== --- trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/JDBCBaseExecution.java 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/JDBCBaseExecution.java 2010-06-17 13:44:55 UTC (rev 2238) @@ -75,7 +75,7 @@ } /** - * Return true if this is a batched update + * Bind the values in the TranslatedCommand to the PreparedStatement */ protected void bindPreparedStatementValues(PreparedStatement stmt, TranslatedCommand tc, int rowCount) throws SQLException { List<?> params = tc.getPreparedValues(); 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-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -2,8 +2,7 @@ <title>ra.xml file Template</title> <para> This appendix contains an example of the ra.xml file that can be used as a template when creating a new Connector.</para> - <programlisting><![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -29,10 +28,10 @@ <!-- repeat for every configuration property --> <config-property> - <description>{$display:"Invocation Type",$description:"Service Invocation type (HTTP or SOAP)", $allowed="HTTP_GET, HTTP_POST, SOAP11, SOAP12", $required="true", $defaultValue="SOAP12"}</description> + <description>{$display:"${short-name}",$description:"${description}", $allowed:[${value-list}], $required:"${required-boolean}", $defaultValue:"${default-value}"}</description> <config-property-name>${property-name}</config-property-name> <config-property-type>${property-type}</config-property-type> - <config-property-value>${optioal-property-value}</config-property-value> + <config-property-value>${optional-property-value}</config-property-value> </config-property> <!-- use the below as is if you used the Connection Factory interface --> @@ -53,6 +52,7 @@ <reauthentication-support>false</reauthentication-support> </outbound-resourceadapter> </resourceadapter> -</connector> - ]]></programlisting> +</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 Modified: trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-b.xml =================================================================== --- trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-b.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/appendix-b.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -1,7 +1,7 @@ <appendix id="advanced_topics"> <title>Advanced Topics</title> <sect1> - <title>Migration From Previous Versions</title> + <title>Security Migration From Previous Versions</title> <para>It is recommended that customers who have utilized the internal JDBC membership domain from releases prior to MetaMatrix 5.5 migrate those users and groups to an LDAP compliant directory server.  Several free and open source directory servers can be used including:</para> @@ -17,7 +17,7 @@ Apache Directory Server <ulink url="http://directory.apache.org/">http://directory.apache.o... </para> - <para>If there are additional questions or the need for guidance in the migration process, please contact + <para>See the JBossAS security documentation for using an LDAP directory server. If there are additional questions or the need for guidance in the migration process, please contact technical support.</para> </sect1> </appendix> \ No newline at end of file Deleted: trunk/documentation/developer-guide/src/main/docbook/en-US/content/command-language.xml =================================================================== --- trunk/documentation/developer-guide/src/main/docbook/en-US/content/command-language.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/command-language.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -1,1000 +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="command_language"> - <title>Command Language</title> - - <sect1> - <title>Language Interfaces</title> - <para> - Teiid sends commands to your Translator in object form. The interfaces - for these objects are all defined in the "org.teiid.language" - package. These interfaces 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 - commands 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 interfaces all extend from the <emphasis>LanguageObject</emphasis> 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 <emphasis>Command</emphasis>. - 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>BatchedUpdate</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> - <sect2> - <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 - element reference such as "table.EmployeeName" represents a column in a data source - and may logically 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>Element</code> - – represents an element 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> - </sect2> - <sect2> - <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 criteria that compares string values</para></listitem> - </itemizedlist> - </sect2> - - <sect2> - <title>The FROM Clause</title> - <para>The FROM clause contains a list of <emphasis>TableReference</emphasis>.  </para> - - <itemizedlist> - <listitem><para><code>TableReference</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 <emphasis>TableReference</emphasis> - 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> - </sect2> - <sect2> - <title>QueryExpression Structure</title> - <para><emphasis>QueryExpression</emphasis> is the base for both queries and set queries. It may optionally take an - <emphasis>OrderBy</emphasis> (representing a SQL ORDER BY clause) and a <emphasis>Limit</emphasis> (represent a SQL LIMIT clause)</para> - </sect2> - - <sect2> - <title>Select Structure</title> - - <para>Each <emphasis>QueryExpression</emphasis> can be a <emphasis>Select</emphasis> describing the expressions - (typically elements) being selected and an <emphasis>TableReference</emphasis> specifying the table - or tables being selected from, along with any join information.  The - <emphasis>Select</emphasis> may optionally also supply an <emphasis>Condition</emphasis> (representing a SQL - WHERE clause), an <emphasis>GroupBy</emphasis> (representing a SQL GROUP BY clause), an - an <emphasis>Condition</emphasis> (representing a SQL HAVING clause).</para> - </sect2> - - <sect2> - <title>SetQuery Structure</title> - - <para>A <emphasis>QueryExpression</emphasis> can also be a <emphasis>SetQuery</emphasis> that represents on of the SQL set operations (UNION, - INTERSECT, EXCEPT) on two <emphasis>QueryExpression</emphasis>. The all flag may be set to - indicate UNION ALL (currently INTERSECT and EXCEPT ALL are not allowed in Teiid)</para> - </sect2> - - <sect2> - <title>Insert Structure</title> - - <para>Each <emphasis>Insert</emphasis> will have a single <emphasis>NamedTable</emphasis> specifying the table being - inserted into.  It will also has a list of <emphasis>ColumnReference</emphasis> specifying the columns - of the <emphasis>TableReference</emphasis> that are being inserted into. It also has - <emphasis>InsertValueSource</emphasis>, which will either be a list of - <emphasis>Expression(ExpressionValueSource)</emphasis> or <emphasis>QueryExpression</emphasis></para> - </sect2> - - <sect2> - <title>Update Structure</title> - - <para>Each <emphasis>Update</emphasis> will have a single <emphasis>NamedTable</emphasis> specifying the table being - updated and list of <emphasis>SetClause</emphasis> entries that specify <emphasis>ColumnReference</emphasis> - and <emphasis>Expression</emphasis> pairs for the update. The Update may optionally provide a criteria - <emphasis>Condition</emphasis> specifying which rows should be updated.</para> - </sect2> - - <sect2> - <title>Delete Structure</title> - - <para>Each <emphasis>Delete</emphasis> will have a single <emphasis>NamedTable</emphasis> specifying the table being - deleted from. It may also optionally have a criteria specifying which rows should be deleted.  </para> - </sect2> - - <sect2> - <title>Call Structure</title> - - <para>Each <emphasis>Call</emphasis> has zero or more <emphasis>Argument</emphasis> objects. The - <emphasis>Argument</emphasis> objects describe the input parameters, the output result - set, and the output parameters.  </para> - </sect2> - - <sect2> - <title>BatchedUpdates Structure </title> - <para>Each <emphasis>BatchedUpdates</emphasis> has a list of <emphasis>Command</emphasis> objects (which must be either - <emphasis>Insert</emphasis>, <emphasis>Update</emphasis> or <emphasis>Delete</emphasis>) that compose the batch. </para> - </sect2> - </sect1> - - <sect1> - <title>Language Utilities</title> - <para>This section covers utilities available when using, creating, and manipulating the language interfaces.</para> - - <sect2> - <title>Data Types</title> - <para>The Translator API contains an interface <emphasis>TypeFacility</emphasis> 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 - <emphasis>Expression</emphasis> instances define a data type based on this set of types. -  These constants are often needed in understanding or creating language interfaces.</para> - </sect2> - - <sect2> - <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 <emphasis>LanguageFactory</emphasis> 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 <emphasis>Condition</emphasis> objects are - provided in the <emphasis>LanguageUtil</emphasis> class.  This class has methods to combine - <emphasis>Condition</emphasis> with AND or to break an <emphasis>Condition</emphasis> apart based on AND - operators.  These utilities are helpful for breaking apart a criteria - into individual filters that your translator can implement.</para> - </sect2> - </sect1> - - <sect1> - <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. For example, a XML model could define the 'xpath' as - one of the property on Column of a Table.</para> - - <para>Translator gets access to the <emphasis>RuntimeMetadata</emphasis> interface at the time of <emphasis>Excecution</emphasis> creation. - Translators can access runtime metadata by using the interfaces - defined in <emphasis>org.teiid.metadata</emphasis> package.  This package defines - API representing a Schema, Table, Columns and Procedures, and ways to navigate these objects.</para> - - <sect2> - <title>Language Objects</title> - <para>All the language objects extend <emphasis>AbstractMetadataRecord</emphasis> 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 or objects.</para> - </sect2> - <sect2> - <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 - metadta records based on their fully qualified names in the VDB. There are several kinds of - metadata objects and they can be used to find more information about - the objects in runtime metadata.  </para> - - - <para><emphasis>Obtaining Metadata Properties Example</emphasis></para> - - <para>The process of getting an 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 -Properties props = table.getProperties(); - ]]></programlisting> - - </sect2> - </sect1> - - <sect1> - <title>Language Visitors</title> - - <sect2> - <title>Framework</title> - <para>The API provides a language visitor framework in the - <emphasis>org.teiid.language.visitor</emphasis> 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 <emphasis>AbstractLanguageVisitor</emphasis> 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 <emphasis>HierarchyVisitor</emphasis> provides the basic code for walking a - language object tree.  <emphasis>The HierarchyVisitor</emphasis> 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 <emphasis>DelegatingHierarchyVisitor</emphasis> 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 - <emphasis>DelegatingHierarchyVisitor</emphasis> to aid in executing pre- and post-order - visitors.   </para> - </sect2> - <sect2> - <title>Provided Visitors</title> - <para>The <emphasis>SQLStringVisitor</emphasis> 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 <emphasis>SQLStringVisitor</emphasis> does not use the <emphasis>HierarchyVisitor</emphasis> - described in the last section; it provides both iteration and - processing type functionality in a single custom visitor.    </para> - <para>The <emphasis>CollectorVisitor</emphasis> 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> - </sect2> - <sect2> - <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 - <emphasis>visit(ColumnReference)</emphasis> 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> - </sect2> - </sect1> - <sect1 id="translator_capabilities"> - <title>Translator Capabilities</title> - <para>The <emphasis>ExecutionFactory</emphasis> 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 <emphasis>ExecutionFactory</emphasis> class implements all the basic capabilities, which says - your translator does not support any cpabilities. Your extended - <emphasis>ExecutionFactory</emphasis> class must override the the necessary methods to specify which - capabilities your translator supports.  </para> - <sect2> - <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> - </sect2> - <sect2> - <title>Capabilities</title> - <para>The following table lists the capabilities that can be specified in the <emphasis>ExecutionFactory</emphasis> 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 "&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>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>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> - </sect2> - - <sect2 id="command_form_capabilities"> - <title>Command Form</title> - <para>The method <emphasis>ExecutionFactory.useAnsiJoin()</emphasis> 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 <emphasis>ExecutionFactory.requiresCriteria()</emphasis> 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> - </sect2> - - <sect2> - <title>Scalar Functions</title> - <para>The method <emphasis>ExecutionFactory.getSupportedFunctions()</emphasis> 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> - </sect2> - - <sect2> - <title>Physical Limits</title> - <para>The method <emphasis>ExecutionFactory.getMaxInCriteriaSize()</emphasis> 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 <emphasis>ExecutionFactory.getMaxFromGroups()</emphasis> 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> - </sect2> - - <sect2> - <title>Update Execution Modes</title> - <para>The method <emphasis>ExecutionFactory.supportsBatchedUpdates()</emphasis> can be - used to indicate that the Translator supports executing the <emphasis>BatchedUpdates</emphasis> command. - </para> - <para>The method <emphasis>ExecutionFactory.supportsBulkUpdate()</emphasis> 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> - </sect2> - - </sect1> - -</chapter> \ No newline at end of file Modified: 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-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -3,14 +3,14 @@ %CustomDTD; ]> <chapter id="translator_api"> - <title>Developing a Translator</title> + <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 <emphasis>org.teiid.translator.ExecutionFactory</emphasis> + 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> @@ -32,10 +32,9 @@ <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 - <emphasis>@TranslatorProperty</emphasis> annotation and provide the metadata about the property. For example, if you need a + <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"; + <programlisting><![CDATA[String foo = "balh"; @TranslatorProperty(display="Foo property", description="description about Foo") public String getFoo() { @@ -44,19 +43,17 @@ public void setFoo(String value) { return this.foo = value; -} - ]]> </programlisting> +}]]> </programlisting> by providing the annotation on these properties, the Teiid tooling will automatically interrogate and provide graphical way to configure your - Translator. Only "java.lang" and java "primitive" types are supported as Translator properties. - If you do not provide the property during the configuration, the default value defined in this class will be used. - All the properties <emphasis>should</emphasis> have a default value. If you can not provide a default value, - validate all the required properties during the initialization, fail if one is not provided. Repeat this - process for all the properties that you require to configure the Translator. + 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 <emphasis>@TranslatorProperty</emphasis> defines the following metadata that you can define about your property</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> @@ -65,10 +62,10 @@ <para>description: Description about the property</para> </listitem> <listitem> - <para>required: The property is a required property; or optional and a default is supplied</para> + <para>required: The property is a required property</para> </listitem> <listitem> - <para>advanced: This is advanced property; A default must be provided. A property can not be "advanced" and "required" at same time.</para> + <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> @@ -78,7 +75,7 @@ <sect2> <title>Initializing the Translator</title> - <para>Override and implement the <emphasis>start</emphasis> method (be sure to call + <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> @@ -86,9 +83,8 @@ <sect2> <title>TranslatorCapabilities</title> <para>These are various methods that typically begin with method - signature "supports" on the "ExecutionFactory" calss. These methods need to be overridden to describe the execution - capabilities of the Translator. These will be used by the query engine to determine the capabilities of the Translator. - More information on what these are in the next chapter.</para> + 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> @@ -98,31 +94,29 @@ <itemizedlist> <listitem> - <para><emphasis>createResultSetExecution</emphasis> - Define if you are doing read based operation that is + <para><code>createResultSetExecution</code> - Define if you are doing read based operation that is returning a rows of results.</para> </listitem> <listitem> - <para><emphasis>createUpdateExecution</emphasis> - Define if you are doing write based operations.</para> + <para><code>createUpdateExecution</code> - Define if you are doing write based operations.</para> </listitem> <listitem> - <para><emphasis>createProcedureExecution</emphasis> - Define if you are doing procedure based operations.</para> + <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. There is no restriction, but it must - implement at least one type of execution. See more details on this below.</para> + <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 <emphasis>getMetadata()</emphasis>, if you want to expose the - metadata about the source. This defines the tables with its column names, procedures with its parameter that - this translator exposing to the query engine. If you expect your translator to work with Dynamic VDB, you must override this - method, if are always going to use Designer to build the VDB then this is optional. </para> + <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 <emphasis>org.teiid.logging.LogManager</emphasis> class for logging purposes. + <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> @@ -130,14 +124,14 @@ <sect2> <title>Exceptions</title> - <para>If you need to bubble up any exception use <emphasis>org.teiid.translator.TranslatorException</emphasis> + <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 <emphasis>@Translator</emphasis> on the "ExecutionFactory". When you define this, and after deployment + 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 @@ -151,7 +145,7 @@ <title>Connections to Source</title> <sect2> <title>Obtaining connections</title> - <para>The extended "ExecutionFactory" must implement the <emphasis>getConnection()</emphasis> method to + <para>The extended "ExecutionFactory" must implement the <code>getConnection()</code> method to allow the Connector Manager to obtain a connection. </para> </sect2> <sect2> @@ -163,7 +157,7 @@ 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 - sematics are left to the user to define on their own. + semantics are left to the user to define on their own. </para> </sect2> </sect1> @@ -174,7 +168,7 @@ <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 Chapter <link linkend="command_language">Command Language</link>. + 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'> @@ -217,7 +211,7 @@ <entry> <code>Call</code> </entry> - <entry>A procedure execution that may return a result set and/or output values.</entry> + <entry>A procedure execution that may return a result set and/or output values.</entry> </row> </tbody> </tgroup> @@ -253,32 +247,18 @@ 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: - </para> - <itemizedlist> - <listitem> - <para>Set either the SynchronousWorkers annotation or the connector - binding property SynchWorkers to false - this overrides the default - behavior in which connector threads stay associated with their - Execution until the Execution is closed.</para> - </listitem> - <listitem> - <para>Throw a DataNotAvailableExecption during a retrival method, rather than explicitly waiting or sleeping for the results. The + 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> - </listitem> - <listitem> - <para>Be aware that a connector with asynchronous workers cannot be transactional.</para> - </listitem> - </itemizedlist> + </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> @@ -291,7 +271,7 @@ <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 in the Execution object.</para> + 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> @@ -320,43 +300,1104 @@ 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 =, &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 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 "&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>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>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> + <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 Execution Factory class name. This will create Java bean in the JBoss AS, that facilitates to interrogate - available properties in configuration for this Translator for tooling and Admin API.</para> + 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 - Translator will be deployed automatically. There is no restriction that, JBoss AS need to be restarted. However, if your Translator + 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 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-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -3,7 +3,7 @@ %CustomDTD; ]> <chapter id="develop_adapter"> - <title>Developing JEE JCA Adapters for Teiid Translators</title> + <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 standard JEE JCA connectors, nothing special needs to be done for Teiid. As an aid to our Translator @@ -17,9 +17,9 @@ <para>Check out the following links <ulink url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch7.chapt.htm... on JBoss</ulink> </para> <sect1> - <title>Develop Adapter using the Teiid Framework</title> + <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 - <emphasis>org.teiid.resource.api</emphasis> package. Please note that Teiid framework does not make use JCA's CCI framework. It + <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> <itemizedlist> @@ -39,59 +39,53 @@ <sect2 id="managed_connection_factory"> <title>Define Managed Connection Factory</title> - <para>Extend the <emphasis>BasicManagedConnectionFactory</emphasis>, and provide a implementation for the + <para>Extend the <code>BasicManagedConnectionFactory</code>, and provide a implementation for the "createConnectionFactory()" method. This method defines a factory method that can create connections.</para> <para>This class also defines configuration variables, like user, password, URL etc to connect to the EIS system. Define an attribute for each configuration variable, and then provide both "getter" and "setter" methods for them. Note to use only "java.lang" objects as the attributes, DO NOT use Java primitives for defining and accessing the properties. See the following code for an example.</para> - <programlisting><![CDATA[ - public class MyManagedConnectionFactory extends BasicManagedConnectionFactory { - @Override - public Object createConnectionFactory() throws ResourceException { - return new MyConnectionFactory(); - } - - // config property name (metadata for these are defined inside the ra.xml) - String userName; - public String getUserName() { - return this.userName; - } - public void setUserName(String name) { - this.userName = name; - } - - // config property count (metadata for these are defined inside the ra.xml) - Integer count; - public Integer getCount() { - return this.count; - } - public void setCount(Integer value) { - this.count = value; - } - } - ]]></programlisting> + <programlisting><![CDATA[public class MyManagedConnectionFactory extends BasicManagedConnectionFactory { + @Override + public Object createConnectionFactory() throws ResourceException { + return new MyConnectionFactory(); + } + + // config property name (metadata for these are defined inside the ra.xml) + String userName; + public String getUserName() { + return this.userName; + } + public void setUserName(String name) { + this.userName = name; + } + + // config property count (metadata for these are defined inside the ra.xml) + Integer count; + public Integer getCount() { + return this.count; + } + public void setCount(Integer value) { + this.count = value; + } +}]]></programlisting> </sect2> <sect2> <title>Define the Connection Factory class</title> - <para>Extend the <emphasis>BasicConnectionFactory</emphasis> class, and provide a implementation for the "getConnection()" method.</para> - <programlisting><![CDATA[ - public class MyConnectionFactory extends BasicConnectionFactory { - @Override - public MyConnection getConnection() throws ResourceException { - return new MyConnection(); - } - } - ]]></programlisting> + <para>Extend the <code>BasicConnectionFactory</code> class, and provide a implementation for the "getConnection()" method.</para> + <programlisting><![CDATA[public class MyConnectionFactory extends BasicConnectionFactory { + @Override + public MyConnection getConnection() throws ResourceException { + return new MyConnection(); + } +}]]></programlisting> <para>Since the Managed connection object created the "ConnectionFactory" class it has access to all the configuration parameters, if "getConnection" method needs to do pass any of credentials to the underlying EIS system. - The Connection Factory class can also get reference to the calling user's <emphasis>javax.security.auth.Subject</emphasis> during + The Connection Factory class can also get reference to the calling user's <code>javax.security.auth.Subject</code> during "getConnection" method by calling - <programlisting><![CDATA[ - Subject subject = ConnectionContext.getSubject(); - ]]></programlisting> + <programlisting><![CDATA[Subject subject = ConnectionContext.getSubject();]]></programlisting> This "Subject" object can give access to logged-in user's credentials and roles that are defined. Note that this may be null. </para> <para>Note that you can define "security-domain" for this resource adapter, that is separate from @@ -101,29 +95,27 @@ <sect2 id="connection"> <title>Define the Connection class</title> - <para>Extend the <emphasis>BasicConnection</emphasis> class, and provide a implementation based on your access + <para>Extend the <code>BasicConnection</code> class, and provide a implementation based on your access of the Connection object in the Translator. If your connection is stateful, then override "isAlive()" and "cleanup()" methods and provide proper implementations. These are called to check if a Connection is stale or need to flush them from the connection pool etc. by the Container.</para> - <programlisting><![CDATA[ - public class MyConnection extends BasicConnection { + <programlisting><![CDATA[public class MyConnection extends BasicConnection { - public void doSomeOperation(command){ - // do some operation with EIS system.. - // This is method you use in the Translator, you should know - // what need to be done here for your source.. - } - - @Override - public boolean isAlive() { - return true; - } - @Override - public void cleanUp() { - - } - } - ]]></programlisting> + public void doSomeOperation(command){ + // do some operation with EIS system.. + // This is method you use in the Translator, you should know + // what need to be done here for your source.. + } + + @Override + public boolean isAlive() { + return true; + } + @Override + public void cleanUp() { + + } +}]]></programlisting> </sect2> <sect2> @@ -146,14 +138,12 @@ fragment inside the "ra.xml" file. These properties are used by user to configure instance of this Connector inside a Container. Also, during the startup the Container reads these properties from this file and knows how to inject provided values in the "-ds.xml" file into a instance of "ManagedConnectionFactory" to create the Connection.</para> - <programlisting><![CDATA[ - <config-property> - <description>{$display:"${display-name}",$description:"${description}", $allowed="${allowed}", $required="${true|false}", $defaultValue="${default-value}"}</description> - <config-property-name>${property-name}</config-property-name> - <config-property-type>${property-type}</config-property-type> - <config-property-value>${optioal-property-value}</config-property-value> - </config-property> - ]]></programlisting> + <programlisting><![CDATA[<config-property> + <description>{$display:"${display-name}",$description:"${description}", $allowed="${allowed}", $required="${true|false}", $defaultValue="${default-value}"}</description> + <config-property-name>${property-name}</config-property-name> + <config-property-type>${property-type}</config-property-type> + <config-property-value>${optioal-property-value}</config-property-value> +</config-property>]]></programlisting> <para>The format and contents of "&lt;description&gt;" 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. @@ -206,35 +196,33 @@ <para>Maven: If you are using maven, use &lt;packaging&gt; element value as "rar". Teiid uses maven, you can look at any of the "connector" projects for sample "pom.xml" file. Here is sample pom.xml file.</para> - <programlisting><![CDATA[ - <?xml version="1.0" encoding="UTF-8"?> - <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> - <modelVersion>4.0.0</modelVersion> - <artifactId>connector-{name}</artifactId> - <groupId>org.company.project</groupId> - <name>Name Connector</name> - <packaging>rar</packaging> - <description>This connector is a sample</description> - - <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>javax.resource</groupId> - <artifactId>connector-api</artifactId> - <scope>provided</scope> - </dependency> - </dependencies> - </project> - ]]></programlisting> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> + <modelVersion>4.0.0</modelVersion> + <artifactId>connector-{name}</artifactId> + <groupId>org.company.project</groupId> + <name>Name Connector</name> + <packaging>rar</packaging> + <description>This connector is a sample</description> + + <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>javax.resource</groupId> + <artifactId>connector-api</artifactId> + <scope>provided</scope> + </dependency> + </dependencies> +</project>]]></programlisting> </listitem> </itemizedlist> <para>Make sure that the RAR file, under its "META-INF" directory has the "ra.xml" file. If you are using maven @@ -255,24 +243,22 @@ <itemizedlist> <listitem> <para>Create "${name}-ds.xml" file, and copy it into "deploy" directory of JBoss AS. - <programlisting><![CDATA[ - <!DOCTYPE connection-factories PUBLIC - "-//JBoss//DTD JBOSS JCA Config 1.5//EN" - "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd"> - - <connection-factories> - <no-tx-connection-factory> - <jndi-name>${jndi-name}</jndi-name> - <rar-name>${name}.rar</rar-name> - <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition> - - <!-- define all the properties defined in the "ra.xml" that required or needs to be modified from defaults --> - <!-- each property is defined in single element --> - <config-property name="prop-name" type="java.lang.String">prop-value</config-property> - - </no-tx-connection-factory> - </connection-factories> - ]]></programlisting> + <programlisting><![CDATA[<!DOCTYPE connection-factories PUBLIC + "-//JBoss//DTD JBOSS JCA Config 1.5//EN" + "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd"> + +<connection-factories> + <no-tx-connection-factory> + <jndi-name>${jndi-name}</jndi-name> + <rar-name>${name}.rar</rar-name> + <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition> + + <!-- define all the properties defined in the "ra.xml" that required or needs to be modified from defaults --> + <!-- each property is defined in single element --> + <config-property name="prop-name" type="java.lang.String">prop-value</config-property> + + </no-tx-connection-factory> +</connection-factories>]]></programlisting> There are lot more properties that you can define for pooling, transactions, security etc in this file. Check JBoss AS documentation for all the avaialble properties. </para> Modified: 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-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -1,19 +1,16 @@ <?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 Connector</title> - <para>The JDBC Connector can be extended to handle new JDBC drivers and database versions. This chapter - outlines the process by which a user can modify the behavior of the JDBC Connector for a new source</para> + <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> - - <sect1> - <title>Extension Interfaces</title> - <para>To design JDBC Translator for any RDMS that are not already provided by the Teiid, extend the - <emphasis>org.teiid.translator.jdbc.JDBCExecutionFactory</emphasis> class in the "translator-jdbc" module. There + <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>Extension methods</title> + <title>Extensions</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> <colspec colname='c1' colwidth="1*"/> <colspec colname='c2' colwidth="2*"/> @@ -25,23 +22,23 @@ </thead> <tbody> <row> - <entry><para>Translator Capabilities</para></entry> + <entry><para>Capabilities</para></entry> <entry><para>Specify the SQL syntax and functions the source supports.</para></entry> </row> <row> - <entry><para>SQL Translator</para></entry> + <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 Translator</para></entry> + <entry><para>Results Translation</para></entry> <entry><para>Customize how results are retrieved from JDBC and translated.</para></entry> </row> </tbody> </tgroup> </table> - <sect2> - <title>Translator Capabilities Extension</title> + <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> @@ -50,66 +47,149 @@ 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> - </sect2> + </sect1> - <sect2> + <sect1> <title>SQL Translation Extension</title> - <para>It provides ways to modify the command entering the JDBC Connector (in object form) before it is sent to the - JDBC driver (as an SQL string).</para> + <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> - <para>Common functions that the SQLTranslator can perform are:</para> - - <orderedlist> + <itemizedlist> <listitem> - <para>Arbitrarily modify the object form of a command before translation </para> + <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 “function modifiers” that define how a scalar function should be modified or transformed</para> + <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>Change the way SQL strings are formed from the object for m of a command</para> + <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> - </orderedlist> - <para>For more information on how these functions can be performed, see the examples later in this chapter.</para> - </sect2> + <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> - <sect2> + <sect1> <title>Results Translation Extension</title> - <para>This defines ways to modify the results - as they are read and returned from the JDBC driver to the Teiid Server. Common functions that the - ResultsTranslator can perform are:</para> + <para>The JDBCExecutionFactory provides several methods to modify the java.sql.Statement and java.sql.ResultSet interactions, including:</para> <orderedlist> <listitem> - <para>Execute a stored procedure against the driver</para> + <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>Execute a prepared statement with large objects against the driver</para> + <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>Execute a statement for bulk insert</para> + <para>Override the capabilities method to declare support for the function (REQUIRED)</para> </listitem> <listitem> - <para>Retrieve values from the JDBC ResultSet</para> + <para>Implement a FunctionModifier to change how a function is translated and register it for use (OPTIONAL)</para> </listitem> - <listitem> - <para>Translate values returned from JDBC into the types expected by MetaMatrix</para> - </listitem> - <listitem> - <para>Arbitrarily modify a batch of results</para> - </listitem> - </orderedlist> + </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> - <para>For more information on how these functions can be performed, see the examples later in this chapter.</para> - </sect2> + <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>Developing Extensions</title> - <para>When developing a new JDBC Translator extension, you should start with the development environment used to develop - any translator, as defined in the Translator Developer’s Guide.</para> - </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 @@ -118,4 +198,4 @@ for any JDBC driver. </para> </sect1> -</chapter> \ No newline at end of file +</chapter> 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-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -1,13 +1,13 @@ <chapter id="introduction"> - <title>Translators and Resource Adapters in Teiid</title> + <title>Translators and Resource Adapters</title> - <para>To integrate data from a Enterprise Information System (EIS) into Teiid, Teiid requires two separate modules </para> <itemizedlist> - <listitem> - <para>Translator</para> + <para>Integrating data from a Enterprise Information System (EIS) into Teiid, is separated into two parts.</para> + <listitem> + <para>A Translator, which is required.</para> </listitem> <listitem> - <para>Resource Adapter (also sometimes called as Connector or J2EE Connector or JCA Connector or RAR file) </para> + <para>An optional Resource Adapter, which will typically be a JCA Resource Adapter (also called a JEE Connector) </para> </listitem> </itemizedlist> @@ -20,27 +20,26 @@ <para>Execute the command.</para> </listitem> <listitem> - <para>Return batches of results in relational form.</para> + <para>Return batches of results translated to expected Teiid types.</para> </listitem> </itemizedlist> - <para>A Resource Adapter is:</para> + <para>A Resource Adapter:</para> <itemizedlist> <listitem> - <para>Handle all communications with individual enterprise information system(EIS), which can include databases, data feeds, flat files, etc.</para> + <para>Handles all communications with individual enterprise information system (EIS), which can include databases, data feeds, flat files, etc.</para> </listitem> <listitem> - <para>This adapter can be a <ulink url="http://java.sun.com/j2ee/connector/">JEE JCA Connector</ulink> or any other custom connection provider. - The reason Teiid uses JEE JCA is, this specification defines how one can write, package and configure access to EIS system in consistent manner. - Also, there are various commercial/open source software vendors already provide JCA Connectors that provide - access mechanisms to variety of back-end systems.</para> + <para>Can be a <ulink url="http://java.sun.com/j2ee/connector/">JCA Connector</ulink> or any other custom connection provider. + The reason Teiid recommends and uses JCA is this specification defines how one can write, package, and configure access to EIS system in consistent manner. + There are also various commercial/open source software vendors already providing JCA Connectors to access a variety of back-end systems.</para> </listitem> <listitem> - <para>Helps to execute the command and fetch results from source systems for a given Translator</para> + <para>Abstracts Translators from many common concerns, such as connection information, resource pooling, or authentication.</para> </listitem> </itemizedlist> - <para>Given a combination of a Translator + Resource Adapter, one can connect any EIS system to Teiid for their data integration needs</para> + <para>Given a combination of a Translator + Resource Adapter, one can connect any EIS system to Teiid for their data integration needs.</para> <sect1> <title>Do You Need a New Translator?</title> @@ -66,7 +65,7 @@ </listitem> <listitem> <para> - <emphasis>XML:</emphasis> Provides a procedural way to access XML content on the File system or in a Web-Service. + <emphasis>WS:</emphasis> Provides procedural access to XML content via Web Services. </para> </listitem> <listitem> @@ -85,18 +84,18 @@ <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. - The following resource adapters are provided by Teiid distribution to work with above Translators. </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 used by XML and File Translators</para> + <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>XML:</emphasis> Provides JEE JCA Connector to invoke Web Services using JBoss Web services stack. This is used by the XML Translator</para> + <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> @@ -113,7 +112,7 @@ </sect1> <sect1> - <title>Required Items to Write a Custom Translator</title> + <title>Custom Translators</title> <para>To write a translator, follow this procedure:</para> <orderedlist numeration="arabic"> <listitem> Deleted: trunk/documentation/developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml =================================================================== --- trunk/documentation/developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -1,183 +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="examples"> - <title>JDBC Extension Examples</title> - <para>This chapter contains a series of examples showing how to extend the JDBC Connector for different common scenarios. </para> - <sect1> - <title>Adding Support for a Scalar Function</title> - <sect2> - <title>Overview</title> - <para>For this example we consider how a translator might provide support for accepting - a function supported by Teiid. See the following section for adding support for a new - function unknown 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 the 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 (OPTIONAL)</para> - </listitem> - <listitem> - <para>Implement a SQLTranslator extension and register the new function modifier (OPTIONAL)</para> - </listitem> - </orderedlist> - <para>The capabilities class has a method getSupportedFunctions() that declares all the scalar functions that can be supported by the connector. To add support for a new function, extend an existing capabilities class (like the base JDBC class JDBCCapabilities or the provided base class in the Connector API, BasicConnectorCapabilities). </para> - <para>Below is 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> - <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> - <sect2> - <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 <emphasis>FunctionModifier</emphasis> can be used to register function - translations in a SQLTranslator extension. </para> - - <para>The FunctionModifier has method called "translate". Generally, it is recommended - to subclass FunctionModifier and override the method. - Use the translate method to change the way the function is represented; - this is typically only necessary when using a non-standard function form with special operators or - ways of representing parameters. </para> - - <para>Below is an example of overriding just the translate method to translate the MOD(a, b) function into an operator form 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> - - <para>You can also extend the <emphasis>AliasModifier</emphasis> that defines a method called "modify" - using which you can modify in coming function from Teiid server into some thing that is source specific.</para> - - <para>Below is an example of using a AliasFunctionModifier to modify the incoming function. This particular - example is from the Oracle JDBC Translator and is translating the Teiid function HOUR(ts) which takes a - timestamp and returns the hour part into the Oracle equivalent TO_NUMBER(TO_CHAR(ts, ‘HH24’)). - It demonstrates the use of the LanguageFactory to construct new functions and literal values.</para> - <programlisting><![CDATA[ - /** - * Convert the HOUR function into an equivalent Oracle function. - * HOUR(ts) --> TO_NUMBER(TO_CHAR(ts, 'HH24')) - */ - public class HourFunctionModifier extends AliasFunctionModifier { - - private LanguageFactory langFactory; - - public HourFunctionModifier(LanguageFactory langFactory) { - this.langFactory = langFactory; - } - - public Expression modify(Function function) { - Expression[] args = function.getParameters(); - - Function innerFunction = langFactory.createFunction("TO_CHAR", - new Expression[] { - args[0], - langFactory.createLiteral("HH24", String.class)}, String.class); - - Function outerFunction = langFactory.createFunction("TO_NUMBER", - new Expression[] { innerFunction },Integer.class); - - return outerFunction; - } - } - ]]></programlisting> - - <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>Connection Factories</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth=".5*"/> - <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>DropFunctionModifier</para></entry> - <entry><para>Replaces a function with the function’s first argument, effectively dropping the function call if it is unnecessary – useful with unneeded type conversions</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 implement call " public void registerFunctionModifier(String name, FunctionModifier modifier)" method. - Below is an example that registers some functions.</para> - <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>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>Pushdown Scalar Functions</title> - <para>“Pushdown” scalar functions are special in that they are functions new to Teiid that can be “pushed down” - to the translator. Implementing support for a pushdown scalar function is identical to implementing support - for a standard Teiid function except that the function must be declared to Teiid as such. This allows - Teiid to properly parse and resolve queries using the pushdown function.</para> - <para>Pushdown scalar functions are modeled as user-defined functions with a special attribute. - They differ from normal user-defined functions in that no code is provided and the - Teiid engine does not how to execute the function. Pushdown functions typically must be passed - to the translator for evaluation. User-defined scalar functions have a special pushdown attribute that should be - set to “Required” when modeling a pushdown function. </para> - <para>For more information on modeling user-defined scalar functions, see the Reference manual.</para> - </sect1> - -</chapter> \ No newline at end of file Deleted: trunk/documentation/developer-guide/src/main/docbook/en-US/content/lob-support.xml =================================================================== --- trunk/documentation/developer-guide/src/main/docbook/en-US/content/lob-support.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/lob-support.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -1,77 +0,0 @@ -<chapter id="lob_support"> - <title>Handling Large Objects</title> - <para>This chapter examines how to use facilities provided by the Teiid - API to use large objects such as blobs, clobs, and xml in - your Translator.</para> - - <sect1> - <title>Large Objects</title> - - <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> - </sect1> - - <sect1> - <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> - - </sect1> - - <sect1> - <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> - </sect1> -</chapter> \ No newline at end of file Added: trunk/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml =================================================================== --- trunk/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml (rev 0) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -0,0 +1,223 @@ +<?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="udfs"> + <title>User Defined Functions</title> + <para>If you need to extends Teiid's scalar function library, + then Teiid provides a means to define custom scalar functions or + User Defined Functions(UDF). The following steps need to be taken in + creating a UDF.</para> + <sect1 id="define_udf"> + <title>UDF Definition</title> + <para>The FunctionDefinition.xmi file provides metadata to the + query engine on User Defined Functions. See the Designer Documentation for more on creating a Function Definition Model.</para> + <itemizedlist> + <para>The following are used to define a UDF.</para> + <listitem> + <para> + <emphasis>Function Name</emphasis> + When you create the function name, keep these requirements in + mind: + <itemizedlist> + <listitem> + <para>You cannot use a reserved word, which includes + existing Teiid System function names.  You cannot + overload existing Teiid System functions.</para> + </listitem> + <listitem> + <para>The function name must be unique among user-defined + functions for the number of arguments.  You can use the + same function name for different numbers of types of + arguments.  Hence, you can overload your user-defined + functions.</para> + </listitem> + <listitem> + <para>The function name can only contain letters, + numbers, and the underscore (_).  Your function name must + start with a letter.</para> + </listitem> + <listitem> + <para>The function name cannot exceed 128 characters. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <emphasis>Input Parameters</emphasis> + - defines a type specific signature list. All arguments are + considered + required. + </para> + </listitem> + <listitem> + <para> + <emphasis>Return Type</emphasis> + - the expected type of the returned scalar value. + </para> + </listitem> + <listitem> + <para> + <emphasis>Pushdown</emphasis> + - can be one of REQUIRED, NEVER, ALLOWED. Indicates the expected + pushdown behavior. If NEVER or ALLOWED are specified then a Java + implementation of the function should be supplied. + </para> + </listitem> + <listitem> + <para> + <emphasis>invocationClass/invocationMethod + </emphasis> + - optional properties indicating the static method to invoke when + the UDF is not pushed down. + </para> + </listitem> + <listitem> + <para> + <emphasis>Deterministic</emphasis> + - if the method will always return the same result for the same + input parameters. + </para> + </listitem> + </itemizedlist> + <para>Even pushdown required functions need to be added as a UDF to allow + Teiid to properly parse and resolve the function. Pushdown scalar functions differ from normal user-defined functions in that no code is provided for evaluation in the engine. + An exception will be raised if a pushdown required function cannot be evaluated by the appropriate source.</para> + </sect1> + <sect1> + <title>Source Supported UDF</title> + <para>While Teiid provides an extensive scalar function + library, it contains only those functions that can be evaluated + within the query engine. In many circumstances, especially for + performance, a user defined function allows for calling a source + specific function.</para> + + <para>For example, suppose you want to use the Oracle-specific + functions score and contains: + </para> + <informalexample> + <programlisting>SELECT score(1), ID, FREEDATA FROM Docs WHERE contains(freedata, 'nick', 1) &gt; 0</programlisting> + </informalexample> + <para> + The + <function>score</function> + and + <function>contains</function> + functions are not part of built-in scalar function library. While + you could write your own custom scalar function to mimic their + behavior, it's more likely that you would want to use the actual + Oracle functions that are provided by Oracle when using the Oracle + Free Text functionality. + </para> + <para> + In addition to the normal steps outlined in the section to create and + install a function model (FunctionDefinitions.xmi), you will need to + extend the appropriate connector(s). + </para> + <itemizedlist> + <para>For example, to extend the Oracle Connector</para> + <listitem> + <para> + <emphasis>Required</emphasis> + - extend the OracleExecutionFactory and add SCORE and CONTAINS as + supported functions. For this example, we'll call the class + MyOracleExecutionFactory. Add the + <code>org.teiid.translator.Translator</code> + annotation to the class, e.g. + <code>@Translator(name="myoracle")</code> + </para> + </listitem> + <listitem> + <para>Optionally register new FunctionModifiers on the start of the + ExecutionFactory to handle translation of these functions. Given + that the syntax of these functions is same as other typical + functions, this probably isn't needed - the default translation + should work.</para> + </listitem> + <listitem> + <para> + Create a new translator jar containing your custom + ExecutionFactory. See <link linkend="translator_package">packaging</link> and <link linkend="translator_deploy">deployment</link> instructions for using the jar.</para> + </listitem> + </itemizedlist> + </sect1> + <sect1> + <title>Non-pushdown Support for User-Defined Functions</title> + <para>Non-pushdown support requires a Java function + that matches the metadata supplied in the FunctionDefinitions.xmi + file. You must create a Java method that contains the function’s + logic. This Java method should accept the necessary arguments, which + the Teiid System will pass to it at runtime, and function should + return the calculated or altered value.</para> + <sect2> + <title>Java Code</title> + <itemizedlist> + <para>Code Requirements</para> + <listitem> + <para>The java class containing the function method must be defined + public. + </para> + </listitem> + <listitem> + <para>The function method must be public and static.</para> + </listitem> + <listitem> + <para> + Number of input arguments must match the function metadata defined + in section + <link linkend="define_udf">Install user-defined functions</link> + </para> + </listitem> + <listitem> + <para> + Any exception can be thrown, but Teiid will rethrow the exception + as a + <classname>FunctionExecutionException</classname> + . + </para> + </listitem> + </itemizedlist> + <example> + <title>Sample code</title> + <programlisting><![CDATA[package org.something; + +public class TempConv { + + /** + * Converts the given Celsius temperature to Fahrenheit, and returns the + * value. + * @param doubleCelsiusTemp + * @return Fahrenheit + */ + public static Double celsiusToFahrenheit(Double doubleCelsiusTemp){ + if (doubleCelsiusTemp == null) { + return null; + } + return (doubleCelsiusTemp)*9/5 + 32; + } +}]]></programlisting> + </example> + </sect2> + <sect2> + <title>Post Code Activities</title> + <orderedlist> + <listitem> + <para> After coding the functions you should compile the Java + code into a Java Archive (JAR) file.</para> + </listitem> + <listitem> + <para>The JAR should be available in the classpath of Teiid - this + could be the server profile lib, or the deployers/teiid.deployer + directory depending upon your preference.</para> + </listitem> + </orderedlist> + </sect2> + </sect1> + <sect1> + <title>Installing user-defined functions</title> + <para> + Once a user-defined function model (FunctionDefinitions.xmi) has been + created in in the Designer Tool, it can be added to the VDB for use + by Teiid.</para> + </sect1> +</chapter> \ No newline at end of file Property changes on: trunk/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml ___________________________________________________________________ Name: svn:mime-type + text/plain 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-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/developer-guide/src/main/docbook/en-US/main.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -32,7 +32,7 @@ <bookinfo> <title>Teiid - Scalable Information Integration</title> - <subtitle>Teiid Translator and Resource Adapter Developer's Guide</subtitle> + <subtitle>Teiid Developer's Guide</subtitle> <releaseinfo>&versionNumber;</releaseinfo> <productnumber>&versionNumber;</productnumber> <issuenum>1</issuenum> @@ -48,10 +48,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/command-language.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/lob-support.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/jdbc-translator-examples.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" /> <xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Modified: trunk/documentation/reference/src/main/docbook/en-US/content/datatypes.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/content/datatypes.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/reference/src/main/docbook/en-US/content/datatypes.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -435,10 +435,7 @@ </row> <row> <entry> - yyyy-mm-dd hh:mm:ss.fffffffff - <footnote> - <para>fractional seconds are optional</para> - </footnote> + yyyy-mm-dd hh:mm:ss.[fff...] </entry> <entry>TIMESTAMP</entry> </row> @@ -474,10 +471,6 @@ </thead> <tbody> <row> - <entry>BOOLEAN</entry> - <entry>{b 'true'} or {b 'false'}</entry> - </row> - <row> <entry>DATE</entry> <entry>{d 'yyyy-mm-dd'}</entry> </row> @@ -488,18 +481,9 @@ <row> <entry>TIMESTAMP</entry> <entry> - {ts 'yyyy-mm-dd hh:mm:ss.fffffffff'} - <footnote> - <para>fractional seconds are optional</para> - </footnote> + {ts 'yyyy-mm-dd hh:mm:ss.[fff...]'} </entry> </row> - <row> - <entry>XML</entry> - <entry> - {x 'well-formed doc'} - </entry> - </row> </tbody> </tgroup> </table> Modified: trunk/documentation/reference/src/main/docbook/en-US/content/scalar_functions.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/content/scalar_functions.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/reference/src/main/docbook/en-US/content/scalar_functions.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -7,9 +7,7 @@ <link linkend="sql_support">SQL Support</link> and <link linkend="datatypes">Datatypes</link> - . In addition, Teiid provides the capability for - <link linkend="udfs">user defined functions or UDFs</link> - . + . In addition, Teiid provides the capability for user defined functions or UDFs. See the Developers Guide for adding UDFs. Once added UDFs may be called just like any other function. </para> <sect1 id="numeric_functions"> <title>Numeric Functions</title> @@ -767,7 +765,7 @@ </entry> <entry> <para>Provide the character for ASCII value x - <footnote label="1" id="nonAscii"><para>Non-ASCII range characters or integers used in these functions + <footnote id="nonAscii"><para>Non-ASCII range characters or integers used in these functions may produce different results or exceptions depending on where the function is evalutated (Teiid vs. source). Teiid's uses Java default int to char and char to int conversions, which operates over UTF16 values.</para></footnote> </para> @@ -803,6 +801,27 @@ </row> <row> <entry> + <para>ENCODE(x, encoding)</para> + </entry> + <entry> + <para>Return a clob from the blob with the given encoding. The builtin Java Charset<footnote id="charset"><para>See the <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/nio/charset/Charse... JavaDoc</ulink></para></footnote> names are valid values for encoding.</para> + </entry> + <entry> + <para>x is a blob, encoding is a string, and returns a clob</para> + </entry> + </row><row> + <entry> + <para>DECODE(x, encoding)</para> + </entry> + <entry> + <para>Return a blob from the clob with the given encoding. The builtin Java Charset<footnoteref linkend="charset"/> names are valid values for encoding.</para> + </entry> + <entry> + <para>x in a clob, encoding is a string, and returns a blob</para> + </entry> + </row> + <row> + <entry> <para>INITCAP(x)</para> </entry> <entry> @@ -920,7 +939,7 @@ </row> <row> <entry> - <para>(7.0+) QUERYSTRING(path [, expr [AS name] ...])</para> + <para>QUERYSTRING(path [, expr [AS name] ...])</para> </entry> <entry> <para>Returns a properly encoded query string appended to the given path. Null valued expressions are omitted, and a null path is treated as ''.</para> @@ -1783,8 +1802,7 @@ <itemizedlist> <listitem> <para>The keyColumn is expected to contain unique key - values. If the column contains duplicate values, an exception will be thrown. The - lookup caches can be flushed via the svcmgr.</para> + values. If the column contains duplicate values, an exception will be thrown.</para> </listitem> <listitem> <para>Cached lookup tables might consume significant memory. You @@ -1831,23 +1849,6 @@ </tbody> </tgroup> </informaltable> - <sect2> - <!-- TODO: move to administrative section --> - <title>Clearing the Cache</title> - <para>You can force a cache clearing by using the expert mode of - the svcmgr command, found under the \bin directory of your - Teiid server installation.</para> - <para>Launch the appropriate command:</para> - <orderedlist> - <listitem> - <para><command>svcmgr.cmd</command> (Windows)</para> - </listitem> - <listitem> - <para><command>svcmgr.sh</command> (Solaris or Linux)</para> - </listitem> - </orderedlist> - <para>From the command line enter ClearCodeTableCaches.</para> - </sect2> </sect1> <sect1> <title>System Functions</title> @@ -1927,420 +1928,113 @@ <sect1 id="xml_functions"> <title>XML Functions</title> <para>XML functions provide functionality for working with XML data. </para> - <informaltable frame="all"> - <tgroup cols="3"> - <thead> - <row> - <entry> - <para>Function</para> - </entry> - <entry> - <para>Definition</para> - </entry> - <entry> - <para>Datatype Constraint</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para><code>XPATHVALUE(doc, xpath)</code></para> - </entry> - <entry> - <para>Applies the XPATH query to the document and returns a - string value for the first matching result. An attempt is made to provide a - meaningful result for non-text nodes.</para> - </entry> - <entry> - <para>Doc in {string, clob, xml} and xpath. Return value is a string. - </para> - </entry> - </row> - <row> - <entry> - <para><code>(7.0+) XSLTRANSFORM(doc, xsl)</code></para> - </entry> - <entry> - <para>Applies an xsl stylesheet to the given document. If either argument is null, the result is null.</para> - </entry> - <entry> - <para>Doc, xsl in {string, clob, xml}. Return value is a clob. - </para> - </entry> - </row> - <row id="xmlquery"> - <entry> - <para><code>(7.0+) XMLQUERY([&lt;NSP&gt;] xquery [&lt;PASSING&gt;] [(NULL|EMPTY) ON EMPTY]]</code></para> - <para>PASSING:=<code>PASSING exp [AS name] [, exp [AS name]]*</code></para> - </entry> - <entry> - <para>Returns the XML result from evaluating the given xquery.</para> - <para>See XMLELEMENT for the definition of NSP - <link linkend="xmlnamespaces">XMLNAMESPACES</link>.</para><para>Namespaces may also be directly declared in the xquery prolog.</para> - <para id="passing">The optional PASSING clause is used to provide the context item, which does not have a name, and named global variable values. - If the xquery uses a context item and none is provided, then an exception will be raised. - Only one context item may be specified and should be an XML type. All non-context non-XML passing values will be converted to an appropriate XML type.</para> - <para>The ON EMPTY clause is used to specify the result when the evaluted sequence is empty. - EMPTY ON EMPTY, the default, returns an empty XML result. NULL ON EMPTY returns a null result.</para> - <para>See also <link linkend="xmltable">XMLTABLE</link></para> - <note><para>A technique known as document projection is used to reduce the memory footprint of the context item document. Only the parts of the document needed by the xquery will be loaded into memory.</para></note> - </entry> - <entry> - <para>xquery in string. Return value is xml. - </para> - </entry> - </row> - <row> - <entry> - <para><code>XMLELEMENT([NAME] name [, &lt;NSP&gt;] [, &lt;ATTR&gt;][, exp]*)</code></para> - <para>ATTR:=<code>XMLATTRIBUTES(exp [AS name] [, exp [AS name]]*)</code></para> - <para>NSP:=<code>XMLNAMESPACES((uri AS prefix | DEFAULT uri | NO DEFAULT))+</code></para> - </entry> - <entry> - <para>Returns an XML element with the given name and content. If the content value is of a type other than xml, - it will be escaped when added to the parent element. Null content values are ignored. - Whitespace in XML or the string values of the content is preserved, but no whitespace is added between content values.</para> - <para id="xmlnamespaces">XMLNAMESPACES is used provide namespace information. NO DEFAULT is equivalent to defining the default namespace to the null uri - xmlns="". - Only one DEFAULT or NO DEFAULT namespace item may be specified. The namespace prefixes xmlns and xml are reserved.</para> - <para>If a attribute name is not supplied, the expression must be a column reference, in which case the attribute name will be the column name. Null attribute values are ignored.</para> - <para>Example: with an xml_value of &lt;doc/&gt;, <code>xmlelement('elem', 1, '&lt;2/&gt;', xml_value)</code> - Returns: <code>&lt;elem&gt;1&amp;lt;2/&amp;gt;&lt;doc/&gt;&lt;elem/&gt;</code> - </para> - </entry> - <entry> - <para>Name, prefix are identifiers. uri is a string literal. exp can be any type. Return value is xml. - </para> - </entry> - </row> - <row> - <entry> - <para><code>XMLCONCAT(xml [, other]*)</code></para> - </entry> - <entry> - <para>Returns an XML with the concatination of the given xml types. If a value is null, it will be ignored. - </para> - </entry> - <entry> - <para>Name is an identifier. Content can be any type. Return value is xml. - </para> - </entry> - </row> - <row> - <entry> - <para><code>XMLFOREST(exp [AS name] [, &lt;NSP&gt;] [, exp [AS name]]*)</code></para> - </entry> - <entry> - <para>Returns an concatination of an XML element for each non-null expression exp. If a name is not supplied, the expression must be a column reference, in which case the element name will be the column name. - </para> - <para>See XMLELEMENT for the definition of NSP - <link linkend="xmlnamespaces">XMLNAMESPACES</link>.</para> - </entry> - <entry> - <para>Name is an identifier. Exp can be any type. Return value is xml. - </para> - </entry> - </row> - <row> - <entry> - <para><code>XMLCOMMENT(comment)</code></para> - </entry> - <entry> - <para>Returns an xml comment. - </para> - </entry> - <entry> - <para>Comment is a string. Return value is xml. - </para> - </entry> - </row> - <row> - <entry> - <para><code>XMLPI([NAME] name [, content])</code></para> - </entry> - <entry> - <para>Returns an xml processing instruction. - </para> - </entry> - <entry> - <para>Name is an identifier. Content is a string. Return value is xml. - </para> - </entry> - </row> - <row> - <entry id="xmlserialize"> - <para><code>XMLSERIALIZE([(DOCUMENT|CONTENT)] exp [AS datatype])</code></para> - </entry> - <entry> - <para>Returns a character type representation of the exp expression. - Only a character type (string, varchar, clob) may be specified as the datatype. CONTENT is the default. + <sect2> + <title>XMLCOMMENT</title> + <para>Returns an xml comment.</para> + <para><synopsis>XMLCOMMENT(comment)</synopsis></para> + <para>Comment is a string. Return value is xml.</para> + </sect2> + <sect2> + <title>XMLCONCAT</title> + <para>Returns an XML with the concatination of the given xml types.</para> + <para><synopsis>XMLCONCAT(content [, content]*)</synopsis></para> + <para>Content is xml. Return value is xml.</para> + <para>If a value is null, it will be ignored. If all values are null, null is returned.</para> + </sect2> + <sect2> + <title>XMLELEMENT</title> + <para>Returns an XML element with the given name and content.</para> + <para><synopsis>XMLELEMENT([NAME] name [, &lt;NSP&gt;] [, &lt;ATTR&gt;][, content]*)</synopsis></para> + <para><synopsis>ATTR:=XMLATTRIBUTES(exp [AS name] [, exp [AS name]]*)</synopsis></para> + <para><synopsis>NSP:=XMLNAMESPACES((uri AS prefix | DEFAULT uri | NO DEFAULT))+</synopsis></para> + <para>If the content value is of a type other than xml, it will be escaped when added to the parent element. Null content values are ignored. + Whitespace in XML or the string values of the content is preserved, but no whitespace is added between content values.</para> + <para id="xmlnamespaces">XMLNAMESPACES is used provide namespace information. NO DEFAULT is equivalent to defining the default namespace to the null uri - xmlns="". + Only one DEFAULT or NO DEFAULT namespace item may be specified. The namespace prefixes xmlns and xml are reserved.</para> + <para>If a attribute name is not supplied, the expression must be a column reference, in which case the attribute name will be the column name. Null attribute values are ignored.</para> + <para>Name, prefix are identifiers. uri is a string literal. content can be any type. Return value is xml. The return value is valid for use in places where a document is expected.</para> + <para><emphasis>Example</emphasis>: with an xml_value of &lt;doc/&gt;, <programlisting>xmlelement('elem', 1, '&lt;2/&gt;', xml_value)</programlisting> + Returns: <code>&lt;elem&gt;1&amp;lt;2/&amp;gt;&lt;doc/&gt;&lt;elem/&gt;</code> + </para> + </sect2> + <sect2> + <title>XMLFOREST</title> + <para>Returns an concatination of XML elements for each content item.</para> + <para><synopsis>XMLFOREST(content [AS name] [, &lt;NSP&gt;] [, content [AS name]]*)</synopsis></para> + <para>See XMLELEMENT for the definition of NSP - <link linkend="xmlnamespaces">XMLNAMESPACES</link>.</para> + <para>Name is an identifier. Content can be any type. Return value is xml.</para> + <para>If a name is not supplied for a content item, the expression must be a column reference, in which case the element name will be a partially escaped version of the column name.</para> + </sect2> + <sect2 id="xmlparse"> + <title>XMLPARSE</title> + <para>Returns an XML type representation of the string value expression.</para> + <para><synopsis>XMLPARSE((DOCUMENT|CONTENT) expr [WELLFORMED])</synopsis></para> + <para>expr in {string, clob, blob}. Return value is xml.</para> + <para>If DOCIMENT is specfied then the expression must have a single + root element and may or may not contain an XML declaration.</para> + <para> + If WELLFORMED is specified then validation is skipped; this is especially useful for CLOB and BLOB known to already be valid. + </para> + </sect2> + <sect2> + <title>XMLPI</title> + <para>Returns an xml processing instruction.</para> + <para><synopsis>XMLPI([NAME] name [, content])</synopsis></para> + <para>Name is an identifier. Content is a string. Return value is xml.</para> + </sect2> + <sect2 id="xmlquery"> + <title>XMLQUERY</title> + <para>Returns the XML result from evaluating the given xquery.</para> + <para><synopsis>XMLQUERY([&lt;NSP&gt;] xquery [&lt;PASSING&gt;] [(NULL|EMPTY) ON EMPTY]]</synopsis></para> + <para><synopsis>PASSING:=PASSING exp [AS name] [, exp [AS name]]*</synopsis></para> + <para>See XMLELEMENT for the definition of NSP - <link linkend="xmlnamespaces">XMLNAMESPACES</link>.</para><para>Namespaces may also be directly declared in the xquery prolog.</para> + <para id="passing">The optional PASSING clause is used to provide the context item, which does not have a name, and named global variable values. + If the xquery uses a context item and none is provided, then an exception will be raised. + Only one context item may be specified and should be an XML type. All non-context non-XML passing values will be converted to an appropriate XML type.</para> + <para>The ON EMPTY clause is used to specify the result when the evaluted sequence is empty. + EMPTY ON EMPTY, the default, returns an empty XML result. NULL ON EMPTY returns a null result.</para> + <para>xquery in string. Return value is xml.</para> + <para>XMLQUERY is part of the SQL/XML 2006 specification.</para> + <para>See also <link linkend="xmltable">XMLTABLE</link></para> + <note><para>A technique known as document projection is used to reduce the memory footprint of the context item document. Only the parts of the document needed by the xquery will be loaded into memory.</para></note> + + </sect2> + <sect2 id="xmlserialize"> + <title>XMLSERIALIZE</title> + <para>Returns a character type representation of the xml expression.</para> + <para><synopsis>XMLSERIALIZE([(DOCUMENT|CONTENT)] xml [AS datatype])</synopsis></para> + <para>Return value mathces datatype.</para> + <para>Only a character type (string, varchar, clob) may be specified as the datatype. CONTENT is the default. If DOCUMENT is specified and the xml is not a valid document or fragment, then an exception is raised. </para> - </entry> - <entry> - <para>Exp is xml. Return value mathces datatype. - </para> - </entry> - </row> - <row> - <entry id="xmlparse"> - <para><code>XMLPARSE((DOCUMENT|CONTENT) exp [WELLFORMED])</code></para> - </entry> - <entry> - <para>Returns an XML type representation of the exp expression. If DOCIMENT is specfied then the expression must have a single - root element and may or may not contain an XML declaration.</para> - <para> - If WELLFORMED is specified then validation is skipped; this is especially useful for CLOB and BLOB known to already be valid. - </para> - </entry> - <entry> - <para>Exp in {string, clob, blob}. Return value is xml. - </para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> + </sect2> + <sect2> + <title>XSLTRANSFORM</title> + <para>Applies an XSL stylesheet to the given document.</para> + <para><synopsis>XSLTRANSFORM(doc, xsl)</synopsis></para> + <para>Doc, xsl in {string, clob, xml}. Return value is a clob.</para> + <para>If either argument is null, the result is null.</para> + </sect2> + <sect2> + <title>XPATHVALUE</title> + <para>Applies the XPATH expression to the document and returns a + string value for the first matching result.</para> + <para><synopsis>XPATHVALUE(doc, xpath)</synopsis></para> + <para>Doc and xpath in {string, clob, xml}. Return value is a string.</para> + <para>An attempt is made to provide a meaningful result for non-text nodes.</para> + </sect2> </sect1> <sect1> <title>Security Functions</title> <para>Security functions provide the ability to interact with the security system.</para> - <informaltable frame="all"> - <tgroup cols="3"> - <thead> - <row> - <entry> - <para>Function</para> - </entry> - <entry> - <para>Definition</para> - </entry> - <entry> - <para>Datatype Constraint</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para><code>hasRole(roleName)</code> - </para> - </entry> - <entry> - <para>Whether the current caller has the role - roleName.</para> - </entry> - <entry> - <para>roleName must be a string, the return - type is Boolean.</para> - </entry> - </row> - <row> - <entry> - <para><code>hasRole(roleType, roleName)</code> - </para> - </entry> - <entry> - <para>Whether the current caller has the role - roleName of roleType. See the 1 argument version above.</para> - </entry> - <entry> - <para>roleType must be 'data' and roleName must be a string, the return - type is Boolean.</para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - <sect1 id="udfs"> - <title>User Defined Functions</title> - <para>If you need to extends Teiid's scalar function library, - then Teiid provides a means to define custom scalar functions or - User Defined Functions(UDF). The following steps need to be taken in - creating a UDF.</para> - <sect2 id="define_udf"> - <title>UDF Definition</title> - <para>The FunctionDefinition.xmi file provides metadata to the - query engine on User Defined Functions. See our product document on - "Creating User-defined Functions" for a more extensive reference on - creating that file through the Designer Tool.</para> - <itemizedlist> - <para>The following are used to define a UDF.</para> - <listitem> - <para> - <emphasis>Function Name</emphasis> - When you create the function name, keep these requirements in - mind: - <itemizedlist> - <listitem> - <para>You cannot use a reserved word, which includes - existing Teiid System function names.  You cannot - overload existing Teiid System functions.</para> - </listitem> - <listitem> - <para>The function name must be unique among user-defined - functions for the number of arguments.  You can use the - same function name for different numbers of types of - arguments.  Hence, you can overload your user-defined - functions.</para> - </listitem> - <listitem> - <para>The function name can only contain letters, - numbers, and the underscore (_).  Your function name must - start with a letter.</para> - </listitem> - <listitem> - <para>The function name cannot exceed 128 characters. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - <listitem> - <para> - <emphasis>Input Parameters</emphasis> - - defines a type specific signature list. All arguments are considered - required.</para> - </listitem> - <listitem> - <para> - <emphasis>Return Type</emphasis> - the expected type of the returned scalar value. - </para> - </listitem> - <listitem> - <para> - <emphasis>Pushdown</emphasis> - - can be one of REQUIRED, NEVER, ALLOWED. Indicates the expected - pushdown behavior. If NEVER or ALLOWED are specified then a Java - implementation of the function should be supplied.</para> - </listitem> - <listitem> - <para> - <emphasis>invocationClass/invocationMethod - </emphasis> - - optional properties indicating the static method to invoke when - the UDF is not pushed down. - </para> - </listitem> - <listitem> - <para><emphasis>Deterministic</emphasis> - if the method will always return the same result for the same input parameters. - </para> - </listitem> - </itemizedlist> - </sect2> <sect2> - <title>Source Supported UDF</title> - <para>While Teiid provides an extensive scalar function - library, it contains only those functions that can be evaluated - within the query engine. In many circumstances, especially for - performance, a user defined function allows for calling a source - specific function.</para> - <para>For example, suppose you want to use the Oracle-specific functions score and contains: - </para> - <informalexample> - <programlisting>SELECT score(1), ID, FREEDATA FROM Docs WHERE contains(freedata, 'nick', 1) &gt; 0</programlisting> - </informalexample> - <para> - The - <function>score</function> - and - <function>contains</function> - functions are not part of built-in scalar function library. While - you could write your own custom scalar function to mimic their - behavior, it's more likely that you would want to use the actual - Oracle functions that are provided by Oracle when using the Oracle - Free Text functionality.</para> - <para> - In addition to the normal steps outlined in the section to create and install a function model (FunctionDefinitions.xmi), you will need to extend the appropriate connector(s). - </para> - <itemizedlist> - <para>For example, to extend the Oracle Connector</para> - <listitem> - <para><emphasis>Required</emphasis> - extend OracleCapabilities and set up SCORE and CONTAINS as supported functions (this lets Teiid know that the connector can accept these functions).</para> - </listitem> - <listitem> - <para>Optionally extend the OracleSQLTranslator to insert new FunctionModifiers to handle translation of these functions. Given that the syntax of these functions is same as other typical functions, this probably isn't needed - the default translation should work.</para> - </listitem> - <listitem> - <para>Create a new connector - The easiest way is to copy JDBC connector rar file from the distribution and modify the "ra.xml" file. Change the capabilities class (to use the extended version) and possibly the translation class (if that was extended for b. Also, include a new jar of your changes above in the same rar file. Rename the RAR file to different name to differentiate from original JDBC rar file.</para> - </listitem> - </itemizedlist> + <title>HASROLE</title> + <para>Whether the current caller has the role roleName.</para> + <para><synopsis>hasRole([roleType,] roleName)</synopsis></para> + <para>roleName must be a string, the return type is boolean.</para> + <para>The two argument form is provided for backwards compatibility. roleType is a string and must be 'data'</para> </sect2> - <sect2> - <title>Non-pushdown Support for User-Defined Functions</title> - <para>Non-pushdown support requires a Java function - that matches the metadata supplied in the FunctionDefinitions.xmi - file. You must create a Java method that contains the function’s - logic. This Java method should accept the necessary arguments, which - the Teiid System will pass to it at runtime, and function should - return the calculated or altered value.</para> - <sect3> - <title>Java Code</title> - <itemizedlist> - <para>Code Requirements</para> - <listitem> - <para>The java class containing the function method must be defined public. - </para> - </listitem> - <listitem> - <para>The function method must be public and static.</para> - </listitem> - <listitem> - <para> - Number of input arguments must match the function metadata defined in section - <link linkend="define_udf">Install user-defined functions</link> - </para> - </listitem> - <listitem> - <para>Any exception can be thrown, but Teiid will rethrow the exception as a <classname>FunctionExecutionException</classname>.</para> - </listitem> - </itemizedlist> - <example> - <title>Sample code</title> - <programlisting><![CDATA[package userdefinedfunctions; - -public class TempConv { - - /** - * Converts the given Celsius temperature to Fahrenheit, and returns the - * value. - * @param doubleCelsiusTemp - * @return Fahrenheit - */ - public static Double celsiusToFahrenheit(Double doubleCelsiusTemp){ - if (doubleCelsiusTemp == null) { - return null; - } - return (doubleCelsiusTemp)*9/5 + 32; - } -}]]></programlisting> - </example> - </sect3> - <sect3> - <title>Post Code Activities</title> - <orderedlist> - <listitem> - <para> After coding the functions you should compile the Java - code into a Java Archive (JAR) file, so that you can add it to - the Teiid System as an Extension Module.</para> - </listitem> - <listitem> - <para> After adding the jar file as an extension module, the - name of jar file need to be added to user defined functions - classpath using Console tool.</para> - </listitem> - </orderedlist> - </sect3> - </sect2> - <sect2> - <title>Installing user-defined functions</title> - <para> - Once a user-defined function model (FunctionDefinitions.xmi) has been - created in in the Designer Tool, it should be installed by replacing - the existing version under the Extension Modules (for the Enterprise - product this will be done through the Console). That will allow the - query engine to know about and use functions</para> - </sect2> </sect1> <sect1 id="nondeterministic_functions"> <title>Nondeterministic Function Handling</title> Modified: trunk/documentation/reference/src/main/docbook/en-US/content/sql_support.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/content/sql_support.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/reference/src/main/docbook/en-US/content/sql_support.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -724,7 +724,7 @@ </note> <sect3 id="nested_table"> <title>Nested Table Reference</title> - <para>(7.0+) Nested tables may appear in the FROM clause with the TABLE + <para>Nested tables may appear in the FROM clause with the TABLE keyword. They are an alternative to using a view with normal join semantics. The columns projected from the command contained in the nested table may be used just as any of the other FROM clause projected columns in join criteria, the where clause, etc. @@ -748,7 +748,7 @@ </sect3> <sect3 id="texttable"> <title>TEXTTABLE</title> - <para>(7.0+) The TEXTTABLE funciton processes character input to produce tabular ouptut. It supports both fixed and delimited file format parsing. + <para>The TEXTTABLE funciton processes character input to produce tabular ouptut. It supports both fixed and delimited file format parsing. The function itself defines what columns it projects. The TEXTTABLE function is implicitly a nested table and may be correlated to preceeding FROM clause entries. </para> @@ -826,7 +826,7 @@ </sect3> <sect3 id="xmltable"> <title>XMLTABLE</title> - <para>(7.0+) The XMLTABLE funciton uses XQuery to produce tabular ouptut. + <para>The XMLTABLE funciton uses XQuery to produce tabular ouptut. The XMLTABLE function is implicitly a nested table and may be correlated to preceeding FROM clause entries. XMLTABLE is part of the SQL/XML 2006 specification. </para> <para> Modified: trunk/documentation/reference/src/main/docbook/en-US/content/translators.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/content/translators.xml 2010-06-16 19:02:47 UTC (rev 2237) +++ trunk/documentation/reference/src/main/docbook/en-US/content/translators.xml 2010-06-17 13:44:55 UTC (rev 2238) @@ -266,12 +266,12 @@ </row> <row> <entry>widenUnsignedTypes</entry> -<entry>(7.0+) true to convert unsigned types to the next widest type. For example SQL Server reports tinyint as an unsigned type. With this option enabled, tinyint would be imported as a short instead of a byte.</entry> +<entry>true to convert unsigned types to the next widest type. For example SQL Server reports tinyint as an unsigned type. With this option enabled, tinyint would be imported as a short instead of a byte.</entry> <entry>true</entry> </row> <row> <entry>quoteNameInSource</entry> -<entry>(7.0+) false will override the default and direct Teiid to create source queries using unquoted identifiers.</entry> +<entry>false will override the default and direct Teiid to create source queries using unquoted identifiers.</entry> <entry>true</entry> </row> </tbody>