[teiid-commits] teiid SVN: r1345 - in trunk: documentation/admin-guide/src/main/docbook/en-US and 9 other directories.

Author: shawkins Date: 2009-09-13 09:39:12 -0400 (Sun, 13 Sep 2009) New Revision: 1345 Added: trunk/documentation/docbook/custom.dtd Removed: trunk/documentation/docbook/en-US/custom.dtd Modified: trunk/connector-api/src/main/java/org/teiid/connector/api/ProcedureExecution.java trunk/connector-api/src/main/java/org/teiid/connector/api/ResultSetExecution.java trunk/connector-api/src/main/java/org/teiid/connector/api/UpdateExecution.java trunk/documentation/admin-guide/src/main/docbook/en-US/adminshell_guide.xml 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/command-language.xml 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-api.xml 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-development-kit.xml trunk/documentation/docbook/en-US/legal_notice.xml trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml trunk/documentation/quick-start-example/src/main/docbook/en-US/quick_start_example.xml trunk/documentation/reference/src/main/docbook/en-US/Reference.xml trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/salesforce_connector_guide.xml trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml Log: TEIID-104 finishing the update of the connector developer's guide. at this point all images have been removed. Modified: trunk/connector-api/src/main/java/org/teiid/connector/api/ProcedureExecution.java =================================================================== --- trunk/connector-api/src/main/java/org/teiid/connector/api/ProcedureExecution.java 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/connector-api/src/main/java/org/teiid/connector/api/ProcedureExecution.java 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,12 +24,12 @@ import java.util.List; +import org.teiid.connector.language.IProcedure; + /** - * The procedure execution represents the case where a connector can - * execute a procedural call (such as a stored procedure). This command - * takes a procedure with input values and executes the procedure. The - * output may include 0 or more output parameters and optionally a result - * set. + * The procedure execution represents the case where a connector can execute a + * {@link IProcedure}. The output may include 0 or more output parameters and + * optionally a result set. */ public interface ProcedureExecution extends ResultSetExecution { Modified: trunk/connector-api/src/main/java/org/teiid/connector/api/ResultSetExecution.java =================================================================== --- trunk/connector-api/src/main/java/org/teiid/connector/api/ResultSetExecution.java 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/connector-api/src/main/java/org/teiid/connector/api/ResultSetExecution.java 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,12 +24,22 @@ import java.util.List; +import org.teiid.connector.language.IProcedure; +import org.teiid.connector.language.IQueryCommand; - /** + * Defines an execution for {@link IQueryCommand}s and {@link IProcedure}s that + * returns a resultset, which is represented through the iterator method + * {@link #next()}. */ public interface ResultSetExecution extends Execution { + /** + * Retrieves the next row of the resultset. + * @return the next row or null indicating that there are no more results + * @throws ConnectorException + * @throws DataNotAvailableException + */ List<?> next() throws ConnectorException, DataNotAvailableException; } Modified: trunk/connector-api/src/main/java/org/teiid/connector/api/UpdateExecution.java =================================================================== --- trunk/connector-api/src/main/java/org/teiid/connector/api/UpdateExecution.java 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/connector-api/src/main/java/org/teiid/connector/api/UpdateExecution.java 2009-09-13 13:39:12 UTC (rev 1345) @@ -22,13 +22,24 @@ package org.teiid.connector.api; +import org.teiid.connector.language.IBatchedUpdates; +import org.teiid.connector.language.IDelete; +import org.teiid.connector.language.IInsert; +import org.teiid.connector.language.IUpdate; + /** * The update execution represents the case where a connector can - * execute an INSERT, UPDATE, or DELETE command. + * execute an {@link IInsert}, {@link IUpdate}, {@link IDelete}, or {@link IBatchedUpdates} command. */ public interface UpdateExecution extends Execution { + /** + * Returns the update counts for the execution. + * @return the update counts corresponding to the command executed + * @throws DataNotAvailableException + * @throws ConnectorException + */ int[] getUpdateCounts() throws DataNotAvailableException, ConnectorException; } Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/adminshell_guide.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/adminshell_guide.xml 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/adminshell_guide.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,7 +24,7 @@ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> %CustomDTD; ]> 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 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,7 +24,7 @@ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> %CustomDTD; ]> 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 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -1,3 +1,7 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> +%CustomDTD; +]> <chapter id="command_language"> <title>Command Language</title> @@ -13,16 +17,21 @@ <link linkend="connector_capabilities">Connector Capabilities</link> for more information. </para> - <para>The language interfaces all extend from the main interface, - ILanguageObject. They should be thought of as a tree where each node is a + <para>The language interfaces all extend from the ILanguageObject 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.</para> + Important components of + these commands are expressions, criteria, and + joins, which are examined + in closer detail below. Also see the + <ulink url="&javaDocUrl;">Teiid JavaDocs</ulink> + for more on the classes and interfaces described here. + </para> <sect2> <title>Expressions</title> <para>An expression represents a single value in context, although in @@ -116,10 +125,10 @@ </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 only one IFromItem, an IJoin. This latter form + 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.</para> + ConnectorCapability.useAnsiJoin return true. See <link linkend="command_form_capabilities">Command Form Capabilities</link> for more.</para> </sect2> <sect2> <title>IQueryCommand Structure</title> @@ -229,7 +238,7 @@ <sect1> <title>Runtime Metadata</title> - <para>Teiid uses a library of metadata, known as “runtime metadata” for + <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> @@ -242,10 +251,10 @@ <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> <itemizedlist> - <listitem><para>IElement</para></listitem> - <listitem><para>IGroup</para></listitem> - <listitem><para>IProcedure</para></listitem> - <listitem><para>IParameter</para></listitem> + <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> </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> @@ -291,27 +300,74 @@ <sect2> <title>Framework</title> - <para>The Connector API provides a language visitor framework in the com.metamatrix.data.visitor.framework package.   The framework provides utilities useful in navigating and extracting information from trees of language objects.</para> - - <para>The visitor framework is a variant of the Visitor design pattern, which is documented in several popular design pattern references.  The visitor pattern encompasses two primary operations: traversing the nodes of a graph (also known as iteration) and performing some action at each node of the graph.  In this case, the nodes are language interface objects and the graph is really a tree rooted at some node.  The provided framework allows for customization of both aspects of visiting.</para> - <para>The base LanguageObjectVisitor class defines the visit methods for all leaf language interfaces that can exist in the tree.  The LanguageObject interface defines an acceptVisitor() method – this method will call back on the visit method of the visitor to complete the contract.  A base class with empty visit methods is provided as AbstractLanguageVisitor.  The AbstractLanguageVisitor is just a visitor shell – it performs no actions when visiting nodes and does not provide any iteration.</para> - <para>The HierarchyVisitor provides the basic code for walking a language object tree.  The HierarchyVisitor performs no action as it walks the tree – it just encapsulates the knowledge of how to walk it.  If your connector 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 HierarchyVisitor that provides the ability to perform a different visitor’s processing before and after iteration.  This allows users of this class to implement either pre- or post-order processing based on the HierarchyVisitor.  Two helper methods are provided on DelegatingHierarchyVisitor to aid in executing pre- and post-order visitors.   </para> + <para>The Connector API provides a language visitor framework in the + org.teiid.connector.visitor.framework package.   The framework + provides utilities useful in navigating and extracting information + from trees of language objects.</para> + + <para>The visitor framework is a variant of the Visitor design pattern, + which is documented in several popular design pattern references.  The + visitor pattern encompasses two primary operations: traversing the + nodes of a graph (also known as iteration) and performing some action + at each node of the graph.  In this case, the nodes are language + interface objects and the graph is really a tree rooted at some node. +  The provided framework allows for customization of both aspects of + visiting.</para> + <para>The base LanguageObjectVisitor class defines the visit methods + for all leaf language interfaces that can exist in the tree.  The + LanguageObject interface defines an acceptVisitor() method – this + method will call back on the visit method of the visitor to complete + the contract.  A base class with empty visit methods is provided as + AbstractLanguageVisitor.  The AbstractLanguageVisitor is just a + visitor shell – it performs no actions when visiting nodes and does + not provide any iteration.</para> + <para>The HierarchyVisitor provides the basic code for walking a + language object tree.  The HierarchyVisitor performs no action as it + walks the tree – it just encapsulates the knowledge of how to walk it. +  If your connector 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 + HierarchyVisitor that provides the ability to perform a different + visitor’s processing before and after iteration.  This allows users of + this class to implement either pre- or post-order processing based on + the HierarchyVisitor.  Two helper methods are provided on + DelegatingHierarchyVisitor to aid in executing pre- and post-order + visitors.   </para> </sect2> <sect2> <title>Provided Visitors</title> - <para>The SQLStringVisitor is a special visitor that can traverse a tree of language interfaces and output the equivalent Teiid SQL.  This visitor can be used to print language objects for debugging and logging.  The SQLStringVisitor does not use the HierarchyVisitor described in the last section; it provides both iteration and processing type functionality in a single custom visitor.    </para> - <para>The CollectorVisitor is a handy utility to collect all language objects of a certain type in a tree. Some additional helper methods exist to do common tasks such as retrieving all elements in a tree, retrieving all groups in a tree, and so on.  </para> + <para>The SQLStringVisitor is a special visitor that can traverse a + tree of language interfaces and output the equivalent Teiid SQL.  This + visitor can be used to print language objects for debugging and + logging.  The SQLStringVisitor does not use the HierarchyVisitor + described in the last section; it provides both iteration and + processing type functionality in a single custom visitor.    </para> + <para>The CollectorVisitor is a handy utility to collect all language + objects of a certain type in a tree. Some additional helper methods + exist to do common tasks such as retrieving all elements in a tree, + retrieving all groups in a tree, and so on.  </para> </sect2> <sect2> <title>Writing a Visitor</title> - <para>Writing your own visitor can be quite easy if you use the provided facilities.  If the normal method of iterating the language tree is sufficient, then just follow these steps:</para> - <para>Create a subclass of AbstractLanguageVisitor.  Override any visit methods needed for your processing.  For instance, if you wanted to count the number of elements in the tree, you need only override the visit(IElement) 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.  In many cases, it doesn’t matter, so if you’re not sure, use pre-order processing.</para> - <para>Write code to execute your visitor using the utility methods on DelegatingHierarchyVisitor:</para> + <para>Writing your own visitor can be quite easy if you use the + provided facilities.  If the normal method of iterating the language + tree is sufficient, then just follow these steps:</para> + <para>Create a subclass of AbstractLanguageVisitor.  Override any visit + methods needed for your processing.  For instance, if you wanted to + count the number of elements in the tree, you need only override the + visit(IElement) method.  Collect any state in local variables and + provide accessor methods for that state.</para> + <para>Decide whether to use pre-order or post-order iteration. Note + that visitation order is based upon syntax ordering of SQL clauses - + not processing order.</para> + <para>Write code to execute your visitor using the utility methods on + DelegatingHierarchyVisitor:</para> <programlisting><![CDATA[ // Get object tree -LanguageObject objectTree = … +ILanguageObject objectTree = … // Create your visitor initialize as necessary MyVisitor visitor = new MyVisitor(); @@ -322,30 +378,36 @@ // Retrieve state collected while visiting int count = visitor.getCount(); ]]></programlisting> - <para>Often it’s useful to create a static method implementing this sequence of calls within your visitor.</para> </sect2> </sect1> <sect1 id="connector_capabilities"> <title>Connector Capabilities</title> - <para>All connectors must return a ConnectorCapabilities class from the Connection.getCapabilities() 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 com.metamatrix.data.basic.BasicConnectorCapabilities. This capabilities class specifies that the connector only executes queries and does not support any capability. Teiid recommends that you extend this class and override the necessary methods to specify which capabilities your connector supports.  </para> - + <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> <sect2> <title>Capability Scope</title> - <para>The method ConnectorCapabilities.getScope() specifies the scope of a capabilities set. Currently, two scope modes are defined in ConnectorCapabilities.SCOPE: global and per user. Specifying the scope as global means that the capabilities are the same for all connections to this source. Specifying the scope as per user means that the capabilities are potentially different for each user, so capabilities cannot be cached between users.</para> - <para>The per user mode is significantly slower and usually not necessary, therefore Teiid recommends using the global mode if capabilities of a source are the same across all connections. The BasicConnectorCapabilities implementation specifies global scope.</para> + <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. + </para> </sect2> <sect2> - <title>Execution Modes</title> - <para>The method ConnectorCapabilities.supportsExecutionMode() is used by the Connector Manager to discover what kinds of commands the connector can support. Constants defining the available execution modes are specified in ConnectorCapabilities.EXECUTION_MODE. Your implementation of ConnectorCapabilities should return true from this method for each execution mode your connector supports.</para> - <para>The BasicConnectorCapabilities implementation specifies only that it supports the SYNCH_QUERY execution mode.</para> - </sect2> - <sect2> <title>Capabilities</title> <para>The following table lists the capabilities that can be specified in the ConnectorCapabilities class.</para> <table frame='all'> <title>Available Connector Capabilities</title> <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*" /> + <colspec colname='c1' colwidth="1.5*" /> <colspec colname='c2' colwidth="1*" /> <colspec colname='c3' colwidth="2*" /> <thead> @@ -375,39 +437,17 @@ </row> <row> <entry> - <para>Joins</para> + <para>SelectExpression</para> </entry> <entry> <para /> </entry> <entry> - <para>Connector can support joins.</para> + <para>Connector can support SELECT of more than just element references.</para> </entry> </row> <row> <entry> - <para>OuterJoins</para> - </entry> - <entry> - <para>Joins</para> - </entry> - <entry> - <para>Connector can support LEFT and RIGHT OUTER JOIN.</para> - </entry> - </row> - <row> - <entry> - <para>FullOuterJoins</para> - </entry> - <entry> - <para>Joins, OuterJoins</para> - </entry> - <entry> - <para>Connector can support FULL OUTER JOIN.</para> - </entry> - </row> - <row> - <entry> <para>AliasedGroup</para> </entry> <entry> @@ -420,199 +460,135 @@ </row> <row> <entry> - <para>SelfJoins</para> + <para>SupportedJoinCriteria</para> </entry> <entry> - <para>Joins, AliasedGroups</para> + <para>At least one 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>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>InlineViews</para> + <para>InnerJoins</para> </entry> <entry> - <para>AliasedGroup</para> + <para/> </entry> <entry> - <para>Connector can support a named subquery in the FROM clause.</para> + <para>Connector can support inner and cross joins</para> </entry> </row> <row> <entry> - <para>Criteria</para> + <para>SelfJoins</para> </entry> <entry> - <para /> + <para>AliasedGroups and at least on of the join type supports.</para> </entry> <entry> - <para>Connector can support WHERE and HAVING clauses.</para> + <para>Connector can support a self join between two aliased versions of the + same group.</para> </entry> </row> <row> <entry> - <para>RowLimit</para> + <para>OuterJoins</para> </entry> <entry> - <para> </para> + <para/> </entry> <entry> - <para>Connector can support the limit portion of the limit clause</para> + <para>Connector can support LEFT and RIGHT OUTER JOIN.</para> </entry> </row> <row> <entry> - <para>RowOffset</para> + <para>FullOuterJoins</para> </entry> <entry> - <para> </para> + <para/> </entry> <entry> - <para>Connector can support the offset portion of the limit clause</para> + <para>Connector can support FULL OUTER JOIN.</para> </entry> </row> <row> <entry> - <para>AndCriteria</para> + <para>InlineViews</para> </entry> <entry> - <para>Criteria</para> + <para>AliasedGroup</para> </entry> <entry> - <para>Connector can support AND criteria in join conditions of the FROM clause, - the WHERE clause, and the HAVING clause.</para> + <para>Connector can support a named subquery in the FROM clause.</para> </entry> </row> <row> <entry> - <para>OrCriteria</para> - </entry> - <entry> - <para>Criteria</para> - </entry> - <entry> - <para>Connector can support the OR logical criteria.</para> - </entry> - </row> - <row> - <entry> - <para>NotCriteria</para> - </entry> - <entry> - <para>Criteria</para> - </entry> - <entry> - <para>Connector can support the NOT logical criteria.</para> - </entry> - </row> - <row> - <entry> <para>BetweenCriteria</para> </entry> <entry> - <para>Criteria</para> + <para /> </entry> <entry> - <para>Connector can support the BETWEEN predicate criteria.</para> + <para>Not currently used - between criteria is rewriten as compound comparisions.</para> </entry> </row> <row> <entry> - <para>CompareCriteria</para> - </entry> - <entry> - <para>Criteria</para> - </entry> - <entry> - <para>Connector can support comparison criteria such as “age &gt; 10”.  </para> - </entry> - </row> - <row> - <entry> <para>CompareCriteriaEquals</para> </entry> <entry> - <para>Criteria, CompareCriteria</para> + <para/> </entry> <entry> - <para>Connector can support comparison criteria with the operator “=”.</para> + <para>Connector can support comparison criteria with the operator "=”.</para> </entry> </row> <row> <entry> - <para>CompareCriteriaGreaterThan</para> + <para>CompareCriteriaOrdered</para> </entry> <entry> - <para>Criteria, CompareCriteria</para> + <para/> </entry> <entry> - <para>Connector can support comparison criteria with the operator “&gt;”.</para> + <para>Connector can support comparison criteria with the operator "&gt;” or "&lt;".</para> </entry> </row> <row> <entry> - <para>CompareCriteriaGreaterThanOrEqual</para> + <para>LikeCriteria</para> </entry> <entry> - <para>Criteria, CompareCriteria</para> + <para/> </entry> <entry> - <para>Connector can support comparison criteria with the operator “&gt;=”.</para> + <para>Connector can support LIKE criteria.</para> </entry> </row> <row> <entry> - <para>CompareCriteriaLessThan</para> + <para>LikeCriteriaEscapeCharacter</para> </entry> <entry> - <para>Criteria, CompareCriteria</para> + <para>LikeCriteria</para> </entry> <entry> - <para>Connector can support comparison criteria with the operator “&lt;”.</para> + <para>Connector can support LIKE criteria with an ESCAPE character clause.</para> </entry> </row> <row> <entry> - <para>CompareCriteriaLessThanOrEqual</para> - </entry> - <entry> - <para>Criteria, CompareCriteria</para> - </entry> - <entry> - <para>Connector can support comparison criteria with the operator “&lt;=”.</para> - </entry> - </row> - <row> - <entry> - <para>CompareCriteriaNotEquals</para> - </entry> - <entry> - <para>Criteria, CompareCriteria</para> - </entry> - <entry> - <para>Connector can support comparison criteria with the operator “&lt;&gt;”.</para> - </entry> - </row> - <row> - <entry> - <para>ExistsCriteria</para> - </entry> - <entry> - <para>Criteria</para> - </entry> - <entry> - <para>Connector can support EXISTS predicate criteria.</para> - </entry> - </row> - <row> - <entry> <para>InCriteria</para> </entry> <entry> - <para>Criteria</para> + <para/> </entry> <entry> <para>Connector can support IN predicate criteria.</para> @@ -623,7 +599,7 @@ <para>InCriteriaSubquery</para> </entry> <entry> - <para>Criteria, InCriteria</para> + <para/> </entry> <entry> <para>Connector can support IN predicate criteria where values are supplied by a @@ -635,7 +611,7 @@ <para>IsNullCriteria</para> </entry> <entry> - <para>Criteria</para> + <para/> </entry> <entry> <para>Connector can support IS NULL predicate criteria.</para> @@ -643,36 +619,37 @@ </row> <row> <entry> - <para>LikeCriteria</para> + <para>OrCriteria</para> </entry> <entry> - <para>Criteria</para> + <para/> </entry> <entry> - <para>Connector can support LIKE criteria.</para> + <para>Connector can support the OR logical criteria.</para> </entry> </row> <row> <entry> - <para>LikeCriteriaEscapeCharacter</para> + <para>NotCriteria</para> </entry> <entry> - <para>Criteria, LikeCriteria</para> + <para/> </entry> <entry> - <para>Connector can support LIKE criteria with an ESCAPE character clause.</para> + <para>Connector can support the NOT logical criteria. IMPORTANT: This + capability also applies to negation of predicates, such as specifying + IS NOT NULL, "&lt;=" (not "&gt;"), "&gt;=" (not "&lt;"), etc.</para> </entry> </row> <row> <entry> - <para>QuantifiedCompareCriteria</para> + <para>ExistsCriteria</para> </entry> <entry> - <para>Criteria, CompareCriteria</para> + <para/> </entry> <entry> - <para>Connector can support a quantified comparison criteria with a subquery on the - right side.</para> + <para>Connector can support EXISTS predicate criteria.</para> </entry> </row> <row> @@ -680,7 +657,7 @@ <para>QuantifiedCompareCriteriaAll</para> </entry> <entry> - <para>Criteria, CompareCriteria, QuantifiedCompareCriteria</para> + <para/> </entry> <entry> <para>Connector can support a quantified comparison criteria using the ALL @@ -692,7 +669,7 @@ <para>QuantifiedCompareCriteriaSome</para> </entry> <entry> - <para>Criteria, CompareCriteria, QuantifiedCompareCriteria</para> + <para/> </entry> <entry> <para>Connector can support a quantified comparison criteria using the SOME or ANY @@ -712,21 +689,43 @@ </row> <row> <entry> - <para>Aggregates</para> + <para>OrderByUnrelated</para> </entry> <entry> + <para>OrderBy</para> + </entry> + <entry> + <para>Connector can support the ORDER BY items that are not directly specified in the select clause.</para> + </entry> + </row> + <row> + <entry> + <para>GroupBy</para> + </entry> + <entry> <para /> </entry> <entry> - <para>Connector can support GROUP BY and HAVING clauses in queries.</para> + <para>Connector can support an explict GROUP BY clause.</para> </entry> </row> <row> <entry> + <para>Having</para> + </entry> + <entry> + <para>GroupBy</para> + </entry> + <entry> + <para>Connector can support the HAVING clause.</para> + </entry> + </row> + <row> + <entry> <para>AggregatesAvg</para> </entry> <entry> - <para>Aggregates</para> + <para/> </entry> <entry> <para>Connector can support the AVG aggregate function.</para> @@ -737,7 +736,7 @@ <para>AggregatesCount</para> </entry> <entry> - <para>Aggregates</para> + <para/> </entry> <entry> <para>Connector can support the COUNT aggregate function.</para> @@ -748,7 +747,7 @@ <para>AggregatesCountStar</para> </entry> <entry> - <para>Aggregates, AggregatesCount</para> + <para/> </entry> <entry> <para>Connector can support the COUNT(*) aggregate function.</para> @@ -759,7 +758,7 @@ <para>AggregatesDistinct</para> </entry> <entry> - <para>Aggregates</para> + <para>At least one of the aggregate functions.</para> </entry> <entry> <para>Connector can support the keyword DISTINCT inside an aggregate function.  This @@ -771,7 +770,7 @@ <para>AggregatesMax</para> </entry> <entry> - <para>Aggregates</para> + <para/> </entry> <entry> <para>Connector can support the MAX aggregate function.</para> @@ -782,7 +781,7 @@ <para>AggregatesMin</para> </entry> <entry> - <para>Aggregates</para> + <para/> </entry> <entry> <para>Connector can support the MIN aggregate function.</para> @@ -793,7 +792,7 @@ <para>AggregatesSum</para> </entry> <entry> - <para>Aggregates</para> + <para/> </entry> <entry> <para>Connector can support the SUM aggregate function.</para> @@ -801,118 +800,115 @@ </row> <row> <entry> - <para>ScalarFunctions</para> + <para>ScalarSubqueries</para> </entry> <entry> <para /> </entry> <entry> - <para>Connector can support scalar functions wherever expressions are accepted. - </para> + <para>Connector can support the use of a subquery in a scalar context (wherever an + expression is valid).</para> </entry> </row> <row> <entry> - <para>CaseExpressions</para> + <para>CorrelatedSubqueries</para> </entry> <entry> - <para /> + <para>At least one of the subquery pushdown capabilities.</para> </entry> <entry> - <para>Connector can support “unsearched” CASE expressions anywhere that expressions - are accepted.</para> + <para>Connector can support a correlated subquery that refers to an element in + the outer query.</para> </entry> </row> <row> <entry> - <para>SearchedCaseExpressions</para> + <para>CaseExpressions</para> </entry> <entry> <para /> </entry> <entry> - <para>Connector can support “searched” CASE expressions anywhere that expressions are - accepted.</para> + <para>Not currently used - simple case is rewriten as searched case.</para> </entry> </row> <row> <entry> - <para>ScalarSubqueries</para> + <para>SearchedCaseExpressions</para> </entry> <entry> <para /> </entry> <entry> - <para>Connector can support the use of a subquery in a scalar context (wherever an - expression is valid).</para> + <para>Connector can support "searched” CASE expressions anywhere that expressions are + accepted.</para> </entry> </row> <row> <entry> - <para>CorrelatedSubqueries</para> + <para>Unions</para> </entry> <entry> - <para>ScalarSubqueries or QuantifiedCompareCriteria or ExistsCriteria or - InCriteriaSubquery</para> + <para /> </entry> <entry> - <para>Connector can support a correlated subquery that refers back to an element in - the outer query.</para> + <para>Connector support UNION and UNION ALL</para> </entry> </row> <row> <entry> - <para>SelectLiterals</para> + <para>Intersect</para> </entry> <entry> - <para /> + <para/> </entry> <entry> - <para>Connector can support literals in the SELECT clause</para> + <para>Connector supports INTERSECT</para> </entry> </row> <row> <entry> - <para>Unions</para> + <para>Except</para> </entry> <entry> - <para /> + <para/> </entry> <entry> - <para>Connector support UNIONs</para> + <para>Connector supports Except</para> </entry> </row> <row> <entry> - <para>Intersect</para> + <para>SetQueryOrderBy</para> </entry> <entry> - <para/> + <para>Unions, Intersect, or Except</para> </entry> <entry> - <para>Connector supports INTERSECT</para> + <para>Connector supports set queries with an ORDER BY</para> </entry> </row> <row> <entry> - <para>Except</para> + <para>RowLimit</para> </entry> <entry> <para/> </entry> <entry> - <para>Connector supports Except</para> + <para>Connector can support the limit portion of the limit clause</para> </entry> </row> <row> <entry> - <para>SetQueryOrderBy</para> + <para>RowOffset</para> </entry> <entry> - <para>Unions, Intersect, or Except</para> + <para/> </entry> <entry> - <para>Connector supports set queries with an ORDER BY</para> + <para>Connector can support the offset portion of the limit clause</para> </entry> </row> <row> @@ -920,45 +916,84 @@ <para>FunctionsInGroupBy</para> </entry> <entry> - <para>ScalarFunctions, Aggregates</para> + <para>GroupBy</para> </entry> <entry> - <para>Connector supports functions in the GROUP BY list</para> + <para>Not currently used - non-element expressions in the group by create an inline view.</para> </entry> </row> <row> <entry> - <para>FunctionsInGroupBy</para> + <para>InsertWithQueryExpression</para> </entry> <entry> - <para>ScalarFunctions, Aggregates</para> + <para/> </entry> <entry> - <para>Connector supports functions in the GROUP BY list</para> + <para>Connector supports INSERT statements with values specified by an IQueryCommand.</para> </entry> </row> </tbody> </tgroup> </table> + <para>Note that any pushdown subquery must itself be compliant with the + connector capabilities.</para> </sect2> - <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 INNER and CROSS joins that are pushed down.</para> - <para>The method ConnectorCapabilities.requiresCriteria() should return true if the Connector requires criteria for any Query, Update, or Delete. This is a replacement for the model support property "Where All".</para> + <para>The method ConnectorCapabilities.useAnsiJoin() should return true + if the Connector 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 + 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 set of possible functions is based on the set of functions supported by Teiid.  This set can be found in the Query Support Booklet documentation.  If the connector states that it supports a function, it must support all type combinations and overloaded forms of that function.</para> - <para>There are five operators that can also be specified in the supported function list: +, -, *, /, and ||.</para> + <para>The method ConnectorCapabilities.getSupportedFunctions() can be + used to specify which scalar functions the connector 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, + it must support all type combinations and overloaded forms of that + function.</para> + <para>There are also five standard operators that can also be specified in the + supported function list: +, -, *, /, and ||.</para> + <para>The constants interface SourceSystemFunctions contains the string + names of all possible built-in pushdown functions. Note that not all + system functions appear in this list. This is because some system + functions will always be evaluted in Teiid, are simple aliases to + other functions, or are rewriten to a more standard expression.</para> </sect2> <sect2> <title>Physical Limits</title> - <para>The method ConnectorCapabilities.getMaxInCriteriaSize() can be used to specify the maximum number of values that can be passed in an IN criteria.  This is an important constraint as an IN criteria is frequently used to pass criteria between one source and another using a dependent join.</para> - <para>The method ConnectorCapabilities.getMaxFromGroups() can be used to specify the maximum number of FROM Clause groups that can used in a join. -1 indicates there is no limit.</para> + <para>The method ConnectorCapabilities.getMaxInCriteriaSize() can be + used to specify the maximum number of values that can be passed in an + IN criteria.  This is an important constraint as an IN criteria is + frequently used to pass criteria between one source and another using + a dependent join.</para> + <para>The method ConnectorCapabilities.getMaxFromGroups() can be used + to specify the maximum number of FROM Clause groups that can used in a + join. -1 indicates there is no limit.</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> + <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> + </sect2> + </sect1> </chapter> \ No newline at end of file Modified: 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 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -5,7 +5,7 @@ <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 situaions, + 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 @@ -198,14 +198,14 @@ <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.</para> + 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='3' align='left' colsep='1' rowsep='1'> + <tgroup cols='4' align='left' colsep='1' rowsep='1'> <colspec colname='c1' colwidth=".5*" /> - <colspec colname='c1' colwidth="1*" /> - <colspec colname='c2' colwidth=".25*" /> - <colspec colname='c3' colwidth="2*" /> + <colspec colname='c2' colwidth="1*" /> + <colspec colname='c3' colwidth=".25*" /> + <colspec colname='c4' colwidth="1*" /> <thead> <row> <entry> @@ -259,8 +259,7 @@ <para>Pool Maximum Connections</para> </entry> <entry> - <para>com.metamatrix.data. - ~pool.max_connections + <para>*.max_connections </para> </entry> <entry> @@ -276,8 +275,7 @@ <para>Pool Maximum Connections for Each ID</para> </entry> <entry> - <para>com.metamatrix.data. - ~pool.max_connections_for_each_id + <para>*.max_connections_for_each_id </para> </entry> <entry> @@ -293,8 +291,7 @@ <para>Pool Connection Idle Time (seconds)</para> </entry> <entry> - <para>com.metamatrix.data. - ~pool.live_and_unused_time + <para>*.live_and_unused_time </para> </entry> <entry> @@ -310,8 +307,7 @@ <para>Pool Connection Waiting Time (milliseconds)</para> </entry> <entry> - <para>com.metamatrix.data. - ~pool.wait_for_source_time + <para>*.wait_for_source_time </para> </entry> <entry> @@ -327,8 +323,7 @@ <para>Pool cleaning Interval (seconds)</para> </entry> <entry> - <para>com.metamatrix.data. - ~pool.cleaning_interval + <para>*.cleaning_interval </para> </entry> <entry> @@ -344,8 +339,7 @@ <para>Enable Pool Shrinking</para> </entry> <entry> - <para>com.metamatrix.data. - ~pool.enable_shrinking + <para>*.enable_shrinking </para> </entry> <entry> 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 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -1,5 +1,5 @@ <!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/en-US/custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> %CustomDTD; ]> <chapter id="connector_api"> @@ -303,11 +303,15 @@ binding property SynchWorkers to false - this overrides the default behavior in which connector threads stay associated with their Execution until the Execution is closed.</para> + </listitem> + <listitem> <para>Throw a DataNotAvailableExecption during a retrival method, rather than explicitly waiting or sleeping for the results. The DataNotAvailableException may take a delay parameter in its constructor to indicate how long the system should wait befor polling for results. Any non-negative value is allowed. </para> + </listitem> + <listitem> <para>Be aware that a connector with asynchronous workers cannot be transactional.</para> </listitem> </itemizedlist> Modified: 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 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -1,3 +1,7 @@ +<!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> @@ -4,7 +8,7 @@ <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 a Teiid Server:</para> + steps to deploy your connector to Teiid:</para> <itemizedlist> <listitem> <para>Creating a Connector Type Definition file that defines the properties required @@ -19,9 +23,6 @@ file and the Extension Modules.</para> </listitem> <listitem> - <para>Importing the Connector Archive file in the Teiid Console.</para> - </listitem> - <listitem> <para>Creating a Connector Binding using your Connector Type.</para> </listitem> </itemizedlist> @@ -42,11 +43,13 @@ also be created using the Connector Development Kit.</para> <sect2> - <title>Required Properties</title> - <para>The Connector API requires the following properties for Teiid to load - and use your connector.</para> + <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>Required Connector Properties</title> + <title>Connector Properties</title> <tgroup cols='3' align='left' colsep='1' rowsep='1'> <colspec colname='c1' colwidth="1*"/> <colspec colname='c2' colwidth="1*"/> @@ -54,7 +57,7 @@ <thead> <row> <entry> - <para>Property Attribute</para> + <para>Property Name</para> </entry> <entry> <para>Example Value</para> @@ -82,7 +85,7 @@ <para>ConnectorClassPath</para> </entry> <entry> - <para>extensionjar:mycode.jar;</para> + <para>extensionjar:foo.jar</para> </entry> <entry> <para>Semi-colon delimited list of jars defining the classpath of this @@ -99,7 +102,7 @@ <sect2> <title>Connector Properties</title> - <para>Most connectors will require some initialization parameters to connect to the + <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> @@ -107,7 +110,7 @@ Teiid Console to integrate the connector seamlessly into Teiid.</para> <table frame='all'> - <title>All Properties</title> + <title>All Attributes</title> <tgroup cols='3' align='left' colsep='1' rowsep='1'> <colspec colname='c1' colwidth="1*"/> <colspec colname='c2' colwidth="1*"/> @@ -115,7 +118,7 @@ <thead> <row> <entry> - <para>Property Name</para> + <para>Attribute Name</para> </entry> <entry> <para>Example Value</para> @@ -238,37 +241,47 @@ </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>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> - - <sect2> - <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> + <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>Each connector is started in an isolated classloader instance. This classloader loads - classes via the Teiid Extension Modules before loading classes from Teiid - classpath. Ideally, all of your connector classes should be loaded from extension modules, - which are configured in the Teiid Console.  </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> + <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 @@ -303,50 +316,25 @@ <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 to Chapter 4 for more information on the CDK tool</para> + “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 Server</title> - <para>To use a new connector type definition in Teiid, the Connector Archive - file must be imported in the Teiid Console or using the Admin API.  To perform this task, - perform the following steps:</para> - <orderedlist> - <listitem> - <para>Start the Teiid Console and connect to your Teiid Server.</para> - </listitem> - <listitem> - <para>Select Connector Types from the tree at the left of the Console.  This will - display a list of existing Connector Types on the right.</para> - </listitem> - <listitem> - <para>Click the Import… button on the bottom of the Connector Type list.  This will - open the Import Connector Type Wizard.</para> - </listitem> - <listitem> - <para>Select your Connector Archive file and click the Next button.</para> - </listitem> - <listitem> - <para>Click Finish to create the Connector Type.  At this point you will see the new - Connector Type in the list of Connector Types.  </para> - </listitem> - <listitem> - <para>Select Extension Modules from the tree at the left of the Console, and make sure - all the required Extension Modules are added.</para> - </listitem> - </orderedlist> + <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 Enterprise or Dimension Designer</title> + <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 the Enterprise or Dimension designer</para> + <para>Start Designer</para> </listitem> <listitem> <para>Open the project and in the “vdb” execute panel, click on the “Open the @@ -367,58 +355,17 @@ <title>Creating a Connector Binding</title> <sect2> - <title>In Console</title> - <para>To actually use your connector in Teiid, you must create a Connector - Binding that specifies the specific property values for an instance of the Connector Type.  To - create a Connector Binding, perform the following steps:</para> - <orderedlist> - <listitem> - <para>Start the Teiid Console and connect to your Teiid Server.</para> - </listitem> - <listitem> - <para>Select Connector Bindings from the tree at the left of the Console.  This will - display a list of existing Connector Bindings on the right.</para> - </listitem> - <listitem> - <para>Click the New… button below the list of Connector Bindings.  This will launch the - Create New Connector Binding Wizard.  </para> - </listitem> - <listitem> - <para>In Step 1, you must specify a name for your connector binding and select your - connector type from the Connector Type list.  Click the Next button to continue.</para> - </listitem> - <listitem> - <para>In Step 2, the connector properties from your connector type definition file will be - displayed.  Default values are used to pre-fill the value fields if they exist.  Required - properties are displayed with bold text.  Required properties with no value specified are - displayed in red text.  These fields must be completed before the Next button will enable. -  Optional properties may be displayed by checking the Optional Properties checkbox.  When - you have completed all required values, click the Next button.</para> - </listitem> - <listitem> - <para>In Step 3, you are given the opportunity to set the enabled state of the new binding - in each PSC.  Typically, no modifications need to be made.  For more information, see the - Teiid Console User’s Guide.  Click the Finish button to complete the wizard and - create your connector binding.  The Connector Binding list now displays your new connector - binding.  </para> - </listitem> - </orderedlist> - <para>To actually start your connector binding, please consult the Teiid Console User’s - Guide for detailed information.</para> - </sect2> - - <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 Enterprise Designer User’s Guide.</para> + 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 deployed to Teiid using the Console to correct resources.</para> + when a VDB is later deployed.</para> </sect2> </sect1> </chapter> \ No newline at end of file Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-development-kit.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-development-kit.xml 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-development-kit.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -1,169 +1,200 @@ +<!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_development_kit"> - <title>Using the Connector Development Kit</title> - <sect1> - <title>Overview</title> - <para>The Connector Developer Kit (CDK) is a set of programmatic and command line utilities - for testing connectors.  The programmatic components of the CDK are useful for unit testing - your connector and the command line utilities is useful for integration testing and regression - testing (due to scripting abilities).</para> - <para>This chapter covers usage of both aspects of the CDK.  For more detailed information - about the CDK programmatic utilities, please see the Connector API Javadoc, which include the - CDK Javadoc.</para> - </sect1> - <sect1> - <title>Programmatic Utilities</title> - <para>All components provided by the CDK are in the package com.metamatrix.cdk.api.  </para> - <sect2> - <title>Language Translation</title> - <para>Commands are sent to the Connector API in terms of the language interfaces - discussed earlier in this guide.  Typically, a connector must write logic to read and - sometimes manipulate these objects.  The CDK language translation utilities can be used to - write unit tests for translation code or command execution.</para> - <para>The utilities are provided in the class TranslationUtility.  This class has the - following methods:</para> - - <table frame='all'> - <title>Language Translation</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*" /> - <colspec colname='c2' colwidth="2*" /> - <thead> - <row> - <entry> - <para>Method Name</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>TranslationUtility(String vdbFile)</para> - </entry> - <entry> - <para>Constructor – takes the path to a file which is a valid metadata - archive created by the Teiid Designer.  These files have the suffix “.vdb”.   + <title>Using the Connector Development Kit</title> + <sect1> + <title>Overview</title> + <para>The Connector Developer Kit (CDK) is a set of programmatic and + command line utilities + for testing connectors.  The programmatic components of the CDK are + useful for unit testing + your connector and the command line utilities is useful for integration + testing and regression + testing (due to scripting abilities).</para> + <para>This chapter covers usage of both aspects of the CDK.  For more + detailed information + about the CDK programmatic utilities also consult the <ulink url="&javaDocUrl;">Teiid JavaDocs</ulink>.</para> + </sect1> + <sect1> + <title>Programmatic Utilities</title> + <para>All components provided by the CDK are in the package + com.metamatrix.cdk.api.  </para> + <sect2> + <title>Language Translation</title> + <para> + Commands are sent to the Connector API in terms of the language + interfaces + discussed in the + <link linkend="command_language">Command Language</link> + chapter.  Typically, a connector must write logic to read and + sometimes manipulate these objects.  The CDK language translation + utilities can be used to + write unit tests for translation code or command execution. + </para> + <para>The utilities are provided in the class TranslationUtility. +  This class has the + following methods:</para> + + <table frame='all'> + <title>Language Translation</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*" /> + <colspec colname='c2' colwidth="2*" /> + <thead> + <row> + <entry> + <para>Method Name</para> + </entry> + <entry> + <para>Description</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>TranslationUtility(String vdbFile)</para> + </entry> + <entry> + <para>Constructor – takes the path to a file which is a valid + metadata + archive created by the Teiid Designer.  These files have the suffix + “.vdb”.   </para> - </entry> - </row> - <row> - <entry> - <para>createRuntimeMetadata()</para> - </entry> - <entry> - <para>Creates an instance of RuntimeMetadata that can be used to test code - that uses runtime metadata when translating or executing commands.</para> - </entry> - </row> - <row> - <entry> - <para>parseCommand(String sql)</para> - </entry> - <entry> - <para>Take a single-source command and return an ICommand that can be used to - test translation or execution of commands.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect2> - - <sect2> - <title>Command Execution</title> - <para>The primary purpose of a Connector is to execute commands against an information - source.  The query execution utilities allow you to test the execution of commands - programmatically.  This utility does not run the Teiid query engine or the connector - manager although does simulate what happens when those components use a Connector to execute - a command.</para> - <para>The command execution utilities are provided in the class ConnectorHost.  This class - has the following methods:</para> - - <table frame='all'> - <title>Command Execution</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*" /> - <colspec colname='c2' colwidth="2*" /> - <thead> - <row> - <entry> - <para>Method Name</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>ConnectorHost</para> - </entry> - <entry> - <para>Constructor – takes a Connector instance, a set of connector - property values, and the path to a VDB archive file</para> - </entry> - </row> - <row> - <entry> - <para>setBatchSize</para> - </entry> - <entry> - <para>Sets the batch size to use when executing commands.</para> - </entry> - </row> - <row> - <entry> - <para>setExecutionContext</para> - </entry> - <entry> - <para>Sets the security context values currently being used to execute commands. -  This method may be called multiple times during the use of a single instance of - ConnectorHost to change the current context.</para> - </entry> - </row> - <row> - <entry> - <para>getConnectorEnvironmentProperties</para> - </entry> - <entry> - <para>Helper method to retrieve the properties passed to the ConnectorHost - constructor.</para> - </entry> - </row> - <row> - <entry> - <para>executeCommand</para> - </entry> - <entry> - <para>Execute a command and return the results using this connector.</para> - </entry> - </row> - <row> - <entry> - <para>executeBatchedUpdates</para> - </entry> - <entry> - <para>Execute a set of commands as a batched update.</para> - </entry> - </row> - <row> - <entry> - <para>getCommand</para> - </entry> - <entry> - <para>Use the host metadata to get the ICommand for a SQL string.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - <para /> - <para>Here is some example code showing how to use ConnectorHost to test a connector: + </entry> + </row> + <row> + <entry> + <para>createRuntimeMetadata()</para> + </entry> + <entry> + <para>Creates an instance of RuntimeMetadata that can be used to + test code + that uses runtime metadata when translating or executing commands. + </para> + </entry> + </row> + <row> + <entry> + <para>parseCommand(String sql)</para> + </entry> + <entry> + <para>Take a single-source command and return an ICommand that + can be used to + test translation or execution of commands.</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2> + <title>Command Execution</title> + <para>The primary purpose of a Connector is to execute commands + against an information + source.  The query execution utilities allow you to test the execution of + commands + programmatically.  This utility does not run the Teiid query engine or the connector + manager although does simulate what happens when those components + use a Connector to execute + a command.</para> + <para>The command execution utilities are provided in the class + ConnectorHost.  This class + has the following methods:</para> + + <table frame='all'> + <title>Command Execution</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*" /> + <colspec colname='c2' colwidth="1.25*" /> + <thead> + <row> + <entry> + <para>Method Name</para> + </entry> + <entry> + <para>Description</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>ConnectorHost</para> + </entry> + <entry> + <para>Constructor – takes a Connector instance, a set of + connector + property values, and the path to a VDB archive file</para> + </entry> + </row> + <row> + <entry> + <para>setBatchSize</para> + </entry> + <entry> + <para>Sets the batch size to use when executing commands.</para> + </entry> + </row> + <row> + <entry> + <para>setExecutionContext</para> + </entry> + <entry> + <para>Sets the security context values currently being used to + execute commands. +  This method may be called multiple times during the use of a single + instance of + ConnectorHost to change the current context.</para> + </entry> + </row> + <row> + <entry> + <para>getConnectorEnvironmentProperties</para> + </entry> + <entry> + <para>Helper method to retrieve the properties passed to the + ConnectorHost + constructor.</para> + </entry> + </row> + <row> + <entry> + <para>executeCommand</para> + </entry> + <entry> + <para>Execute a command and return the results using this + connector.</para> + </entry> + </row> + <row> + <entry> + <para>executeBatchedUpdates</para> + </entry> + <entry> + <para>Execute a set of commands as a batched update.</para> + </entry> + </row> + <row> + <entry> + <para>getCommand</para> + </entry> + <entry> + <para>Use the host metadata to get the ICommand for a SQL + string.</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para /> + <para>Here is some example code showing how to use ConnectorHost to + test a connector: </para> - <programlisting><![CDATA[ + <programlisting><![CDATA[ // Prepare state for testing MyConnector connector = new MyConnector(); Properties props = new Properties(); @@ -180,552 +211,604 @@ // Compare actual results to expected results // . . . ]]></programlisting> - <para>The executeCommand() method will return results as a List of rows.  Each row is - itself a List of objects in column order.  So, each row should have the same number of items - corresponding to the columns in the SELECT clause of the query.  In the case of an INSERT, - UPDATE, or DELETE, a single “row” will be returned with a single column that contains the - update count.</para> - </sect2> - - </sect1> - - <sect1> - <title>Connector Environment</title> - <para>Many parts of the Connector API require use of the Connector Environment.  The - EnvironmentUtility can be used to obtain and control a Connector Environment instance.</para> - - <table frame='all'> - <title>Command Execution</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*" /> - <colspec colname='c2' colwidth="2*" /> - <thead> - <row> - <entry> - <para>Method Name</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>createExecutionContext</para> - </entry> - <entry> - <para>Creates a ExecutionContext instance.</para> - </entry> - </row> - <row> - <entry> - <para>createStdoutLogger</para> - </entry> - <entry> - <para>Creates an instance of ConnectorLogger that prints log messages to - system.out( )</para> - </entry> - </row> - <row> - <entry> - <para>createEnvironment</para> - </entry> - <entry> - <para>Creates an instance of connectorEnvironment for use in your testing - environment.</para> - </entry> - </row> - <row> - <entry> - <para>createExecutionContext</para> - </entry> - <entry> - <para>Creates an ExecutionContext instance.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - <para /> - <para>In addition, some implementations of ConnectorLogger are provided which can be used as - needed to build a custom logger for testing.  BaseLogger is a base logger class that can be - extended to create your own ConnectorLogger implementation.  SysLogger is a utility - implementation that logs to System.out.</para> - </sect1> - - <sect1> - <title>Command Line Tester</title> - <sect2> - <title>Using the Command Line Tester</title> - <para>The command line tester is available in the mmtools kit along with the other - Teiid products in the tools directory. The tester can be executed in interactive mode by running </para> - - <programlisting><![CDATA[ + <para>The executeCommand() method will return results as a List of + rows.  Each row is + itself a List of objects in column order.  So, each row should have the + same number of items + corresponding to the columns in the SELECT clause of the query.  In the case of + an INSERT, + UPDATE, or DELETE, a single “row” will be returned with a single column + that contains the + update count.</para> + </sect2> + + </sect1> + + <sect1> + <title>Connector Environment</title> + <para>Many parts of the Connector API require use of the Connector + Environment.  The + EnvironmentUtility can be used to obtain and control a Connector Environment instance. + </para> + + <table frame='all'> + <title>Command Execution</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*" /> + <colspec colname='c2' colwidth="2*" /> + <thead> + <row> + <entry> + <para>Method Name</para> + </entry> + <entry> + <para>Description</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>createExecutionContext</para> + </entry> + <entry> + <para>Creates a ExecutionContext instance.</para> + </entry> + </row> + <row> + <entry> + <para>createStdoutLogger</para> + </entry> + <entry> + <para>Creates an instance of ConnectorLogger that prints log + messages to + system.out( )</para> + </entry> + </row> + <row> + <entry> + <para>createEnvironment</para> + </entry> + <entry> + <para>Creates an instance of connectorEnvironment for use in your + testing + environment.</para> + </entry> + </row> + <row> + <entry> + <para>createExecutionContext</para> + </entry> + <entry> + <para>Creates an ExecutionContext instance.</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para /> + <para>In addition, some implementations of ConnectorLogger are + provided which can be used as + needed to build a custom logger for testing.  BaseLogger is a base logger + class that can be + extended to create your own ConnectorLogger implementation.  SysLogger is a + utility + implementation that logs to System.out.</para> + </sect1> + + <sect1> + <title>Command Line Tester</title> + <sect2> + <title>Using the Command Line Tester</title> + <para>The command line tester is available in the mmtools kit along + with the other + Teiid products in the tools directory. The tester can be executed in + interactive mode by running </para> + + <programlisting><![CDATA[ <unzipped folder>S\cdk\cdk.bat ]]></programlisting> - <para>Typing “help” in the command line tester provides a list of all available options.  These options are listed here with some additional detail:</para> - - <table frame='all'> - <title>Connector Lifecycle</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>Option</para> - </entry> - <entry> - <para>Arguments</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>Load Archive</para> - </entry> - <entry> - <para>PathToArchiveFileName</para> - </entry> - <entry> - <para>Load the Connector archive file, which loads the Connector type definition - file and all the extension modules into the CDK shell.</para> - </entry> - </row> - <row> - <entry> - <para>Load</para> - </entry> - <entry> - <para>ConnectorClass vdbFile</para> - </entry> - <entry> - <para>Load a connector by specifying the connector class name and the VDB metadata archive file</para> - </entry> - </row> - <row> - <entry> - <para>LoadFromScript</para> - </entry> - <entry> - <para>ScriptFile</para> - </entry> - <entry> - <para>Load a connector from a script</para> - </entry> - </row> - <row> - <entry> - <para>LoadProperties</para> - </entry> - <entry> - <para>PathToPropertyFile</para> - </entry> - <entry> - <para>Load a set of properties for your connector from a file</para> - </entry> - </row> - <row> - <entry> - <para>SetProperty</para> - </entry> - <entry> - <para>PropertyName PropertyValue</para> - </entry> - <entry> - <para>Set the value of a property</para> - </entry> - </row> - <row> - <entry> - <para>GetProperties</para> - </entry> - <entry> - <para /> - </entry> - <entry> - <para>List all properties currently set on the connector</para> - </entry> - </row> - <row> - <entry> - <para>Start</para> - </entry> - <entry> - <para /> - </entry> - <entry> - <para>Start the connector</para> - </entry> - </row> - <row> - <entry> - <para>Stop</para> - </entry> - <entry> - <para /> - </entry> - <entry> - <para>Stop the connector</para> - </entry> - </row> - </tbody> - </tgroup> - </table> + <para>Typing “help” in the command line tester provides a list of all + available options.  These options are listed here with some + additional detail:</para> - <table frame='all'> - <title>Command Execution</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>Option</para> - </entry> - <entry> - <para>Arguments</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>Select</para> - </entry> - <entry> - <para>Sql</para> - </entry> - <entry> - <para>Run a SELECT statement.  This option takes multi-line input terminated with “;”</para> - </entry> - </row> - <row> - <entry> - <para>Insert</para> - </entry> - <entry> - <para>Sql</para> - </entry> - <entry> - <para>Execute an INSERT statement.  This option takes multi-line input terminated with a “;”.</para> - </entry> - </row> - <row> - <entry> - <para>Update</para> - </entry> - <entry> - <para>Sql</para> - </entry> - <entry> - <para>Execute an UPDATE statement.  This option takes multi-line input terminated with “;”</para> - </entry> - </row> - <row> - <entry> - <para>Delete</para> - </entry> - <entry> - <para>Sql</para> - </entry> - <entry> - <para>Execute a DELETE statement.  This option takes multi-line input terminated with a “;”.</para> - </entry> - </row> - <row> - <entry> - <para>SetBatchSize</para> - </entry> - <entry> - <para>BatchSize</para> - </entry> - <entry> - <para>Set the batch size used when retrieving results</para> - </entry> - </row> - <row> - <entry> - <para>SetExecutionContext</para> - </entry> - <entry> - <para>VDBName VDBVersion UserName</para> - </entry> - <entry> - <para>Set the properties of the current security context</para> - </entry> - </row> - <row> - <entry> - <para>SetPrintStackOnError</para> - </entry> - <entry> - <para>PrintStackOnError</para> - </entry> - <entry> - <para>Set whether to print the stack trace when an error is received</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame='all'> - <title>Scripting</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>Option</para> - </entry> - <entry> - <para>Arguments</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>SetScriptFile</para> - </entry> - <entry> - <para>PathToScriptFile</para> - </entry> - <entry> - <para>Set the script file to use</para> - </entry> - </row> - <row> - <entry> - <para>Run</para> - </entry> - <entry> - <para>ScriptName</para> - </entry> - <entry> - <para>Run a script with the file name</para> - </entry> - </row> - <row> - <entry> - <para>Runall</para> - </entry> - <entry> - <para /> - </entry> - <entry> - <para>Run all scripts loaded by loadFromScript</para> - </entry> - </row> - <row> - <entry> - <para>RunScript</para> - </entry> - <entry> - <para>PathToScriptFile ScriptNameWithinFile</para> - </entry> - <entry> - <para>Run a particular script in a script file</para> - </entry> - </row> - <row> - <entry> - <para>SetFailOnError</para> - </entry> - <entry> - <para>FailOnError</para> - </entry> - <entry> - <para>Set whether to fail a script when an error is encountered or continue on</para> - </entry> - </row> - <row> - <entry> - <para>Result</para> - </entry> - <entry> - <para>ExpectedResults</para> - </entry> - <entry> - <para>Compares actual results from the previous command with the expected - results.  This command is only available when using the command line tester in script - mode.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame='all'> - <title>Miscellaneous</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>Option</para> - </entry> - <entry> - <para>Arguments</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>CreateArchive</para> - </entry> - <entry> - <para>PathTOArchiveFileName</para> - <para>PathToCDKFileName</para> - <para>PathToDirectoryForExtensionModules</para> - </entry> - <entry> - <para>Creates a connector archive file based on the properties supplied.</para> - </entry> - </row> - <row> - <entry> - <para>CreateTemplate</para> - </entry> - <entry> - <para>PathToTemplateFile</para> - </entry> - <entry> - <para>Create a template connector type file at the given file name.</para> - </entry> - </row> - <row> - <entry> - <para>Help</para> - </entry> - <entry> - <para /> - </entry> - <entry> - <para>List all options</para> - </entry> - </row> - <row> - <entry> - <para>Quit</para> - </entry> - <entry> - <para /> - </entry> - <entry> - <para>Quit the command line tester</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect2> - - <sect2> - <title>Loading Your Connector</title> - <para>Preparing your connector to execute commands consists of the following steps:</para> - <orderedlist> - <listitem> - <para>Add your connector code to the CDK classpath.  The cdk.bat script looks for this code - in the CONNECTORPATH environment variable.  This variable can be set with the DOS shell - command “SET CONNECTORPATH=c:\path\to\connector.jar”.  Alternately, you can modify the value - of the CONNECTORPATH environment variable in the cdk.bat file.</para> - </listitem> - <listitem> - <para>Start the command line tester.  You can start the tester by executing the cdk.bat - file in the cdk directory of the Teiid Tools installation.  </para> - </listitem> - <listitem> - <para>Load your connector class and the associated runtime metadata.  You can load your - connector by using the “load” command and specifying the fully-qualified class name of your - Connector implementation and the path to a VDB file.  The VDB runtime metadata archive - should contain the metadata you want to use while testing.</para> - </listitem> - <listitem> - <para>Set any properties required by your connector.  This can be accomplished with the - setProperty command for individual properties or the loadProperties command to load a set of - properties from either a properties file or a connector binding file.  You can use the - “getProperties” command to view the current property settings.</para> - </listitem> - <listitem> - <para>Start the connector.  Use the “start” command in the command-line tester to start your connector.  </para> - </listitem> - </orderedlist> - - <para>Following is an example transcript of how this process might look in a DOS command window.  User input is in bold.</para> + <table frame='all'> + <title>Connector Lifecycle</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*" /> - <programlisting><![CDATA[ -D:\metamatrix\console\cdk> set CONNECTORPATH=D:\myconn\myconn.jar -D:\metamatrix\console\cdk> cdk + <thead> + <row> + <entry> + <para>Option</para> + </entry> + <entry> + <para>Arguments</para> + </entry> + <entry> + <para>Description</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>Load Archive</para> + </entry> + <entry> + <para>ArchiveFileName</para> + </entry> + <entry> + <para>Load the Connector archive file, which loads the Connector + type definition + file and all the extension modules into the CDK shell.</para> + </entry> + </row> + <row> + <entry> + <para>Load</para> + </entry> + <entry> + <para>ConnectorClass vdbFile</para> + </entry> + <entry> + <para>Load a connector by specifying the connector class name + and the VDB metadata archive file</para> + </entry> + </row> + <row> + <entry> + <para>LoadFromScript</para> + </entry> + <entry> + <para>ScriptFile</para> + </entry> + <entry> + <para>Load a connector from a script</para> + </entry> + </row> + <row> + <entry> + <para>LoadProperties</para> + </entry> + <entry> + <para>PropertyFile</para> + </entry> + <entry> + <para>Load a set of properties for your connector from a file + </para> + </entry> + </row> + <row> + <entry> + <para>SetProperty</para> + </entry> + <entry> + <para>PropertyName PropertyValue</para> + </entry> + <entry> + <para>Set the value of a property</para> + </entry> + </row> + <row> + <entry> + <para>GetProperties</para> + </entry> + <entry> + <para /> + </entry> + <entry> + <para>List all properties currently set on the connector</para> + </entry> + </row> + <row> + <entry> + <para>Start</para> + </entry> + <entry> + <para /> + </entry> + <entry> + <para>Start the connector</para> + </entry> + </row> + <row> + <entry> + <para>Stop</para> + </entry> + <entry> + <para /> + </entry> + <entry> + <para>Stop the connector</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame='all'> + <title>Command Execution</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>Option</para> + </entry> + <entry> + <para>Arguments</para> + </entry> + <entry> + <para>Description</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>Select</para> + </entry> + <entry> + <para>Sql</para> + </entry> + <entry> + <para>Run a SELECT statement.  This option takes multi-line + input terminated with “;”</para> + </entry> + </row> + <row> + <entry> + <para>Insert</para> + </entry> + <entry> + <para>Sql</para> + </entry> + <entry> + <para>Execute an INSERT statement.  This option takes multi-line + input terminated with a “;”.</para> + </entry> + </row> + <row> + <entry> + <para>Update</para> + </entry> + <entry> + <para>Sql</para> + </entry> + <entry> + <para>Execute an UPDATE statement.  This option takes multi-line + input terminated with “;”</para> + </entry> + </row> + <row> + <entry> + <para>Delete</para> + </entry> + <entry> + <para>Sql</para> + </entry> + <entry> + <para>Execute a DELETE statement.  This option takes multi-line + input terminated with a “;”.</para> + </entry> + </row> + <row> + <entry> + <para>SetBatchSize</para> + </entry> + <entry> + <para>BatchSize</para> + </entry> + <entry> + <para>Set the batch size used when retrieving results</para> + </entry> + </row> + <row> + <entry> + <para>SetExecutionContext</para> + </entry> + <entry> + <para>VDBName VDBVersion UserName</para> + </entry> + <entry> + <para>Set the properties of the current security context</para> + </entry> + </row> + <row> + <entry> + <para>SetPrintStackOnError</para> + </entry> + <entry> + <para>PrintStackOnError</para> + </entry> + <entry> + <para>Set whether to print the stack trace when an error is + received</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame='all'> + <title>Scripting</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>Option</para> + </entry> + <entry> + <para>Arguments</para> + </entry> + <entry> + <para>Description</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>SetScriptFile</para> + </entry> + <entry> + <para>ScriptFile</para> + </entry> + <entry> + <para>Set the script file to use</para> + </entry> + </row> + <row> + <entry> + <para>Run</para> + </entry> + <entry> + <para>ScriptName</para> + </entry> + <entry> + <para>Run a script with the file name</para> + </entry> + </row> + <row> + <entry> + <para>Runall</para> + </entry> + <entry> + <para /> + </entry> + <entry> + <para>Run all scripts loaded by loadFromScript</para> + </entry> + </row> + <row> + <entry> + <para>RunScript</para> + </entry> + <entry> + <para>ScriptFile</para> + <para>ScriptNameWithinFile</para> + </entry> + <entry> + <para>Run a particular script in a script file</para> + </entry> + </row> + <row> + <entry> + <para>SetFailOnError</para> + </entry> + <entry> + <para>FailOnError</para> + </entry> + <entry> + <para>Set whether to fail a script when an error is encountered + or continue on</para> + </entry> + </row> + <row> + <entry> + <para>Result</para> + </entry> + <entry> + <para>ExpectedResults</para> + </entry> + <entry> + <para>Compares actual results from the previous command with the + expected + results.  This command is only available when using the command line + tester in script + mode.</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame='all'> + <title>Miscellaneous</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>Option</para> + </entry> + <entry> + <para>Arguments</para> + </entry> + <entry> + <para>Description</para> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>CreateArchive</para> + </entry> + <entry> + <para>ArchiveFileName</para> + <para>CDKFileName</para> + <para>ExtensionModuleDir</para> + </entry> + <entry> + <para>Creates a connector archive file based on the properties + supplied.</para> + </entry> + </row> + <row> + <entry> + <para>CreateTemplate</para> + </entry> + <entry> + <para>TemplateFile</para> + </entry> + <entry> + <para>Create a template connector type file at the given file + name.</para> + </entry> + </row> + <row> + <entry> + <para>Help</para> + </entry> + <entry> + <para /> + </entry> + <entry> + <para>List all options</para> + </entry> + </row> + <row> + <entry> + <para>Quit</para> + </entry> + <entry> + <para /> + </entry> + <entry> + <para>Quit the command line tester</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2> + <title>Loading Your Connector</title> + <para>Preparing your connector to execute commands consists of the + following steps:</para> + <orderedlist> + <listitem> + <para>Add your connector code to the CDK classpath.  The cdk.bat + script looks for this code + in the CONNECTORPATH environment variable.  This variable can be set + with the DOS shell + command “SET CONNECTORPATH=c:\path\to\connector.jar”.  Alternately, you + can modify the value + of the CONNECTORPATH environment variable in the cdk.bat file. + </para> + </listitem> + <listitem> + <para>Start the command line tester.  You can start the tester by + executing the cdk.bat + file in the cdk directory of the Teiid Tools installation.  </para> + </listitem> + <listitem> + <para>Load your connector class and the associated runtime + metadata.  You can load your + connector by using the “load” command and specifying the fully-qualified + class name of your + Connector implementation and the path to a VDB file.  The VDB runtime + metadata archive + should contain the metadata you want to use while testing.</para> + </listitem> + <listitem> + <para>Set any properties required by your connector.  This can be + accomplished with the + setProperty command for individual properties or the loadProperties command + to load a set of + properties from either a properties file or a connector binding file.  You + can use the + “getProperties” command to view the current property settings.</para> + </listitem> + <listitem> + <para>Start the connector.  Use the “start” command in the + command-line tester to start your connector.  </para> + </listitem> + </orderedlist> + + <para>Following is an example transcript of how this process might + look in a DOS command window.  User input is in bold.</para> + + <programlisting><![CDATA[ +D:\teiid\cdk> set CONNECTORPATH=D:\myconn\myconn.jar +D:\teiid\cdk> cdk.bat ========================== ENV SETTINGS ========================== -MM_ROOT = D:\metamatrix\console -MM_JAVA = D:\metamatrix\console\jre +TEIID_ROOT = D:\teiid CONNECTORPATH = D:\myconn\myconn.jar -CLASSPATH = ;D:\metamatrix\console\cdk\metamatrix-cdk.jar;D:\myconn\myconn.jar; +CLASSPATH = ;D:\teiid\cdk\metamatrix-cdk.jar;D:\myconn\myconn.jar; ================================================================== -D:\metamatrix\console>D:\metamatrix\tools400wl7\console\jre\bin\java -Xmx256m -Dmetamatrix.config.none -Dmetamatrix.log=4 com.metamatrix.cdk.ConnectorShell +java -Xmx256m com.metamatrix.cdk.ConnectorShell Starting Started - ]]></programlisting> - - </sect2> - - <sect2> - <title>Executing Commands</title> - <para>Commands can be executed against your connector using the SELECT, INSERT, UPDATE, and DELETE commands.  Procedure execution is not currently supported via the command line tester.  Commands may span multiple lines and should be terminated with a “;”.  </para> - <para>When a command is executed, the results are printed to the console.  Following is an example session executing a SELECT command with the command line tester.  User input is in bold.</para> - <programlisting><![CDATA[ + ]]></programlisting> + + </sect2> + + <sect2> + <title>Executing Commands</title> + <para>Commands can be executed against your connector using the + SELECT, INSERT, UPDATE, and DELETE commands.  Procedure execution is + not currently supported via the command line tester.  Commands may + span multiple lines and should be terminated with a “;”.  </para> + <para>When a command is executed, the results are printed to the + console.  Following is an example session executing a SELECT command + with the command line tester.  User input is in bold.</para> + <programlisting><![CDATA[ String Integer xyz 5 xyz 10 - ]]></programlisting> + ]]></programlisting> - <para/> - </sect2> - - <sect2> - <title>Scripting</title> - <para>One of the most useful capabilities of the command-line tester is the ability to capture - a sequence of commands in a script and automate the execution of the script.  This allows for - the rapid creation of regression and acceptance tests.  </para> - <para>A script file may contain multiple scripts, where each script is grouped together with { } - and a name.  Following is an example of a script file.  This script file also uses the special - script-only command RESULTS that will compare the results of the last execution with the - specified expected results.</para> - <programlisting><![CDATA[ + <para /> + </sect2> + + <sect2> + <title>Scripting</title> + <para>One of the most useful capabilities of the command-line tester + is the ability to capture + a sequence of commands in a script and automate the execution of the + script.  This allows for + the rapid creation of regression and acceptance tests.  </para> + <para>A script file may contain multiple scripts, where each script + is grouped together with { } + and a name.  Following is an example of a script file.  This script + file also uses the special + script-only command RESULTS that will compare the results of the last execution + with the + specified expected results.</para> + <programlisting><![CDATA[ test { load com.metamatrix.myconn.MyConnector d:\myconn\myconn.vdb setproperty user joe @@ -738,22 +821,22 @@ xyz 10 ] } - ]]></programlisting> - - <para/> - <para>To execute this file, run the command line tester in scripting mode and specify the script - file and the script within the file:</para> - - <programlisting><![CDATA[ -D:\metamatrix\console\cdk>cdk runscript d:\myconn\my.script test + ]]></programlisting> + + <para /> + <para>To execute this file, run the command line tester in scripting + mode and specify the script + file and the script within the file:</para> + + <programlisting><![CDATA[ +D:\teiid\cdk>cdk runscript d:\myconn\my.script test ========================== ENV SETTINGS ========================== -MM_ROOT = D:\metamatrix\console -MM_JAVA = D:\metamatrix\console\jre +TEIID_ROOT = D:\teiid CONNECTORPATH = D:\myconn\myconn.jar -CLASSPATH = ;D:\metamatrix\console\cdk\metamatrix-cdk.jar;D:\myconn\myconn.jar; +CLASSPATH = ;D:\teiid\cdk\metamatrix-cdk.jar;D:\myconn\myconn.jar; ================================================================== -D:\metamatrix\console>D:\metamatrix\tools400wl7\console\jre\bin\java -Xmx256m -Dmetamatrix.config.none -Dmetamatrix.log=4 com.metamatrix.cdk.ConnectorShell runscript my.script +java -Xmx256m -Dmetamatrix.config.none -Dmetamatrix.log=4 com.metamatrix.cdk.ConnectorShell runscript my.script Starting Started @@ -764,20 +847,25 @@ xyz 5 xyz 15 ->Test /metamatrix/tools400wl7/console/cdk/yahoo.script.test failed. CompareResults Error: Value mismatch at row 2 and column 2: expected = 10, actual = 15 +>Test /teiid/cdk/yahoo.script.test failed. CompareResults Error: Value mismatch at row 2 and column 2: expected = 10, actual = 15 -D:\metamatrix\console\cdk> - ]]></programlisting> +D:\teiid\cdk> + ]]></programlisting> - <para/> - <para>The script run above illustrates the output when the test result fails due to differences - between expected and actual results.  In this case the value was expected to be 10 in the script - but was actually 15.  The setFailOnError command can be used to fail the execution of the entire - script if an error occurs.  </para> - <para>Scripts can also be run in interactive mode by using the setScriptFile and run - commands.  This can be useful to record portions of your interactive testing to avoid re-typing - later.</para> - </sect2> - </sect1> + <para /> + <para>The script run above illustrates the output when the test + result fails due to differences + between expected and actual results.  In this case the value was expected + to be 10 in the script + but was actually 15.  The setFailOnError command can be used to fail + the execution of the entire + script if an error occurs.  </para> + <para>Scripts can also be run in interactive mode by using the + setScriptFile and run + commands.  This can be useful to record portions of your interactive testing + to avoid re-typing + later.</para> + </sect2> + </sect1> </chapter> \ No newline at end of file Copied: trunk/documentation/docbook/custom.dtd (from rev 1344, trunk/documentation/docbook/en-US/custom.dtd) =================================================================== --- trunk/documentation/docbook/custom.dtd (rev 0) +++ trunk/documentation/docbook/custom.dtd 2009-09-13 13:39:12 UTC (rev 1345) @@ -0,0 +1,7 @@ +<!ENTITY versionNumber "6.2.0"> +<!ENTITY copyrightYear "2009"> +<!ENTITY copyrightHolder "Red Hat, Inc."> +<!ENTITY url "http://www.jboss.org/teiid/"> +<!ENTITY docUrl "&url;/docs.html"> +<!ENTITY javaDocUrl "http://docs.jboss.org/teiid/&versionNumber;/apidocs"> +<!ENTITY desDocUrl "http://www.jboss.org/teiiddesigner/docs.html"> Deleted: trunk/documentation/docbook/en-US/custom.dtd =================================================================== --- trunk/documentation/docbook/en-US/custom.dtd 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/docbook/en-US/custom.dtd 2009-09-13 13:39:12 UTC (rev 1345) @@ -1,6 +0,0 @@ -<!ENTITY versionNumber "6.2.0"> -<!ENTITY copyrightYear "2009"> -<!ENTITY copyrightHolder "Red Hat, Inc."> -<!ENTITY url "http://www.jboss.org/teiid/"> -<!ENTITY docUrl "http://www.jboss.org/teiid/docs.html"> -<!ENTITY docLink "<ulink url='&docLink;'>Teiid Documentation</ulink>"> Modified: trunk/documentation/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/docbook/en-US/legal_notice.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,7 +24,7 @@ --> <!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> %CustomDTD; ]> Modified: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml =================================================================== --- trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,7 +24,7 @@ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> %CustomDTD; ]> Modified: trunk/documentation/quick-start-example/src/main/docbook/en-US/quick_start_example.xml =================================================================== --- trunk/documentation/quick-start-example/src/main/docbook/en-US/quick_start_example.xml 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/quick-start-example/src/main/docbook/en-US/quick_start_example.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,7 +24,7 @@ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> %CustomDTD; ]> Modified: trunk/documentation/reference/src/main/docbook/en-US/Reference.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/Reference.xml 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/reference/src/main/docbook/en-US/Reference.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,7 +24,7 @@ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> %CustomDTD; ]> Modified: trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/salesforce_connector_guide.xml =================================================================== --- trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/salesforce_connector_guide.xml 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/salesforce_connector_guide.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,7 +24,7 @@ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> %CustomDTD; ]> Modified: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml =================================================================== --- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml 2009-09-11 21:42:50 UTC (rev 1344) +++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml 2009-09-13 13:39:12 UTC (rev 1345) @@ -24,7 +24,7 @@ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> %CustomDTD; ]>