[teiid-commits] teiid SVN: r2219 - in trunk: documentation/connector-developer-guide/src/main/docbook/en-US and 1 other directories.

Author: rareddy Date: 2010-06-10 19:14:14 -0400 (Thu, 10 Jun 2010) New Revision: 2219 Added: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml Removed: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml Modified: trunk/api/src/main/java/org/teiid/resource/spi/BasicConnection.java trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnection.java trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnectionFactory.java trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-a.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml Log: TEIID-315: Updating the translator developers guide. Added a section for developing the "resource adapters" into the same guide. Also made few changes to adapter api, to better support XA and security. These changes do not modify any behaviour. Modified: trunk/api/src/main/java/org/teiid/resource/spi/BasicConnection.java =================================================================== --- trunk/api/src/main/java/org/teiid/resource/spi/BasicConnection.java 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/api/src/main/java/org/teiid/resource/spi/BasicConnection.java 2010-06-10 23:14:14 UTC (rev 2219) @@ -28,6 +28,7 @@ import javax.resource.cci.LocalTransaction; import javax.resource.cci.ResultSetInfo; import javax.resource.spi.ManagedConnection; +import javax.transaction.xa.XAResource; public abstract class BasicConnection implements Connection { @@ -51,6 +52,10 @@ throw new ResourceException("This operation not supported"); //$NON-NLS-1$ } + public XAResource getXAResource() throws ResourceException { + return null; + } + /** * Tests the connection to see if it is still valid. * @return Modified: trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnection.java =================================================================== --- trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnection.java 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnection.java 2010-06-10 23:14:14 UTC (rev 2219) @@ -107,7 +107,7 @@ @Override public XAResource getXAResource() throws ResourceException { - return null; + return this.physicalConnection.getXAResource(); } @Override Modified: trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnectionFactory.java =================================================================== --- trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnectionFactory.java 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnectionFactory.java 2010-06-10 23:14:14 UTC (rev 2219) @@ -57,7 +57,10 @@ @Override public ManagedConnection createManagedConnection(Subject arg0, ConnectionRequestInfo arg1) throws ResourceException { ConnectionRequestInfoWrapper criw = (ConnectionRequestInfoWrapper)arg1; - return new BasicManagedConnection(criw.cf.getConnection()); + ConnectionContext.setSubject(arg0); + BasicConnection connection = criw.cf.getConnection(); + ConnectionContext.setSubject(null); + return new BasicManagedConnection(connection); } @Override Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -32,7 +32,7 @@ <bookinfo> <title>Teiid - Scalable Information Integration</title> - <subtitle>Teiid Connector Developer's Guide</subtitle> + <subtitle>Teiid Translator and Resource Adapter Developer's Guide</subtitle> <releaseinfo>&versionNumber;</releaseinfo> <productnumber>&versionNumber;</productnumber> <issuenum>1</issuenum> @@ -46,10 +46,9 @@ <toc/> <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/connector-deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/connection-pooling.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/examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-a.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -1,45 +1,58 @@ <appendix id="appendix_a"> - <title>Connector Type Definition Template</title> - <para> This appendix contains an example of the Connector Type Definition file that can be used as a template - when creating a new Connector Type Definition.</para> + <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"?> -<ConfigurationDocument> - <Header> - <ApplicationCreatedBy>Connector Development Kit</ApplicationCreatedBy> - <ApplicationVersionCreatedBy>4.0:1681</ApplicationVersionCreatedBy> - <UserCreatedBy>MetaMatrixAdmin</UserCreatedBy> - <DocumentTypeVersion>1.0</DocumentTypeVersion> - <MetaMatrixSystemVersion>4.0</MetaMatrixSystemVersion> - <Time>2008-01-30T15:22:05.296-06:00</Time> - </Header> - <ComponentTypes> - <ComponentType Name="My Connector" ComponentTypeCode="2" Deployable="true" Deprecated="false" Monitorable="false" SuperComponentType="Connector" ParentComponentType="Connectors"> - <!-- Required by Connector API --> - <ComponentTypeDefn Deprecated="false"> - <PropertyDefinition Name="ConnectorClass" DisplayName="Connector Class" ShortDescription="" DefaultValue="com.mycode.Connector" IsRequired="true" IsMasked="false" IsModifiable="false" /> - </ComponentTypeDefn> - <ComponentTypeDefn Deprecated="false"> - <PropertyDefinition Name="ConnectorClassPath" DisplayName="Class Path" ShortDescription="" DefaultValue="extensionjar:mycode.jar" IsRequired="true" IsMasked="false" /> - </ComponentTypeDefn> - <!-- Example properties - replace with custom properties --> - <ComponentTypeDefn Deprecated="false"> - <PropertyDefinition Name="ExampleOptional" DisplayName="Example Optional Property" ShortDescription="This property is optional due to not being marked as IsRequired" IsMasked="false" /> - </ComponentTypeDefn> - <ComponentTypeDefn Deprecated="false"> - <PropertyDefinition Name="ExampleDefaultValue" DisplayName="Example Default Value Property" ShortDescription="This property has a default value" DefaultValue="Default value" IsRequired="true" IsMasked="false" /> - </ComponentTypeDefn> - <ComponentTypeDefn Deprecated="false"> - <PropertyDefinition Name="ExampleEncrypted" DisplayName="Example Encrypted Property" ShortDescription="This property is encrypted in storage due to Masked=true" IsRequired="true" IsMasked="true" /> - </ComponentTypeDefn> +<connector xmlns="http://java.sun.com/xml/ns/j2ee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee + http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" + version="1.5"> - <ChangeHistory> - <Property Name="LastChangedBy">ConfigurationStartup</Property> - <Property Name="CreatedBy">ConfigurationStartup</Property> - </ChangeHistory> - </ComponentType> - </ComponentTypes> -</ConfigurationDocument> + <vendor-name>${comapany-name}</vendor-name> + <eis-type>${type-of-connector}</eis-type> + <resourceadapter-version>1.0</resourceadapter-version> + <license> + <description> + ${license text} + </description> + <license-required>true</license-required> + </license> + <resourceadapter> + <resourceadapter-class>org.teiid.resource.spi.BasicResourceAdapter</resourceadapter-class> + + <outbound-resourceadapter> + <connection-definition> + <managedconnectionfactory-class>${connection-factory-class}</managedconnectionfactory-class> + + <!-- 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> + <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> + + <!-- use the below as is if you used the Connection Factory interface --> + + <connectionfactory-interface>javax.resource.cci.ConnectionFactory</connectionfactory-interface> + <connectionfactory-impl-class>org.teiid.resource.spi.WrappedConnectionFactory</connectionfactory-impl-class> + <connection-interface>javax.resource.cci.Connection</connection-interface> + <connection-impl-class>org.teiid.resource.spi.WrappedConnection</connection-impl-class> + + </connection-definition> + + <transaction-support>NoTransaction</transaction-support> + + <authentication-mechanism> + <authentication-mechanism-type>BasicPassword</authentication-mechanism-type> + <credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface> + </authentication-mechanism> + <reauthentication-support>false</reauthentication-support> + </outbound-resourceadapter> + </resourceadapter> +</connector> ]]></programlisting> </appendix> \ No newline at end of file Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -8,28 +8,34 @@ <sect1> <title>Language Interfaces</title> <para> - Teiid sends commands to your connector in object form. The interfaces - for these objects are all defined in the org.teiid.connector.language + 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 connector. However, it is possible - to notify Teiid that your connector can only accept certain kinds of - commands via the ConnectorCapabilities class. See the section on using - <link linkend="connector_capabilities">Connector Capabilities</link> + 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 ILanguageObject interface. + <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 connector are in the form of these - language trees, where the root of the tree is a subclass of ICommand. - ICommand has several sub-interfaces, namely: IQueryCommand, IInsert, IUpdate, - IDelete, IBatchedUpdate, and IProcedure.   - 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> + <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> @@ -43,45 +49,44 @@ <itemizedlist> <listitem> <para> - <code>IExpression</code> + <code>Expression</code> – base expression interface </para> </listitem> <listitem> <para> - <code>IElement</code> + <code>Element</code> – represents an element in the data source </para> </listitem> <listitem> <para> - <code>ILiteral</code> + <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>IFunction</code> - – represents a scalar function with parameters that are also - IExpressions + <code>Function</code> + – represents a scalar function with parameters that are also Expressions </para> </listitem> <listitem> <para> - <code>IAggregate</code> + <code>Aggregate</code> – represents an aggregate function which holds a single expression </para> </listitem> <listitem> <para> - <code>IScalarSubquery</code> + <code>ScalarSubquery</code> – represents a subquery that returns a single value </para> </listitem> <listitem> <para> - <code>ISearchedCaseExpression</code> + <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. @@ -90,110 +95,111 @@ </itemizedlist> </sect2> <sect2> - <title>Criteria</title> + <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>ICriteria</code> – the base criteria interface</para></listitem> - <listitem><para><code>ILogicalCriteria</code> – used to logically combine other criteria</para></listitem> - <listitem><para><code>INotCriteria</code> – used to NOT another criteria</para></listitem> - <listitem><para><code>ICompoundCriteria</code> – used to combine other criteria via AND or OR</para></listitem> - <listitem><para><code>IPredicateCriteria</code> – a predicate that evaluates to true, false, or unknown</para></listitem> - <listitem><para><code>ISubuqeryCompareCriteria</code> – represents a comparison criteria with a subquery including a quantifier such as SOME or ALL</para></listitem> - <listitem><para><code>ICompareCriteria</code> – represents a comparison criteria with =, &gt;, &lt;, etc.</para></listitem> - <listitem><para><code>IBaseInCriteria</code> – base class for an IN criteria</para></listitem> - <listitem><para><code>IInCriteria</code> – represents an IN criteria that has a set of expressions for values</para></listitem> - <listitem><para><code>ISubqueryInCriteria</code> – represents an IN criteria that uses a subquery to produce the value set</para></listitem> - <listitem><para><code>IIsNullCriteria</code> – represents an IS NULL criteria</para></listitem> - <listitem><para><code>IExistsCriteria</code> – represents an EXISTS criteria that determines whether a subquery will return any values</para></listitem> - <listitem><para><code>ILikeCriteria</code> – represents a LIKE criteria that compares string values</para></listitem> + <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 IFromItems.  Each IFomItem can - either represent a group or a join between two other IFromItems.  This - allows joins to be composed into a join tree.</para> + <para>The FROM clause contains a list of <emphasis>TableReference</emphasis>.  </para> <itemizedlist> - <listitem><para><code>IGroup</code> – represents a single group</para></listitem> - <listitem><para><code>IJoin</code> – has a left and right <code>IFromItem</code> and information on the join between the items</para></listitem> - <listitem><para><code>IInlineView</code> – represents a group defined by an inline <code>IQueryCommand</code></para></listitem> + <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 IFromItems is 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 IJoins 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 - ConnectorCapability.useAnsiJoin return true. See <link linkend="command_form_capabilities">Command Form Capabilities</link> for more.</para> + <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>IQueryCommand Structure</title> - <para>IQueryCommand (refered to in SQL as a Query Expression) is the base for both queries and set queries. It may optionally take an IOrderBy (representing a SQL ORDER BY clause) and a ILimit (represent a SQL LIMIT clause)</para> - </sect2> - <sect2> - <title>IQuery Structure</title> - - <para>Each IQuery will have an ISelect describing the expressions - (typically elements) being selected and an IFrom specifying the group - or groups being selected from, along with any join information.  The - IQuery may optionally also supply an ICriteria (representing a SQL - WHERE clause), an IGroupBy (representing a SQL GROUP BY clause), an - an ICriteria (representing a SQL HAVING clause).</para> + <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>ISetQuery Structure</title> + <title>Select Structure</title> - <para>An ISetQuery represents on of the SQL set operations (UNION, - INTERSECT, EXCEPT) on two IQueryCommands. The all flag may be set to - indicate UNION ALL (currently INTERSECT and EXCEPT ALL are not allowed - in Teiid)</para> + <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>IInsert Structure</title> + <title>Insert Structure</title> - <para>Each IInsert will have a single IGroup specifying the group being - inserted into.  It will also a list of - IElements specifying the columns of the IGroup that are being inserted - into and an IInsertValueSource, which will either be a list of IExpression (IInsertExpressionValueSource) or an IQueryCommand.</para> + <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>IUpdate Structure</title> + <title>Update Structure</title> - <para>Each IUpdate will have a single IGroup specifying the group being - updated.  The ISetClauseList contains ISetClause entries that specify - IElement and IExpression pairs for the update. - The IUpdate may optionally provide a - criteria specifying which rows should be updated.</para> + <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>IDelete Structure</title> + <title>Delete Structure</title> - <para>Each IDelete will have a single IGroup specifying the group being - deleted from. It may also optionally have a criteria specifying which - rows should be deleted.  </para> + <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>IProcedure Structure</title> + <title>Call Structure</title> - <para>Each IProcedure has zero or more IParameter objects. The - IParameter objects describe the input parameters, the output result + <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>IBatchedUpdate Structure </title> - - <para>Each IBatchedUpdate has a list of ICommand objects (which must be - an IInsert, IUpdate, or IDelete) that compose the batch. </para> + <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> @@ -203,36 +209,36 @@ <sect2> <title>Data Types</title> - <para>The Connector API contains an interface TypeFacility that defines data types and provides value translation facilities.  </para> + <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>This ConnectorEnvironment (provided by Teiid on connector start) - is a factory to obtain a TypeFacility instance for the connector using - the getTypeFacility() method. + <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 - IExpression instances define a data type based on this set of types. -  These constants are often needed in understanding or creating - language interfaces.</para> + <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 connectors that support a fuller set of capabilities (those + <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 use the ConnectorEnvironment - to get a reference to the ILanguageFactory instance for your - connector.  This interface is a factory that can be used to create new + <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 ICriteria objects are - provided in the LanguageUtil class.  This class has methods to combine - ICriteria with AND or to break an ICriteria apart based on AND + <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 connector can implement.</para> + into individual filters that your translator can implement.</para> </sect2> </sect1> @@ -241,55 +247,50 @@ <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.  </para> - <para>Connectors can access runtime metadata by using the interfaces - defined in org.teiid.connector.metadata.runtime.  This package defines - interfaces representing a MetadataID, a MetadataObject, and ways to - navigate those IDs and objects.</para> + 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>One language interface, IMetadataReference describes whether a language object has a reference to a MetadataObject.  The following interfaces extend IMetadataReference:</para> + <para>All the language objects extend <emphasis>AbstractMetadataRecord</emphasis> class</para> <itemizedlist> - <listitem><para>IElement</para> - returns an Element MetadataObject</listitem> - <listitem><para>IGroup</para> - returns a Group MetadataObject</listitem> - <listitem><para>IProcedure</para> - returns a Procedure MetadataObject</listitem> - <listitem><para>IParameter</para> - returns a Parameter MetadataObject</listitem> + <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 MetadataObject has been obtained, it is possible to use it metadata about that object or to find other related or objects.</para> + <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>As mentioned in the previous section, a MetadataID is obtained - from one of the language objects. That MetadataID can then be used - directly to obtain information about the ID, such as the full name or - short name.  </para> - <para>The RuntimeMetadata interface is passed in for the creation of an Execution. It provides the ability to look up - MetadataObjects based on their fully qualified names in the VDB. There are several kinds of - MetadataObjects and they can be used to find more information about - the object in runtime metadata.  </para> - <para>Currently, only a subset of the most commonly used runtime - metadata is available through these interfaces. In the future, more - complete information will be available.</para> + <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 MetadataObject Properties Example</emphasis></para> + <para><emphasis>Obtaining Metadata Properties Example</emphasis></para> - <para>The process of getting an element's properties is sometimes needed for connector development.  For example to get the NameInSource property or all extension properties:</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 Group metadata from an IGroup is straight-forward -IGroup igroup = ... //some group on a command -Group group = igroup.getMetadataObject(); +//getting the Table metadata from an Table is straight-forward +Table table = runtimeMetadata.getTable("table-name"); +String contextName = table.getNameInSource(); -//we could also use the runtime metadata -RuntimeMetadata rm = ... //Obtained from the creation of the Execution - -group = rm.getGroup("fully.qualified.name"); -String contextName = group.getNameInSource(); - //The props will contain extension properties -Properties props = group.getProperties(); +Properties props = table.getProperties(); ]]></programlisting> </sect2> @@ -300,8 +301,8 @@ <sect2> <title>Framework</title> - <para>The Connector API provides a language visitor framework in the - org.teiid.connector.visitor.framework package.   The framework + <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> @@ -313,7 +314,7 @@ 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 LanguageObjectVisitor class defines the visit methods + <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 @@ -321,31 +322,31 @@ AbstractLanguageVisitor.  The AbstractLanguageVisitor is just a visitor shell – it performs no actions when visiting nodes and does not provide any iteration.</para> - <para>The HierarchyVisitor provides the basic code for walking a - language object tree.  The HierarchyVisitor performs no action as it + <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 connector wants to provide a custom iteration that walks the +  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 DelegatingHierarchyVisitor is a special subclass of the + <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 - DelegatingHierarchyVisitor to aid in executing pre- and post-order + <emphasis>DelegatingHierarchyVisitor</emphasis> to aid in executing pre- and post-order visitors.   </para> </sect2> <sect2> <title>Provided Visitors</title> - <para>The SQLStringVisitor is a special visitor that can traverse a + <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 SQLStringVisitor does not use the HierarchyVisitor + 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 CollectorVisitor is a handy utility to collect all language + <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> @@ -358,7 +359,7 @@ <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 - visit(IElement) method.  Collect any state in local variables and + <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 - @@ -367,7 +368,7 @@ DelegatingHierarchyVisitor:</para> <programlisting><![CDATA[ // Get object tree -ILanguageObject objectTree = … +LanguageObject objectTree = … // Create your visitor initialize as necessary MyVisitor visitor = new MyVisitor(); @@ -380,32 +381,27 @@ ]]></programlisting> </sect2> </sect1> - <sect1 id="connector_capabilities"> - <title>Connector Capabilities</title> - <para>All connectors must return a ConnectorCapabilities class from the - <code>Connection.getCapabilities()</code> or <code>Connector.getCapabilities()</code> method. This class is used by the - Connector Manager to determine what kinds of commands the connector is - capable of executing. A basic implementation of the - ConnectorCapabilities interface is supplied at - BasicConnectorCapabilities. This - capabilities class specifies that the connector does not support any capability. You should extend - this class and override the necessary methods to specify which - capabilities your connector supports.  </para> + <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 connector, you should return them via - <code>Connector.getCapabilities()</code> - since the engine will cache them for reuse by all connections to the - connector. Capabilities returned by the connection will only be cached for the duration of the user request. + 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 ConnectorCapabilities class.</para> + <para>The following table lists the capabilities that can be specified in the <emphasis>ExecutionFactory</emphasis> class.</para> <table frame='all'> - <title>Available Connector Capabilities</title> + <title>Available Capabilities</title> <tgroup cols='3' align='left' colsep='1' rowsep='1'> <colspec colname='c1' colwidth="1.5*" /> <colspec colname='c2' colwidth="1*" /> @@ -432,7 +428,7 @@ <para /> </entry> <entry> - <para>Connector can support SELECT DISTINCT in queries.</para> + <para>Translator can support SELECT DISTINCT in queries.</para> </entry> </row> <row> @@ -443,44 +439,30 @@ <para /> </entry> <entry> - <para>Connector can support SELECT of more than just element references.</para> + <para>Translator can support SELECT of more than just column references.</para> </entry> </row> <row> <entry> - <para>AliasedGroup</para> + <para>AliasedTable</para> </entry> <entry> <para /> </entry> <entry> - <para>Connector can support groups in the FROM clause that have an alias. + <para>Translator can support Tables in the FROM clause that have an alias. </para> </entry> </row> <row> <entry> - <para>SupportedJoinCriteria</para> - </entry> - <entry> - <para>At least one of the join type supports.</para> - </entry> - <entry> - <para>Returns one of the SupportedJoinCriteria enum types: ANY, THETA, - EQUI, KEY. KEY is the most restrictive, indicating that the source - only supports equi-join criteria specified on the primary key of at - least one of the tables in join.</para> - </entry> - </row> - <row> - <entry> <para>InnerJoins</para> </entry> <entry> <para/> </entry> <entry> - <para>Connector can support inner and cross joins</para> + <para>Translator can support inner and cross joins</para> </entry> </row> <row> @@ -491,8 +473,8 @@ <para>AliasedGroups and at least on of the join type supports.</para> </entry> <entry> - <para>Connector can support a self join between two aliased versions of the - same group.</para> + <para>Translator can support a self join between two aliased versions of the + same Table.</para> </entry> </row> <row> @@ -503,7 +485,7 @@ <para/> </entry> <entry> - <para>Connector can support LEFT and RIGHT OUTER JOIN.</para> + <para>Translator can support LEFT and RIGHT OUTER JOIN.</para> </entry> </row> <row> @@ -514,7 +496,7 @@ <para/> </entry> <entry> - <para>Connector can support FULL OUTER JOIN.</para> + <para>Translator can support FULL OUTER JOIN.</para> </entry> </row> <row> @@ -522,10 +504,10 @@ <para>InlineViews</para> </entry> <entry> - <para>AliasedGroup</para> + <para>AliasedTable</para> </entry> <entry> - <para>Connector can support a named subquery in the FROM clause.</para> + <para>Translator can support a named subquery in the FROM clause.</para> </entry> </row> <row> @@ -547,7 +529,7 @@ <para/> </entry> <entry> - <para>Connector can support comparison criteria with the operator "=”.</para> + <para>Translator can support comparison criteria with the operator "=”.</para> </entry> </row> <row> @@ -558,7 +540,7 @@ <para/> </entry> <entry> - <para>Connector can support comparison criteria with the operator "&gt;” or "&lt;".</para> + <para>Translator can support comparison criteria with the operator "&gt;” or "&lt;".</para> </entry> </row> <row> @@ -569,7 +551,7 @@ <para/> </entry> <entry> - <para>Connector can support LIKE criteria.</para> + <para>Translator can support LIKE criteria.</para> </entry> </row> <row> @@ -580,7 +562,7 @@ <para>LikeCriteria</para> </entry> <entry> - <para>Connector can support LIKE criteria with an ESCAPE character clause.</para> + <para>Translator can support LIKE criteria with an ESCAPE character clause.</para> </entry> </row> <row> @@ -588,10 +570,10 @@ <para>InCriteria</para> </entry> <entry> - <para/> + <para>MaxInCriteria</para> </entry> <entry> - <para>Connector can support IN predicate criteria.</para> + <para>Translator can support IN predicate criteria.</para> </entry> </row> <row> @@ -602,7 +584,7 @@ <para/> </entry> <entry> - <para>Connector can support IN predicate criteria where values are supplied by a + <para>Translator can support IN predicate criteria where values are supplied by a subquery.</para> </entry> </row> @@ -614,7 +596,7 @@ <para/> </entry> <entry> - <para>Connector can support IS NULL predicate criteria.</para> + <para>Translator can support IS NULL predicate criteria.</para> </entry> </row> <row> @@ -625,7 +607,7 @@ <para/> </entry> <entry> - <para>Connector can support the OR logical criteria.</para> + <para>Translator can support the OR logical criteria.</para> </entry> </row> <row> @@ -636,7 +618,7 @@ <para/> </entry> <entry> - <para>Connector can support the NOT logical criteria. IMPORTANT: This + <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> @@ -649,7 +631,7 @@ <para/> </entry> <entry> - <para>Connector can support EXISTS predicate criteria.</para> + <para>Translator can support EXISTS predicate criteria.</para> </entry> </row> <row> @@ -660,7 +642,7 @@ <para/> </entry> <entry> - <para>Connector can support a quantified comparison criteria using the ALL + <para>Translator can support a quantified comparison criteria using the ALL quantifier.</para> </entry> </row> @@ -672,7 +654,7 @@ <para/> </entry> <entry> - <para>Connector can support a quantified comparison criteria using the SOME or ANY + <para>Translator can support a quantified comparison criteria using the SOME or ANY quantifier.</para> </entry> </row> @@ -684,7 +666,7 @@ <para /> </entry> <entry> - <para>Connector can support the ORDER BY clause in queries.</para> + <para>Translator can support the ORDER BY clause in queries.</para> </entry> </row> <row> @@ -695,7 +677,7 @@ <para>OrderBy</para> </entry> <entry> - <para>Connector can support the ORDER BY items that are not directly specified in the select clause.</para> + <para>Translator can support the ORDER BY items that are not directly specified in the select clause.</para> </entry> </row> <row> @@ -706,7 +688,7 @@ <para /> </entry> <entry> - <para>Connector can support an explict GROUP BY clause.</para> + <para>Translator can support an explict GROUP BY clause.</para> </entry> </row> <row> @@ -717,7 +699,7 @@ <para>GroupBy</para> </entry> <entry> - <para>Connector can support the HAVING clause.</para> + <para>Translator can support the HAVING clause.</para> </entry> </row> <row> @@ -728,7 +710,7 @@ <para/> </entry> <entry> - <para>Connector can support the AVG aggregate function.</para> + <para>Translator can support the AVG aggregate function.</para> </entry> </row> <row> @@ -739,7 +721,7 @@ <para/> </entry> <entry> - <para>Connector can support the COUNT aggregate function.</para> + <para>Translator can support the COUNT aggregate function.</para> </entry> </row> <row> @@ -750,7 +732,7 @@ <para/> </entry> <entry> - <para>Connector can support the COUNT(*) aggregate function.</para> + <para>Translator can support the COUNT(*) aggregate function.</para> </entry> </row> <row> @@ -761,7 +743,7 @@ <para>At least one of the aggregate functions.</para> </entry> <entry> - <para>Connector can support the keyword DISTINCT inside an aggregate function.  This + <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> @@ -773,7 +755,7 @@ <para/> </entry> <entry> - <para>Connector can support the MAX aggregate function.</para> + <para>Translator can support the MAX aggregate function.</para> </entry> </row> <row> @@ -784,7 +766,7 @@ <para/> </entry> <entry> - <para>Connector can support the MIN aggregate function.</para> + <para>Translator can support the MIN aggregate function.</para> </entry> </row> <row> @@ -795,7 +777,7 @@ <para/> </entry> <entry> - <para>Connector can support the SUM aggregate function.</para> + <para>Translator can support the SUM aggregate function.</para> </entry> </row> <row> @@ -806,7 +788,7 @@ <para /> </entry> <entry> - <para>Connector can support the use of a subquery in a scalar context (wherever an + <para>Translator can support the use of a subquery in a scalar context (wherever an expression is valid).</para> </entry> </row> @@ -818,7 +800,7 @@ <para>At least one of the subquery pushdown capabilities.</para> </entry> <entry> - <para>Connector can support a correlated subquery that refers to an element in + <para>Translator can support a correlated subquery that refers to an element in the outer query.</para> </entry> </row> @@ -841,7 +823,7 @@ <para /> </entry> <entry> - <para>Connector can support "searched” CASE expressions anywhere that expressions are + <para>Translator can support "searched” CASE expressions anywhere that expressions are accepted.</para> </entry> </row> @@ -853,7 +835,7 @@ <para /> </entry> <entry> - <para>Connector support UNION and UNION ALL</para> + <para>Translator support UNION and UNION ALL</para> </entry> </row> <row> @@ -864,7 +846,7 @@ <para/> </entry> <entry> - <para>Connector supports INTERSECT</para> + <para>Translator supports INTERSECT</para> </entry> </row> <row> @@ -875,7 +857,7 @@ <para/> </entry> <entry> - <para>Connector supports Except</para> + <para>Translator supports Except</para> </entry> </row> <row> @@ -886,7 +868,7 @@ <para>Unions, Intersect, or Except</para> </entry> <entry> - <para>Connector supports set queries with an ORDER BY</para> + <para>Translator supports set queries with an ORDER BY</para> </entry> </row> <row> @@ -897,7 +879,7 @@ <para/> </entry> <entry> - <para>Connector can support the limit portion of the limit clause</para> + <para>Translator can support the limit portion of the limit clause</para> </entry> </row> <row> @@ -908,7 +890,7 @@ <para/> </entry> <entry> - <para>Connector can support the offset portion of the limit clause</para> + <para>Translator can support the offset portion of the limit clause</para> </entry> </row> <row> @@ -930,34 +912,55 @@ <para/> </entry> <entry> - <para>Connector supports INSERT statements with values specified by an IQueryCommand.</para> + <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 - connector capabilities.</para> + <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 ConnectorCapabilities.useAnsiJoin() should return true - if the Connector prefers the use of ANSI style join structure for + <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 ConnectorCapabilities.requiresCriteria() should return - true if the Connector requires criteria for any Query, Update, or + <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 ConnectorCapabilities.getSupportedFunctions() can be - used to specify which scalar functions the connector supports.  The + <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 connector states that it supports a function, + 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 @@ -971,27 +974,25 @@ <sect2> <title>Physical Limits</title> - <para>The method ConnectorCapabilities.getMaxInCriteriaSize() can be + <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 ConnectorCapabilities.getMaxFromGroups() can be used + <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 ConnectorCapabilities.supportsBatchedUpdates() can be - used to indicate that the connector supports executing the - IBatchedUpdates command. + <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 ConnectorCapabilities.supportsBulkUpdate() can be used - to indicate that the connector accepts update commands containg multi valued ILiterals.</para> - <para>Note that if the connector does not support either of these - update modes, the query engine will compensate by issuing the updates - individually.</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> Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -1,357 +0,0 @@ -<chapter id="connection_pooling"> - <title>Connection Pooling</title> - <sect1> - <title>Overview</title> - <para>The Query Engine logically obtains and closes a connection - for each command.</para> - <para>However many enterprise sources connections can be persistent - and expensive to create. For these situations, - Teiid provides a transparent connection pool to reuse, rather than - constantly close, connections.  The connection pool is highly - configurable through configuration properties and extension APIs for - Connections and Connectors</para> - <para>Many built-in connector types take advantage of pooling, - including JDBC, Salesforce, and LDAP connectors.</para> - </sect1> - <sect1> - <title>Framework Overview</title> - <para>The table below lists the role of each class in the - framework.</para> - <table frame="all"> - <title>Responsibilities of Connection Pool Classes - </title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*" /> - <colspec colname='c2' colwidth=".5*" /> - <colspec colname='c3' colwidth="2*" /> - <thead> - <row> - <entry> - <para>Class</para> - </entry> - <entry> - <para>Type</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>Connection</para> - </entry> - <entry> - <para>Interface</para> - </entry> - <entry> - <para>The isAlive and closeCalled methods are used for pool interaction.</para> - </entry> - </row> - <row> - <entry> - <para>ConnectorIdentity</para> - </entry> - <entry> - <para>Interface</para> - </entry> - <entry> - <para>This interface corresponds to an identifier for a - connection in the pool.  Changing the identity implementation - changes the basis on which connections are pooled.  Connections - that have equal identity objects (based on the equals() method) - will be in the same pool.</para> - </entry> - </row> - <row> - <entry> - <para>SingleIdentity</para> - </entry> - <entry> - <para>Class</para> - </entry> - <entry> - <para>This implementation of ConnectorIdentity makes all - connections equivalent, thus user scoping of connection is ignored.</para> - </entry> - </row> - <row> - <entry> - <para>MappedUserIdentity</para> - </entry> - <entry> - <para>Class</para> - </entry> - <entry> - <para>This implementation of ConnectorIdentity makes all - connections equivalent for a particular user allowing for per-user connection pools.   - </para> - </entry> - </row> - <row> - <entry> - <para>ConnectionPooling</para> - </entry> - <entry> - <para>Annotation</para> - </entry> - <entry> - <para>This optional Annotation can be used on the Connector - implementation class to indicate configure pooling. This can be - especially useful to indicate that automatic ConnectionPooing - should not be used regardless of the connector binding property - settings.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect1> - <sect1> - <title>Using Connection Pooling</title> - <para>Automatic connection pooling does not require any - changes to basic Connector development. It can be enabled by setting - the Connector binding Property ConnectionPoolEnabled=true or by - adding the ConnectionPooling annotation, which defaults to - enabled=true, to the Connector implementation class. Automatic - Connection pooling can be disabled if either setting is false.</para> - <para> - It is important - to consider providing an implementation for - Connection.isAlive to indicate that a Connection is no - longer viable and should be purged from the pool. Connection testing - is performed upon leases from the pool and optionally at a regular - interval that will purge idle Connections. It is also important to - consider having the concrete Connector class implement - ConnectorIdentity factory if Connections are made for multiple - identities. Note that setting connector binding property - UseCredentialMap to true will allow connectors extending BasicConnector - to have their ConnectorIdentity automatically set based upon the user - CredentialMap.</para> - </sect1> - <sect1> - <title>The Connection Lifecycle</title> - <para>These steps occur when connection pooling is enabled: - </para> - <orderedlist> - <listitem> - <para>The - ConnectorManager asks the Connector to generate a ConnectorIdentity - for the given ExecutionContext. The - ConnectorIdentity is then stored on the ExecutionContext.</para> - </listitem> - <listitem> - <para>The ConnectorManager asks for a Connection from the pool - that pertains to the ConnectorIdentity.</para> - </listitem> - <listitem> - <para>The ConnectionPool returns a Connection that was either - pulled from the pool (and passes the isAlive check) or was created - by the Connector if necessary.</para> - </listitem> - <listitem> - <para>After the ConnectorManager has used the Connection to - execute a command, it releases the Connection. This call is - intercepted by the pool and the method - Connection.closeCalled is invoked on the Connection - instead. Note that for many sources no action is necessary on closeCalled.</para> - </listitem> - <listitem> - <para>When the Connection fails an isAlive check or becomes too - old with pool shrinking enabled, it is purged from the pool and - Connection.close is called.</para> - </listitem> - </orderedlist> - <sect2> - <title>XAConnection Pooling</title> - <para> - The usage of XAConnections (that provide XAResources) typically come - with additional limitations about how those Connections can be used - once they are enlisted in a transaction. When enabled, automatic - connection pooling will perform these additional features with - XAConnections: - <itemizedlist> - <listitem> - <para>The pool will return the same XAConnection for all - executions under a given transaction until that transaction - completes. This implies that all executions to a given - XAConnector under the same connection will happen serially. - </para> - </listitem> - <listitem> - <para>XAConnections enlisted in a transaction will - return to the pool once a transaction completes.</para> - </listitem> - <listitem> - <para>Two separate pools will be maintained. One for - Connections that have not and will not be used in a transaction, - and one for XAConnections that have an will be used in a - transaction. Each pool will be configured based upon the same set - of configuration properties - it is not possible to independently - control pool sizes, etc.</para> - </listitem> - </itemizedlist> - </para> - </sect2> - </sect1> - <sect1> - <title>Configuring the Connection Pool</title> - <para>The ConnectionPool has a number of properties that can be - configured via the connector binding expert properties. Note *. indicates that the property prefix is com.metamatrix.data.pool.</para> - <table frame="all"> - <title>Connection Pool Properties</title> - <tgroup cols='4' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth=".5*" /> - <colspec colname='c2' colwidth="1*" /> - <colspec colname='c3' colwidth=".25*" /> - <colspec colname='c4' colwidth="1*" /> - <thead> - <row> - <entry> - <para>Name</para> - </entry> - <entry> - <para>Key</para> - </entry> - <entry> - <para>Default Value</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>Connection Pool Enabled</para> - </entry> - <entry> - <para>ConnectionPoolEnabled</para> - </entry> - <entry> - <para></para> - </entry> - <entry> - <para>Explicitly enables or disables connection - pooling.</para> - </entry> - </row> - <row> - <entry> - <para>Data Source Test Connect Interval (seconds)</para> - </entry> - <entry> - <para>SourceConnectionTestInterval - </para> - </entry> - <entry> - <para>600</para> - </entry> - <entry> - <para>How often (in seconds) to create test connections to the - underlying source to see if it is available.</para> - </entry> - </row> - <row> - <entry> - <para>Pool Maximum Connections</para> - </entry> - <entry> - <para>*.max_connections - </para> - </entry> - <entry> - <para>20</para> - </entry> - <entry> - <para>Maximum number of connections total in the pool. -  This value should be greater than 0.</para> - </entry> - </row> - <row> - <entry> - <para>Pool Maximum Connections for Each ID</para> - </entry> - <entry> - <para>*.max_connections_for_each_id - </para> - </entry> - <entry> - <para>20</para> - </entry> - <entry> - <para>Maximum number of connections per ConnectorIdentity - object.  This value should be greater than 0.</para> - </entry> - </row> - <row> - <entry> - <para>Pool Connection Idle Time (seconds)</para> - </entry> - <entry> - <para>*.live_and_unused_time - </para> - </entry> - <entry> - <para>60</para> - </entry> - <entry> - <para>Maximum idle time (in seconds) before a connection - is closed if shrinking is enabled.</para> - </entry> - </row> - <row> - <entry> - <para>Pool Connection Waiting Time (milliseconds)</para> - </entry> - <entry> - <para>*.wait_for_source_time - </para> - </entry> - <entry> - <para>120000</para> - </entry> - <entry> - <para>Maximum time to wait (in milliseconds) for a - connection to become available.</para> - </entry> - </row> - <row> - <entry> - <para>Pool cleaning Interval (seconds)</para> - </entry> - <entry> - <para>*.cleaning_interval - </para> - </entry> - <entry> - <para>60</para> - </entry> - <entry> - <para>Interval (in seconds) between checking for idle - connections if shrinking is enabled.</para> - </entry> - </row> - <row> - <entry> - <para>Enable Pool Shrinking</para> - </entry> - <entry> - <para>*.enable_shrinking - </para> - </entry> - <entry> - <para>true</para> - </entry> - <entry> - <para>Indicate whether the pool is allowed to shrink. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect1> -</chapter> \ No newline at end of file Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -2,196 +2,168 @@ <!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> %CustomDTD; ]> -<chapter id="connector_api"> - <title>Connector API</title> +<chapter id="translator_api"> + <title>Developing a Translator</title> <sect1> - <title>Overview</title> - <para>A component called the Connector Manager is controlling access - to your connector. This chapter reviews - the basics of how the Connector Manager interacts with your connector - while leaving reference details and + <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 connector must implement the following interfaces to connect - and query an enterprise Data Source. - These interfaces are in package called - <emphasis>org.teiid.connector.api:</emphasis> - </para> - <itemizedlist> - <listitem> - <para> - <emphasis>Connector</emphasis> - - This interface is the starting point for all interaction with - your connector. It allows the Connector - Manager to obtain a connection and perform lifecycle events. - </para> - </listitem> - <listitem> - <para> - <emphasis>Connection</emphasis> - - This interface represents a connection to your data source. It is - used as a starting point for actual - command executions.  Connections provided to the Connector Manager will be - obtained and released for each - command execution. Teiid provides for extensible automatic connection - pooling, as discussed in the - <link linkend="connection_pooling">Connection Pooling</link> - chapter. - </para> - </listitem> - <listitem> - <para> - <emphasis>ConnectorCapabilities</emphasis> - - This interface allows a connector to describe the execution - capabilities of the connector. - </para> - </listitem> - <listitem> - <para> - <emphasis>Execution (and sub-interfaces)</emphasis> - - These interfaces represent a command execution with your - Connector.  There is a sub-interface for - executing each kinds of command:  ResultSetExecution, UpdateExecution, and ProcedureExecution. - </para> - </listitem> - </itemizedlist> - <para> - Note that many of the interfaces above have base implementations in the - <emphasis>org.teiid.connector.basic</emphasis> - package. Consider extending the corresponding BasicXXX class rather - than fully implementing the interface. - </para> - <para>The most important interfaces provided by Teiid to the connector - are the following:</para> - <itemizedlist> - <listitem> - <para> - <emphasis>ConnectorEnvironment</emphasis> - – an interface describing access to external resources for your - connector. - </para> - </listitem> - <listitem> - <para> - <emphasis>ConnectorLogger</emphasis> - – an interface for writing logging information to Teiid logs. - </para> - </listitem> - <listitem> - <para> - <emphasis>ExecutionContext</emphasis> - – interface defining the execution context available to the connector when - executing a command. - </para> - </listitem> - </itemizedlist> + <para> + A custom translator must extend <emphasis>org.teiid.translator.ExecutionFactory</emphasis> + to connect and query an enterprise data source. This extended class must provide a no-arg constructor + that can be constructed using Java reflection libraries. This Execution Factory need define/override following elements. + </para> + + <sect2> + <title>ConnectionFactory</title> + <para>Defines the "ConnectionFactory" interface that is expected from resource adapter. This defined as part of + class definition using generics while extending the "ExecutionFactory" class</para> + </sect2> + + <sect2> + <title>Connection</title> + <para>Defines the "Connection" interface that is expected from resource adapter. This defined as part of + class definition using generics while extending the "ExecutionFactory" class</para> + </sect2> + + <sect2> + <title>Configuration Properties</title> + <para>Every software program requires some external configuration, that defines ways user can alter the behavior of a program. + If this translator needs configurable properties define a variable for every property as an attribute in the extended + "ExecutionFactory" class. Then define a "get" and "set" methods for each of them. Also, annotate each "get" method with + <emphasis>@TranslatorProperty</emphasis> annotation and provide the metadata about the property. For example, if you need a + property called "foo", + <programlisting><![CDATA[ +String foo = "balh"; + +@TranslatorProperty(display="Foo property", description="description about Foo") +public String getFoo() { + return foo; +} + +public void setFoo(String value) { + return this.foo = value; +} + ]]> </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. + </para> + + <para>The <emphasis>@TranslatorProperty</emphasis> defines the following metadata that you can define about your property</para> + <itemizedlist> + <listitem> + <para>display: Display name of the property</para> + </listitem> + <listitem> + <para>description: Description about the property</para> + </listitem> + <listitem> + <para>required: The property is a required property; or optional and a default is supplied</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> + </listitem> + <listitem> + <para>masked: The tools need to mask the property; Do not show in plain text; used for passwords</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Initializing the Translator</title> + <para>Override and implement the <emphasis>start</emphasis> method (be sure to call + "super.start()") if your translator needs to do any initializing before it is used by the Teiid engine. This method + will be called by Teiid, once after all the configuration properties set above are injected into the class. </para> + </sect2> + + <sect2> + <title>TranslatorCapabilities</title> + <para>These are various methods that typically begin with method + signature "supports" on the "ExecutionFactory" 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> + </sect2> + + <sect2> + <title>Execution (and sub-interfaces)</title> + <para>Based on types of executions you are supporting, the following methods need to be overridden + and need to provide implementations for these methods by extending respective interfaces.</para> + + <itemizedlist> + <listitem> + <para><emphasis>createResultSetExecution</emphasis> - 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> + </listitem> + <listitem> + <para><emphasis>createProcedureExecution</emphasis> - 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> + </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> + </sect2> + + <sect2> + <title>Logging</title> + <para>Teiid provides <emphasis>org.teiid.logging.LogManager</emphasis> class for logging purposes. + Create a logging context and use the LogManager to log your messages. These will be automatically + sent to the main Teiid logs. You can edit the "jboss-log4j.xml" inside "conf" directory of the JBoss AS's profile + to add the custom context. Teiid uses Log4J as its underlying logging system.</para> + </sect2> + + <sect2> + <title>Exceptions</title> + <para>If you need to bubble up any exception use <emphasis>org.teiid.translator.TranslatorException</emphasis> + 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 + a default instance of this + Translator is available any VDB that would like to use by just mentioning its name in its "vdb.xml" configuration file. + VDB can also override the default properties and define another instance of this Translator too. The name you give here is the short + name used every where else in the Teiid configuration to refer to this translator.</para> + </sect2> + </sect1> + + <sect1> - <title>Connector Lifecycle</title> - <sect2> - <title>Starting</title> - <para> - A Connector instance will be initialized one time via the start - method, which passes in a - <emphasis>ConnectorEnvironment</emphasis> - object provided by the - <emphasis>Connector Manager</emphasis> - . The - <emphasis>ConnectorEnvironment provides</emphasis> - the following resources to the connector: - </para> - <itemizedlist> - <listitem> - <para>Configuration properties – name / value pairs as provided by - the connector binding in - the Teiid Console</para> - </listitem> - <listitem> - <para>Logging – ConnectorLogger interface allows a Connector to log - messages and errors to - Teiid’s log files.</para> - </listitem> - <listitem> - <para>Type facility – an interface defining runtime datatypes and - type conversion facility.</para> - </listitem> - <listitem> - <para>Scheduling facility – repeating tasks can be scheduled and managed by Teiid.</para> - </listitem> - <listitem> - <para>Caching facility – easy methods for caching based upon relevant contexts, such as session or query scope.</para> - </listitem> - </itemizedlist> - </sect2> - <sect2> - <title>Running</title> - <para> - While the connector is running it is expected to return provide - connections and capabilities information in response to system - requests. If the source system is not available ConnectorExceptions or - RuntimeExceptions may be thrown at any time to indicate failure. The - connector should handle failure internally in a graceful manner, since - the system will not automatically perform a stop/start. - </para> - </sect2> - <sect2> - <title>Stopping</title> - <para>The stop method will be called on system shutdown or on an - administrative call that to stop the connector. Once a connector has - been stopped the instance is removed from the system. A new Connector - instance will be created prior to the start call.</para> - </sect2> - </sect1> - <sect1> <title>Connections to Source</title> <sect2> <title>Obtaining connections</title> - <para>The connector must implement the getConnection() method to - allow the Connector Manager to obtain a - connection. The getConnection() method is passed a ExecutionContext, which - contains information about the - context in which this query is being executed.</para> - <para>The ExecutionContext provides the following:</para> - <itemizedlist> - <listitem> - <para>User name</para> - </listitem> - <listitem> - <para>Virtual database name</para> - </listitem> - <listitem> - <para>Virtual database version</para> - </listitem> - <listitem> - <para>The ability to add execution warnings.</para> - </listitem> - <listitem> - <para>Trusted token</para> - </listitem> - </itemizedlist> - <para>The trusted token is used to pass security information specific - to your application through the - Teiid. The client can pass the trusted token when they connect via - JDBC. This token is then - passed to the Membership Service and may be created, replaced, or modified - at that time. In some cases, you - may wish to provide a customer Membership Service implementation to - handle security needs specific to your - organization. For more information on implementing see the <ulink url='&docUrl;'>Server Extension Guide</ulink></para> + <para>The extended "ExecutionFactory" must implement the <emphasis>getConnection()</emphasis> method to + allow the Connector Manager to obtain a connection. </para> </sect2> <sect2> <title>Releasing Connections</title> - <para>Once the Connector Manager has obtained a connection, it will - use that connection only for the - lifetime of the request.  When the request has completed, the close() - method will be called on the - connection.</para> + <para>Once the Connector Manager has obtained a connection, it will use that connection only for the + lifetime of the request.  When the request has completed, the closeConnection() method called on the "ExecutionFactory". + You must also override this method to properly close the connection.</para> <para> In cases (such as when a connection is stateful and expensive to - create), connections should be pooled.  Teiid - provides an extensible connection pool for this purpose, as described in - chapter - <link linkend="connection_pooling">Connection Pooling</link>. + 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. </para> </sect2> </sect1> @@ -200,13 +172,10 @@ <sect2> <title>Execution Modes</title> <para> - The Connector API uses a Connection to obtain an execution - interface for the command it is - executing. The actual queries themselves are sent to connectors in the form of a - set of objects, which are further - described in Chapter - <link linkend="command_language">Command Language</link>. Connectors are allowed to support any subset of the available - execution modes. + 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>. + translators are allowed to support any subset of the available execution modes. </para> <table frame='all'> <title>Types of Execution Modes</title> @@ -227,7 +196,7 @@ <code>ResultSetExecution</code> </entry> <entry> - <code>IQueryCommand</code> + <code>QueryExpression</code> </entry> <entry>A query corresponding to a SQL SELECT or set query statement.</entry> </row> @@ -236,10 +205,9 @@ <code>UpdateExecution</code> </entry> <entry> - <code>IInsert, IUpdate, IDelete, IBatchedUpdates</code> + <code>Insert, Update, Delete, BatchedUpdates</code> </entry> - <entry>An insert, update, or delete, corresponding to a SQL - INSERT, UPDATE, or DELETE command + <entry>An insert, update, or delete, corresponding to a SQL INSERT, UPDATE, or DELETE command </entry> </row> <row> @@ -247,10 +215,9 @@ <code>ProcedureExecution</code> </entry> <entry> - <code>IProcedure</code> + <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> @@ -262,10 +229,9 @@ <sect2> <title>ResultSetExecution</title> <para> - Typically most commands executed against connectors are IQueryCommands. - While the command is being executed, the connector provides - results via the - ResultSetExecution next method. The next method should return null to indicate the end + Typically most commands executed against translators are QueryExpression. + While the command is being executed, the translator provides results via the + ResultSetExecution's "next" method. The "next" method should return null to indicate the end of results. Note: the expected batch size can be obtained from the ExecutionContext and used as a hint in fetching results from the EIS. </para> @@ -273,28 +239,24 @@ <sect2> <title>Update Execution</title> <para>Each execution returns the update count(s) expected by the update command. - If possible IBatchedUpdates should be executed atomically. + If possible BatchedUpdates should be executed atomically. The ExecutionContext can be used to determine if the execution is already under a transaction.</para> </sect2> <sect2> <title>Procedure Execution</title> - <para>Procedure commands correspond to the execution of a stored - procedure or some other functional + <para>Procedure commands correspond to the execution of a stored procedure or some other functional construct. A procedure takes zero or more input values and can return a result - set and zero or more output - values.  Examples of procedure execution would be a stored procedure in a - relational database or a call to - a web service.</para> - <para>If a result set is expected when a procedure is executed, all - rows from it will be retrieved via the + set and zero or more output values.  Examples of procedure execution would be a stored procedure in a + relational database or a call to a web service.</para> + <para>If a result set is expected when a procedure is executed, all rows from it will be retrieved via the ResultSetExecution interface first. Then, if any output values are expected, they will - be retrieved via the - getOutputParameterValues() method. + be retrieved via the getOutputParameterValues() method. </para> </sect2> + <!-- <sect2> <title>Asynchronous Executions</title> - <para>In some scenarios, a connector needs to execute + <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> @@ -316,29 +278,24 @@ </listitem> </itemizedlist> </sect2> + --> <sect2> <title>Bulk Execution</title> - <para> - Non batched - <code>IInsert, IUpdate, IDelete</code> - commands may have Iliteral values marked as multiValued if the - ConnectorCapabilities shows support for BulkUpdate. Commands with - multiValued Iliterals represent multiple executions of the same - command with different values. As with IBatchedUpdates, bulk operations should be executed atomically if possible. + <para> Non batched <code>Insert, Update, Delete</code> + commands may have <code>Literal</code> values marked as multiValued if the + capabilities shows support for BulkUpdate. Commands with + multiValued <code>Literal</code>s represent multiple executions of the same + command with different values. As with BatchedUpdates, bulk operations should be executed atomically if possible. </para> </sect2> <sect2> <title>Command Completion</title> - <para>All normal command executions end with the calling of close() - on the Execution object.  Your - implementation of this method should do the appropriate clean-up work for all - state in the Execution - object.</para> + <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> </sect2> <sect2> <title>Command Cancellation</title> - <para>Commands submitted to Teiid may be aborted in several - scenarios:</para> + <para>Commands submitted to Teiid may be aborted in several scenarios:</para> <itemizedlist> <listitem> <para>Client cancellation via the JDBC API (or other client APIs) @@ -354,74 +311,55 @@ <para>Clean-up if a query fails during processing</para> </listitem> </itemizedlist> - <para>Unlike the other execution methods, which are handled in a single-threaded manner, calls to cancel happen asynchronously with respect to the execution thread.</para> - <para>Your connector implementation may choose to do nothing in - response to this cancellation message. In + <para>Unlike the other execution methods, which are handled in a single-threaded manner, + calls to cancel happen asynchronously with respect to the execution thread.</para> + <para>Your connector implementation may choose to do nothing in response to this cancellation message. In this instance, Teiid will call close() on the execution object after - current processing - has completed. Implementing the cancel() method allows for faster - termination of queries being processed - and may allow the underlying data source to terminate its operations + current processing has completed. Implementing the cancel() method allows for faster + termination of queries being processed and may allow the underlying data source to terminate its operations faster as well.</para> </sect2> </sect1> - <sect1> - <title>Monitored Connectors</title> - <para>Teiid can automatically monitor connectors, which will update a - status flag on the connector. This status can be checked via the - AdminApi and is exposed in the console. To use connector - monitoring - effectively: - </para> - <itemizedlist> - <listitem> - <para>Set a positive test interval value on - on the connector binding - (default is 600) indicating the number of - seconds between status - checks. These checks are useful in idle - periods. - </para> - </listitem> - <listitem> - <para>Implement a meaningful isAlive method on your Connector - Connections. - </para> - </listitem> - <listitem> - <para>Use either a pooled Connector or a Connector that supports - single identity. - </para> - </listitem> - </itemizedlist> - <para>Possible status results include:</para> - <itemizedlist> - <listitem> - <para>Not initialized - to indicate not yet started. - </para> - </listitem> - <listitem> - <para>Init failed - to indicate start failed. - </para> - </listitem> - <listitem> - <para>Open - to indicate the running state and that connections can - be obtained form the source. - </para> - </listitem> - <listitem> - <para>Unable to check - to indicate the running state but - connections cannot be obtained administratively. - </para> - </listitem> - <listitem> - <para>Data Source Unavailable - to indicate the running state. - </para> - </listitem> - <listitem> - <para>Closed - to indicate that the Connector has been stopped. - </para> - </listitem> - </itemizedlist> - </sect1> + + <sect1> + <title>Packaging</title> + <para>Once the "ExecutionFactory" class is implemented, package it in a JAR file. The only + additional requirement is provide a file called "jboss-beans.xml" in the "META-INF" directory of the JAR file, with + following contents. + <programlisting><![CDATA[ + <?xml version="1.0" encoding="UTF-8"?> + <deployment xmlns="urn:jboss:bean-deployer:2.0"> + + <bean name="translator-${name}-template" class="org.teiid.templates.TranslatorDeploymentTemplate"> + <property name="info"><inject bean="translator-${name}"/></property> + <property name="managedObjectFactory"><inject bean="ManagedObjectFactory"/></property> + </bean> + + <bean name="translator-${name}" class="org.teiid.templates.TranslatorTemplateInfo"> + <constructor factoryMethod="createTemplateInfo"> + <factory bean="TranslatorDeploymentTemplateInfoFactory"/> + <parameter class="java.lang.Class">org.teiid.templates.TranslatorTemplateInfo</parameter> + <parameter class="java.lang.Class">${execution-factory-class}</parameter> + <parameter class="java.lang.String">translator-${name}</parameter> + <parameter class="java.lang.String">${name}</parameter> + </constructor> + </bean> + + </deployment> + ]]> </programlisting> + + replace ${name} with name of your translator, and replace ${execution-factory-class} with your + overridden 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> + </sect1> + + <sect1> + <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 + has external dependencies to other JAR libraries, they need to be placed inside the "lib" directory of the JBoss AS's profile. + This will require a restart of the JBoss Server. Another option to avoid the restart is to bundle all the required JAR files into + the same JAR file as the Translator. It is user's responsibility to make sure they are not running into any conflicts with their + dependent libraries with those already exist in the JBoss environment.</para> + </sect1> </chapter> \ No newline at end of file Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -1,371 +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="connector_deployment"> - <title>Connector Deployment</title> - - <sect1> - <title>Overview</title> - <para>Once you have written and compiled the code for your connector, there are several - steps to deploy your connector to Teiid:</para> - <itemizedlist> - <listitem> - <para>Creating a Connector Type Definition file that defines the properties required - to initialize your connector.</para> - </listitem> - <listitem> - <para>Identifying the Extension Modules (jars and resources) required for the - Connector to run.</para> - </listitem> - <listitem> - <para>Creating the Connector Archive file to bundle the Connector Type Definition - file and the Extension Modules.</para> - </listitem> - <listitem> - <para>Creating a Connector Binding using your Connector Type.</para> - </listitem> - </itemizedlist> - <para>This chapter will help you perform these steps.  </para> - </sect1> - - <sect1> - <title>Connector Type Definition File</title> - <para>A Connector Type Definition file defines a connector in Teiid.  The - Connector Type Definition file defines some key properties that allow Teiid to - use your connector as well as specifying other properties your connector might need.  </para> - <para>A Connector Type Definition file is in XML format and typically has the extension “.cdk”. -  It defines a default name for the connector type, the properties expected by the connector, - and other information that allows the properties to be displayed correctly in the Console when - a Connector Binding is created from the Connector Type.  </para> - <para> An example of this file can be found in <link linkend="appendix-a">Appendix A.</link> - It may be helpful to refer to this file while reading this section. The template file can - also be created using the Connector Development Kit.</para> - - <sect2> - <title>Connector Binding Properties</title> - <para>The Connector API has built-in mechanisms for using the - properties defined in the Connector ComponentType definition in the - configuration.xml located in your deploy directory. For custom - connectors the following properties are of primary importance:</para> - <table frame='all'> - <title>Connector Properties</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <colspec colname='c3' colwidth="2*" /> - <thead> - <row> - <entry> - <para>Property Name</para> - </entry> - <entry> - <para>Example Value</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>ConnectorClass</para> - </entry> - <entry> - <para>foo.MyConnector</para> - </entry> - <entry> - <para>Fully-qualified name of class implementing the Connector interface.</para> - </entry> - </row> - - <row> - <entry> - <para>ConnectorClassPath</para> - </entry> - <entry> - <para>extensionjar:foo.jar</para> - </entry> - <entry> - <para>Semi-colon delimited list of jars defining the classpath of this - connector.  Typically this includes the actual code for your connector as well as - any 3rd party dependencies.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para>For more information on the Connector Classpath, see the section <link linkend="understanding_classpath">Understanding the Connector Classpath</link></para> - </sect2> - - <sect2> - <title>Connector Properties</title> - <para>Most connectors require some initialization parameters to connect to the - underlying enterprise information system.  These properties can be defined in the Connector - Type Definition file along with their default values and other property metadata.  The actual - property values can be changed when the connector is deployed in the Teiid Console.</para> - <para>Each connector property carries with it several attributes that are used by the - Teiid Console to integrate the connector seamlessly into Teiid.</para> - - <table frame='all'> - <title>All Attributes</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <colspec colname='c3' colwidth="2*"/> - <thead> - <row> - <entry> - <para>Attribute Name</para> - </entry> - <entry> - <para>Example Value</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>Name</para> - </entry> - <entry> - <para>ExampleProperty</para> - </entry> - <entry> - <para>Property name – should only contain letters, no spaces or other - punctuation.  This is the name of the property as it will be passed to the connector - in the ConnectorEnvironment.</para> - </entry> - </row> - <row> - <entry> - <para>DisplayName</para> - </entry> - <entry> - <para>Example property</para> - </entry> - <entry> - <para>The property name as displayed in the Console.  Typically this is a nicely - formatted version of the Name attribute.</para> - </entry> - </row> - <row> - <entry> - <para>ShortDescription</para> - </entry> - <entry> - <para>The example property is used to control something.</para> - </entry> - <entry> - <para>A short description that is displayed as a tooltip of the property in the - Teiid Console.</para> - </entry> - </row> - <row> - <entry> - <para>DefaultValue</para> - </entry> - <entry> - <para>Xyz</para> - </entry> - <entry> - <para>A default value for the property.  This value will be auto-filled when a - connector binding is created from the Connector Type.</para> - </entry> - </row> - <row> - <entry> - <para>IsRequired</para> - </entry> - <entry> - <para>false</para> - </entry> - <entry> - <para>If true, then this property is required.  Any required property without a value - is displayed in red in the connector binding properties panel.</para> - </entry> - </row> - <row> - <entry> - <para>IsModifiable</para> - </entry> - <entry> - <para>true</para> - </entry> - <entry> - <para>If set to “false”, the property is visible only when viewing all properties and is - not modifiable in the properties panel.  </para> - </entry> - </row> - <row> - <entry> - <para>IsMasked</para> - </entry> - <entry> - <para>false</para> - </entry> - <entry> - <para>If set to “true”, the property will be masked with *’s when it is entered and - saved in an encrypted form.  This attribute is typically used with passwords.</para> - </entry> - </row> - <row> - <entry> - <para>IsExpert</para> - </entry> - <entry> - <para>true</para> - </entry> - <entry> - <para>Depending on the property display, the property can be optionally - displayed for advanced users.</para> - </entry> - </row> - <row> - <entry> - <para>PropertyType</para> - </entry> - <entry> - <para>String</para> - </entry> - <entry> - <para>The short name of a built-in Java primitive wrapper Object type.  Other - possible values include Integer, Boolean, etc.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para>A property may also be constrained to a set of allowed values by - adding child AllowedValue elements, i.e. - &lt;AllowedValue&gt;value&lt;/AllowedValue&gt;. - Adding allowed values will cause the property to be displayed with a - dropdown that limits the user selection to the allowed values. - </para> - </sect2> - </sect1> - - <sect1> - <title>Extension Modules</title> - <para>Extension Modules are used in Teiid to store code that extends - Teiid in a central managed location.  Extension Module JAR files are stored in - the repository database and all Teiid processes access this database to obtain extension - code.  Custom connector code is typically deployed as extension models.</para> - <sect2 id="understanding_classpath"> - <title>Understanding the Connector Classpath</title> - <para>By default each connector binding is loaded using the Teiid - common classloader. Any needed extension modules are automatically - added to common classpath. The common classloader is also a delegating - classloader, so it's possible for classes to be found from the - classpath set for Teiid or it's containing application.</para> - <para> - If class conflicts would arise from delegation or shared classloading, - each connector binding - can be loaded in an isolated classloader (shared only by connectors - with the same classpath), by setting the connector binding property - UsePostDelegation to true. This classloading mode loads - classes via the Teiid Extension Modules before loading classes from higher - level classloaders.</para> - - <para>The ConnectorClasspath property of your connector defines the - extension module jars - that are included in your connector’s classpath.  The connector classpath - is defined as a - semi-colon delimited list of extension modules.  Extension module jar files must - be prefixed - with "extensionjar:"</para> - </sect2> - </sect1> - <sect1> - <title>Connector Archive File</title> - <para>The Connector Archive file is a bundled version of all files needed by this Connector - to execute in Teiid. This file includes the Connector Type Definition file and - all the Extension Modules required by the Connector to create a connector archive file (CAF).. - </para> - <itemizedlist> - <listitem> - <para>The archive is a standard zip file.</para> - </listitem> - <listitem> - <para>Start the CDK tool by executing cdk.bat</para> - </listitem> - <listitem> - <para>Execute “CreateArchive” command by supplying:</para> - <orderedlist> - <listitem> - <para>Path to the name of the archive file to create</para> - </listitem> - <listitem> - <para>Path to the Connector Type Definition file</para> - </listitem> - <listitem> - <para>Path to the directory where the required Extension Modules (jar files) are stored - (note that only .jar files specified in the ConnectorClassPath property of the Connector - Type definition file are bundled.</para> - </listitem> - </orderedlist> - </listitem> - </itemizedlist> - - <para>The file created by the CDK can be opened with any zip file utility to verify the - required files are included.</para> - <para>The archive file can be tested in the CDK tool by loading it using the command - “loadArchive”.  Refer <link linkend="connector_development_kit">CDK chapter</link> for more information.</para> - </sect1> - <sect1> - <title>Importing the Connector Archive</title> - - <sect2> - <title>Into Teiid</title> - <para>To use a new connector type definition in Teiid, the Connector Archive - file must be imported via the AdminAPI via the addConnectorArchive method.</para> - </sect2> - - <sect2> - <title>Into Teiid Designer</title> - <para>To use the new connector type during the development of the VDB for testing using the - SQLExplorer, Connector Archive File must be imported into the Designer tools. To perform this - task, perform the following steps.</para> - <orderedlist> - <listitem> - <para>Start Designer</para> - </listitem> - <listitem> - <para>Open the project and in the “vdb” execute panel, click on the “Open the - Configuration Manager” link. For more information consult the designer’s guide.</para> - </listitem> - </orderedlist> - <orderedlist> - <listitem> - <para>In the result window, click “Import a Connector Type (.cdk,.caf)” link and follow - directions.</para> - </listitem> - </orderedlist> - <para>The Connector Type can now be used to create Connector Bindings.  </para> - </sect2> - </sect1> - - <sect1> - <title>Creating a Connector Binding</title> - - <sect2> - <title>In Designer</title> - <para>Connector Binding properties can also be defined in the Designer for the given - Connector Type, if the corresponding Connector Archive File is imported into the Designer. If - you try to execute your VDB with SQLExplorer in the Designer, this tool will present you with - a window to specify such Connector Bindings. The user is required specify these binding - properties before they can test using the SQLExplorer. For more information on how this can be - accomplished please refer to the <ulink url="&desDocUrl;">Designer User’s Guide</ulink>.</para> - <para>Also, note that the bindings specified in the Designer tool are automatically bundled - into the VDB for deployment, so if there are any properties that needs to be changed from - development environment to the production environment, those properties need to be modified - when a VDB is later deployed.</para> - </sect2> - </sect1> -</chapter> \ No newline at end of file Added: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml (rev 0) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -0,0 +1,288 @@ +<!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="develop_adapter"> + <title>Developing JEE JCA Adapters for Teiid Translators</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 + developers, we provided some base implementation framework to ease the development of these Connectors. + If you already have a JCA Connector or some other mechanism to get data from your source system, you can skip this chapter.</para> + + <para>If you are not familiar with JCA API, please read the <ulink url="http://java.sun.com/j2ee/connector/">JCA 1.5 Specification</ulink>. + There are lot of online tutorials on how to design and build a JCA Connector. The below we show you to build very simple connector, + however building actual connector that supports transactions, security can get much more complex.</para> + + <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> + <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 + only uses the JCA's SPI interfaces. </para> + + <itemizedlist> + <listitem> + <para>Define Managed Connection Factory</para> + </listitem> + <listitem> + <para>Define the Connection Factory class</para> + </listitem> + <listitem> + <para>Define the Connection class</para> + </listitem> + <listitem> + <para>Define the configuration properties in a "ra.xml" file</para> + </listitem> + </itemizedlist> + + <sect2 id="managed_connection_factory"> + <title>Define Managed Connection Factory</title> + <para>Extend the <emphasis>BasicManagedConnectionFactory</emphasis>, 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> + </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>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 + "getConnection" method by calling + + <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 + the Teiid defined "security-domain" for validating the JDBC end user. However, it is users responsibility to make the necessary + logins before the Container's thread accesses this resource adapter, and this can get overly complex.</para> + </sect2> + + <sect2 id="connection"> + <title>Define the Connection class</title> + <para>Extend the <emphasis>BasicConnection</emphasis> 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 { + + 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> + <title>XA Transactions</title> + <para>If you EIS source can participate in XA transactions, then on your <link linkend="connection">Connection</link> object, + override the "getXAResource()" method and provide the "XAResource" object for the EIS system. + Also, You need to extend the "BasicResourceAdapter" class and provide implementation for method + "public XAResource[] getXAResources(ActivationSpec[] specs)" to participate in crash recovery. </para> + + <para>Note that, only when the resource adapters are XA capable, then Teiid can make them participate in a distributed + transactions. If they are not XA capable, then source can participate in distributed query but will not participate + in the transaction. Transaction semantics at that time defined by how you defined "-ds.xml" file. i.e. with local-tx or no-tx</para> + </sect2> + + <sect2> + <title>Define the configuration properties in a "ra.xml" file</title> + <para>Define a "ra.xml" file (sample shown in the <link linkend="appendix_a">appendix-a</link>) in "META-INF" directory of your RAR file. + For every configuration property defined inside the <link linkend="managed_connection_factory">ManagedConnectionFactory</link> + class, define the following XML configuration + 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> + + <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. + For every property define the following properties + + <itemizedlist> + <listitem> + <para>$display: Display name of the property</para> + </listitem> + <listitem> + <para>$description: Description about the property</para> + </listitem> + <listitem> + <para>$required: The property is a required property; or optional and a default is supplied</para> + </listitem> + <listitem> + <para>$allowed: If property value must be in certain set of legal values, this defines all the allowed values</para> + </listitem> + <listitem> + <para>$masked: The tools need to mask the property; Do not show in plain text; used for passwords</para> + </listitem> + <listitem> + <para>$advanced: Notes this as Advanced property</para> + </listitem> + <listitem> + <para>$editable: Property can be modified; or read-only</para> + </listitem> + </itemizedlist> + + Note that all these are optional properties; however in the absence of this metadata, tooling will not work as expected. + + </para> + </sect2> + </sect1> + + <sect1> + <title>Packaging the Adapter</title> + <para>Once all the required code is developed, it is time to package them into a RAR artifact, that can be deployed + into a Conainer. A RAR artifact is lot more similar to a WAR. To put together a RAR file it really depends upon + build system you are using.</para> + + <itemizedlist> + <listitem> + <para>Eclipse: You can start out with building Java Connector project, it will produce the RAR file</para> + </listitem> + <listitem> + <para>Ant: If you are using "ant" build tool, there is "rar" build task available</para> + </listitem> + <listitem> + <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> + </listitem> + </itemizedlist> + <para>Make sure that the RAR file, under its "META-INF" directory has the "ra.xml" file. If you are using maven + see <ulink url="http://maven.apache.org/plugins/maven-rar-plugin/"><... the root of the RAR file, + you can embed the JAR file containing your connector code and any dependent library JAR files. </para> + </sect1> + + <sect1> + <title>Deploying the Adapter</title> + <para>Once the RAR file is built, deploy it by copying the RAR file into "deploy" directory of JBoss AS's choosen profile. + Typically the server does not need to be restarted when a new RAR file is being added. Alternatively, you can also use + "admin-console" a web based monitoring and configuration tool to deploy this file into the container. </para> + + <para>Once the Connector's RAR file is deployed into the JBoss container, now you can start creating a instance of this + connector to be used with your Translator. Creating a instance of this Connector is no different than creating a + "Connection Factory" in JBoss AS. Again, you have have two ways you can create a "ConnectionFactory".</para> + + <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> + 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> + </listitem> + <listitem> + <para>Alternatively you can use the web based "admin-console" configration and monitoring program, to create a new + Connection Factory. Just have your RAR file name and needed configuration properties handly and fill out web form + and create the ConnectionFactory.</para> + </listitem> + + </itemizedlist> + </sect1> +</chapter> \ No newline at end of file Property changes on: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -1,137 +1,211 @@ <chapter id="introduction"> - <title>Connectors in Teiid</title> - <para>A connector handles all communications with individual enterprise information sources, which can include - databases, data feeds, flat files, etc.</para> - <para>A connector is used to:</para> + <title>Translators and Resource Adapters in Teiid</title> + + <para>To integrate data from a Enterprise Information System (EIS) into Teiid, Teiid requires two separate modules </para> <itemizedlist> <listitem> + <para>Translator</para> + </listitem> + <listitem> + <para>Resource Adapter (also sometimes called as Connector or J2EE Connector or JCA Connector or RAR file) </para> + </listitem> + </itemizedlist> + + <para>A Translator is used to:</para> + <itemizedlist> + <listitem> <para>Translate a Teiid-specific command into a native command.</para> </listitem> <listitem> <para>Execute the command.</para> </listitem> <listitem> - <para>Return batches of results.</para> + <para>Return batches of results in relational form.</para> </listitem> </itemizedlist> - <para>Teiid is responsible for reassembling the results from one or more connectors into an - answer for the user’s command.</para> - <para> - For a more detailed workflow, see the chapter - <link linkend="connector_api"> - <emphasis>“Connector API.”</emphasis> - </link> - </para> + + <para>A Resource Adapter is:</para> + <itemizedlist> + <listitem> + <para>Handle 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> + </listitem> + <listitem> + <para>Helps to execute the command and fetch results from source systems for a given Translator</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> + <sect1> - <title>Do You Need a New Connector?</title> - <para>Teiid provides several connectors for common enterprise information system types. If + <title>Do You Need a New Translator?</title> + <para>Teiid provides several translators for common enterprise information system types. If you can use one of these enterprise information systems, you do not need to develop a custom one. </para> - <para>Teiid offers the following connectors:</para> + <para>Teiid offers the following translators:</para> <itemizedlist> <listitem> <para> <emphasis>JDBC:</emphasis> - Connects to many relational databases. The JDBC Connector is validated against the following database - systems: Oracle, Microsoft SQL Server, IBM DB2, MySQL, Postgres, Derby, Sybase, H2, and HSQL. In addition, the JDBC Connector can + Works with many relational databases. The JDBC translator is validated against the following database + systems: Oracle, Microsoft SQL Server, IBM DB2, MySQL, Postgres, Derby, Sybase, H2, and HSQL. In addition, the JDBC Translator can often be used with other 3rd-party drivers and provides a wide range of extensibility options to specialize behavior against those drivers. </para> </listitem> <listitem> <para> - <emphasis>Text:</emphasis> - Connects to text files. + <emphasis>File:</emphasis> + Provides a procedural way to access the file system to handle text files. </para> </listitem> <listitem> <para> - <emphasis>XML</emphasis> - Connects to XML files on disk or by invoking Web services on other enterprise systems. + <emphasis>XML:</emphasis> Provides a procedural way to access XML content on the File system or in a Web-Service. </para> </listitem> <listitem> <para> - <emphasis>LDAP</emphasis> - Connects to LDAP directory services. + <emphasis>LDAP:</emphasis> Accesses to LDAP directory services. </para> </listitem> <listitem> <para> - <emphasis>Salesforce</emphasis> - Connects to Salesforce. + <emphasis>Salesforce:</emphasis> Works with Salesforce interfaces. </para> </listitem> </itemizedlist> + </sect1> <sect1> - <title>Required Items to Write a Custom Connector</title> - <para>To write a connector, follow this procedure:</para> + <title>Do You Need a New Resource Adapter?</title> + <para>As mentioned above, for every Translator that needs to gather data from external source systems, it requires a resource adapter. + The following resource adapters are provided by Teiid distribution to work with above Translators. + </para> + + <itemizedlist> + <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> + </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> + </listitem> + <listitem> + <para> + <emphasis>LDAP:</emphasis> Provides JEE JCA connector to access LDAP; Used by the LDAP Translator. + </para> + </listitem> + <listitem> + <para> + <emphasis>Salesforce:</emphasis> Provides JEE JCA connector to access Salesforce by invoking their Web Service interface. Used by the SalesForce Translator. + </para> + </listitem> + </itemizedlist> + <para></para> + </sect1> + + <sect1> + <title>Required Items to Write a Custom Translator</title> + <para>To write a translator, follow this procedure:</para> <orderedlist numeration="arabic"> <listitem> - <para>Gather all necessary information about your Enterprise Information System (EIS). You will need - to know:</para> + <para>Create a new or use a Resource Adapater for the EIS system, to be used with this Translator</para> + </listitem> + <listitem> + <para>Implement the required interfaces defined by the Translator API.</para> <itemizedlist> <listitem> - <para>API for accessing the system</para> + <para>ExecutionFactory – Extend org.teiid.translator.ExecutionFactory class</para> </listitem> <listitem> - <para>Configuration and connection information for the system</para> + <para>Execution (and sub-interfaces) – specifies how to execute each type of command</para> </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>Define the Template for exposing configuration properties</para> + </listitem> + <listitem> + <para>Deploy your Translator into Teiid.</para> + <itemizedlist> <listitem> - <para>Expectation for incoming queries/metadata</para> + <para>Deploy a Virtual Database (VDB) with metadata corresponding to your Translator</para> </listitem> - <listitem> - <para>The processing constructs, or capabilities, supported by information system.</para> - </listitem> - <listitem> - <para>Required properties for the connector, such as URL, user name, etc.</para> - </listitem> </itemizedlist> </listitem> <listitem> - <para>Implement the required interfaces defined by the Connector API.</para> + <para>Execute queries via Teiid.</para> + </listitem> + </orderedlist> + <para> + This guide covers how to do each of these steps in detail. It also provides additional information for + advanced topics, such as connection pooling, streaming large objects, and transactions. For a sample + Translator code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">... source code</ulink> + </para> + </sect1> + + <sect1> + <title>Required Items to write a JEE JCA based Custom Resource Adaptor</title> + <para>To write a resource adaptor, follow this procedure:</para> + <orderedlist numeration="arabic"> + <listitem> + <para>The specification is defined by the <ulink url="http://java.sun.com/j2ee/connector/">JEE JCA Connector</ulink>. + You need to have basic idea about what JCA connectors are how they are developed and packaged.</para> + </listitem> + <listitem> + <para>Gather all necessary information about your Enterprise Information System (EIS). You will need + to know:</para> <itemizedlist> <listitem> - <para>Connector – starting point.</para> + <para>API for accessing the system</para> </listitem> <listitem> - <para>Connection – represents a connection to the source.</para> + <para>Configuration and connection information for the system</para> </listitem> <listitem> - <para>ConnectorCapabilities – specifies what kinds of commands your connector can - execute</para> + <para>Expectation for incoming queries/metadata</para> </listitem> <listitem> - <para>Execution (and sub-interfaces) – specifies how to execute each type of command</para> + <para>The processing constructs, or capabilities, supported by information system.</para> </listitem> + <listitem> + <para>Required properties for the connection, such as URL, user name, etc.</para> + </listitem> </itemizedlist> </listitem> <listitem> - <para>Test your connector with Connector Development Kit (CDK) test utilities.</para> - </listitem> - <listitem> - <para>Deploy your connector type into Teiid.</para> + <para>All the required supporting JCA SPI classes provided by the Teiid API. The JCA CCI support is not provided from Teiid</para> <itemizedlist> <listitem> - <para>Create and import your connector type definition file.</para> + <para>BasicConnectionFactory – Defines the Connection Factory</para> </listitem> <listitem> - <para>Create a connector binding using the connector type</para> + <para>BasicConnection – represents a connection to the source.</para> </listitem> <listitem> - <para>Deploy a Virtual Database with metadata corresponding to your EIS</para> + <para>BasicResourceAdapter – Specifies the resource adapter class</para> </listitem> </itemizedlist> </listitem> <listitem> - <para>Execute queries via Teiid.</para> + <para>Package your resource adapter.</para> + </listitem> + <listitem> + <para>Deploy your resource adapter into Teiid.</para> </listitem> </orderedlist> <para> This guide covers how to do each of these steps in detail. It also provides additional information for - advanced topics, such as connection pooling, streaming large objects, and transactions. For a sample - connector code, please check the <ulink url="http://teiid.org">Teiid community</ulink> + advanced topics such as streaming large objects and transactions. For a sample + connector code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">... Source code</ulink> </para> - </sect1> + </sect1> </chapter> \ No newline at end of file Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml 2010-06-10 23:09:17 UTC (rev 2218) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml 2010-06-10 23:14:14 UTC (rev 2219) @@ -1,9 +1,8 @@ <chapter id="lob_support"> <title>Handling Large Objects</title> <para>This chapter examines how to use facilities provided by the Teiid - Connector API to - use large objects such as blobs, clobs, and xml in - your connector.</para> + API to use large objects such as blobs, clobs, and xml in + your Translator.</para> <sect1> <title>Large Objects</title> @@ -11,115 +10,68 @@ <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 - connector - framework to support memory-safe streaming.  </para> + 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 Connector to return a large object through the - Teiid Connector API by just returning a reference to the actual + <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> + 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> + <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> + <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 + <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 - Connector 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> + <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 Connector API automatically handles large objects - (Blob/Clob/SQLXML) through - the creation of special purpose wrapper - objects when it retrieves results. + <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 - connectors.</para> + 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 connector 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.</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>Now the connector execution - only when the user Statement object - is closed.  - Note that connectors may at their discretion have - executions delayed in their closure by directly setting the keep - alive on the ExecutionContext - </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> - <para>An important limitation of using the LOB type objects - is that - streaming is not supported from remote connectors. - This is an issue in - clustered environments if connectors intended to return - LOBs are - deployed on only - a subset of the hosts or in failover situations. The - most appropriate - workaround to this - limitation is to deploy connectors - intended to return LOBs on each host in the - cluster.</para> </sect1> <sect1> <title>Inserting or Updating Large Objects</title> - <para>LOBs will be passed to the Connector in the - language objects as - an - ILiteral 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> + <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