September 2009 - teiid-commits - Jboss List Archives

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

by teiid-commits＠lists.jboss.org

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 > 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 “>”.</para> + <para>Connector can support comparison criteria with the operator ">” or "<".</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 “>=”.</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 “<”.</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 “<=”.</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 “<>”.</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, "<=" (not ">"), ">=" (not "<"), 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. <AllowedValue>value</AllowedValue>. - 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. + <AllowedValue>value</AllowedValue>. + 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 >load com.metamatrix.myconn.MyConnector d:\myconn\myconn.vdb >setproperty user joe >start > - ]]></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[ >SELECT Name, Value FROM MyModel.MyGroup WHERE Name = ‘xyz’; 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 >Executing: load com.metamatrix.myconn.MyConnector d:\myconn\myconn.vdb @@ -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 >Finished -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; ]>

16 years, 7 months

1
0
0 / 0

teiid SVN: r1344 - in trunk/documentation: admin-guide/src/main/docbook/en-US and 12 other directories.

by teiid-commits＠lists.jboss.org

Author: shawkins Date: 2009-09-11 17:42:50 -0400 (Fri, 11 Sep 2009) New Revision: 1344 Added: trunk/documentation/docbook/ trunk/documentation/docbook/en-US/ trunk/documentation/docbook/en-US/custom.dtd trunk/documentation/docbook/en-US/legal_notice.xml Removed: trunk/documentation/admin-guide/src/main/docbook/en-US/images/ trunk/documentation/admin-guide/src/main/docbook/en-US/legal_notice.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/federate-info.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/monitored-connector.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/images/ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/legal_notice.xml trunk/documentation/custom.dtd trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/images/ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml trunk/documentation/quick-start-example/src/main/docbook/en-US/images/logo.png trunk/documentation/quick-start-example/src/main/docbook/en-US/legal_notice.xml trunk/documentation/reference/src/main/docbook/en-US/images/logo.png trunk/documentation/reference/src/main/docbook/en-US/legal_notice.xml trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/images/logo.png trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/legal_notice.xml trunk/documentation/server-extensions-guide/src/main/docbook/en-US/images/ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/legal_notice.xml Modified: 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/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml 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 some initial progress toward revamping the connector developers guide. also removing invalid image and consolidating the legal notice 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/adminshell_guide.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -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 "../../../../../custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> %CustomDTD; ]> @@ -36,19 +36,11 @@ <releaseinfo>&versionNumber;</releaseinfo> <productnumber>&versionNumber;</productnumber> <issuenum>1</issuenum> - <mediaobject> - <imageobject role="fo"> - <imagedata fileref="images/logo.png" align="center"/> - </imageobject> - <imageobject role="html"> - <imagedata fileref="images/logo.png" depth="3cm" /> - </imageobject> - </mediaobject> <copyright> <year>&copyrightYear;</year> <holder>&copyrightHolder;</holder> </copyright> - <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> <toc/> Deleted: trunk/documentation/admin-guide/src/main/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,58 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> - -<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<legalnotice id="Legal_Notice"> - <title>Legal Notice</title> - <para> - <address> - <street>1801 Varsity Drive</street> - <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> - <phone>Phone: +1 919 754 3700</phone> - <phone>Phone: 888 733 4281</phone> - <fax>Fax: +1 919 754 3701</fax> - <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> - </address> - </para> - <para> - Copyright <trademark class="copyright"/> 2008 by Red Hat, Inc. This copyrighted material is made available to - anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the - GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published - by the Free Software Foundation. - </para> - <para> - Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. - </para> - <para> - All other trademarks referenced herein are the property of their respective owners. - </para> - <para> - The GPG fingerprint of the security(a)redhat.com key is: - </para> - <para> - CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E - </para> -</legalnotice> 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -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 "../../../../../custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> %CustomDTD; ]> @@ -36,31 +36,21 @@ <releaseinfo>&versionNumber;</releaseinfo> <productnumber>&versionNumber;</productnumber> <issuenum>1</issuenum> - <mediaobject> - <imageobject role="fo"> - <imagedata fileref="images/logo.png" align="center"/> - </imageobject> - <imageobject role="html"> - <imagedata fileref="images/logo.png" depth="3cm" /> - </imageobject> - </mediaobject> <copyright> <year>&copyrightYear;</year> <holder>&copyrightHolder;</holder> </copyright> - <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> <toc/> - <xi:include href="content/federate-info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/connector-api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/command-language.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/connector-development-kit.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/connector-deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/connection-pooling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/monitored-connector.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/lob-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -3,157 +3,188 @@ <sect1> <title>Language Interfaces</title> - <para>Teiid sends commands to your connector in object form. The interfaces for these objects are all defined in the com.metamatrix.data.language package. These interfaces can be combined to represent any possible command that Teiid may send to the connector. However, it is possible to notify the Teiid Server that your connector can only accept certain kinds of commands via the ConnectorCapabilities class. See the section on using <link linkend="connector_capabilities">Connector Capabilities</link> for more information.</para> - <para>The language interfaces all extend from the main interface, ILanguageObject. They are composed in 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: IQuery, IInsert, IUpdate, IDelete, and IProcedure. These represent the query in SQL form. Important components of these commands are expressions, criteria, and joins, which are examined in closer detail below.</para> - + <para> + Teiid sends commands to your connector in object form. The interfaces + for these objects are all defined in the org.teiid.connector.language + package. These interfaces can be combined to represent any possible + command that Teiid may send to the connector. However, it is possible + to notify Teiid that your connector can only accept certain kinds of + commands via the ConnectorCapabilities class. See the section on using + <link linkend="connector_capabilities">Connector Capabilities</link> + 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 + 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> <sect2> <title>Expressions</title> - <para>An expression represents a single value in context, although in some cases that value may change as the query is evaluated. For example, a literal value, such as “5” represents an integer value. An element such as “EmployeeName” represents a column in a data source and may take on many scalar values while the command is being evaluated. </para> - <para>The following diagram shows the IExpression interface and all sub-interfaces in the language objects. </para> - - <figure id="expression-interface-hierarchy"> - <title>Execution Interfaces Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/expression-interface-hierarchy.png"/> - </figure> - - <para/> - <para>These interfaces are explained in greater detail here:</para> + <para>An expression represents a single value in context, although in + some cases that value may change as the query is evaluated. For + example, a literal value, such as 5 represents an integer value. An + element reference such as "table.EmployeeName" represents a column in a data source + and may logically take on many values while the command is being + evaluated.</para> <itemizedlist> - <listitem><para><emphasis>IExpression</emphasis> – base expression interface</para></listitem> - <listitem><para><emphasis>IElement</emphasis> – represents an element in the data source</para></listitem> - <listitem><para><emphasis>ILiteral</emphasis> – represents a literal scalar value</para></listitem> - <listitem><para><emphasis>IFunction</emphasis> – represents a scalar function with parameters that are also IExpressions</para></listitem> - <listitem><para><emphasis>IAggregate</emphasis> – represents an aggregate function which holds a single expression</para></listitem> - <listitem><para><emphasis>IScalarSubquery</emphasis> – represents a subquery that returns a single value</para></listitem> - <listitem><para><emphasis>ICaseExpression</emphasis> – represents a CASE expression. The CASE expression evaluates an expression, then compares with the values in the WHEN clauses to determine the THEN clause to evaluate.</para></listitem> - <listitem><para><emphasis>ISearchedCaseExpression</emphasis> – represents a searched CASE expression. The searched CASE expression evaluates the criteria in WHEN clauses till one evaluates to TRUE, then evaluates the associated THEN clause.</para></listitem> + <listitem> + <para> + <code>IExpression</code> + – base expression interface + </para> + </listitem> + <listitem> + <para> + <code>IElement</code> + – represents an element in the data source + </para> + </listitem> + <listitem> + <para> + <code>ILiteral</code> + – represents a literal scalar value, but may also be multi-valued in + the case of bulk updates. + </para> + </listitem> + <listitem> + <para> + <code>IFunction</code> + – represents a scalar function with parameters that are also + IExpressions + </para> + </listitem> + <listitem> + <para> + <code>IAggregate</code> + – represents an aggregate function which holds a single expression + </para> + </listitem> + <listitem> + <para> + <code>IScalarSubquery</code> + – represents a subquery that returns a single value + </para> + </listitem> + <listitem> + <para> + <code>ISearchedCaseExpression</code> + – represents a searched CASE expression. The searched CASE + expression evaluates the criteria in WHEN clauses till one evaluates + to TRUE, then evaluates the associated THEN clause. + </para> + </listitem> </itemizedlist> </sect2> <sect2> <title>Criteria</title> - <para>A criteria is a combination of expressions and operators that evaluates to true or false. Criteria are most commonly used in the FROM or HAVING clauses. The following diagram shows the criteria interfaces present in the language objects.</para> + <para>A criteria is a combination of expressions and operators that + evaluates to true, false, or unknown. Criteria are most commonly used in the + WHERE or HAVING clauses.</para> - <figure id="criteria-interface-hierarchy"> - <title>Criteria Interfaces Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/criteria-interface-hierarchy.png"/> - </figure> - - <para>These interfaces are described in greater detail here:</para> - <itemizedlist> - <listitem><para><emphasis>ICriteria</emphasis> – the base criteria interface</para></listitem> - <listitem><para><emphasis>ILogicalCriteria</emphasis> – used to logically combine other criteria</para></listitem> - <listitem><para><emphasis>INotCriteria</emphasis> – used to NOT another criteria</para></listitem> - <listitem><para><emphasis>ICompoundCriteria</emphasis> – used to combine other criteria via AND or OR</para></listitem> - <listitem><para><emphasis>IPredicateCriteria</emphasis> – a predicate that evaluates to true or false</para></listitem> - <listitem><para><emphasis>ISubuqeryCompareCriteria</emphasis> – represents a comparison criteria with a subquery including a quantifier such as <emphasis>SOME</emphasis> or <emphasis>ALL</emphasis></para></listitem> - <listitem><para><emphasis>ICompareCriteria</emphasis> – represents a comparison criteria with =, >, <, etc</para></listitem> - <listitem><para><emphasis>IBaseInCriteria</emphasis> – base class for an <emphasis>IN</emphasis> criteria</para></listitem> - <listitem><para><emphasis>IInCriteria</emphasis> – represents an <emphasis>IN</emphasis> criteria that has a set of expressions for values</para></listitem> - <listitem><para><emphasis>ISubqueryInCriteria</emphasis> – represents an <emphasis>IN</emphasis> criteria that uses a subquery to produce the value set</para></listitem> - <listitem><para><emphasis>IIsNullCriteria</emphasis> – represents an <emphasis>IS NULL</emphasis> criteria</para></listitem> - <listitem><para><emphasis>IExistsCriteria</emphasis> – represents an <emphasis>EXISTS</emphasis> criteria that determines whether a subquery will return any values</para></listitem> - <listitem><para><emphasis>ILikeCriteria</emphasis> – represents a <emphasis>LIKE</emphasis> criteria that compares string values</para></listitem> + <listitem><para><code>ICriteria</code> – the base criteria interface</para></listitem> + <listitem><para><code>ILogicalCriteria</code> – used to logically combine other criteria</para></listitem> + <listitem><para><code>INotCriteria</code> – used to NOT another criteria</para></listitem> + <listitem><para><code>ICompoundCriteria</code> – used to combine other criteria via AND or OR</para></listitem> + <listitem><para><code>IPredicateCriteria</code> – a predicate that evaluates to true, false, or unknown</para></listitem> + <listitem><para><code>ISubuqeryCompareCriteria</code> – represents a comparison criteria with a subquery including a quantifier such as SOME or ALL</para></listitem> + <listitem><para><code>ICompareCriteria</code> – represents a comparison criteria with =, >, <, etc.</para></listitem> + <listitem><para><code>IBaseInCriteria</code> – base class for an IN criteria</para></listitem> + <listitem><para><code>IInCriteria</code> – represents an IN criteria that has a set of expressions for values</para></listitem> + <listitem><para><code>ISubqueryInCriteria</code> – represents an IN criteria that uses a subquery to produce the value set</para></listitem> + <listitem><para><code>IIsNullCriteria</code> – represents an IS NULL criteria</para></listitem> + <listitem><para><code>IExistsCriteria</code> – represents an EXISTS criteria that determines whether a subquery will return any values</para></listitem> + <listitem><para><code>ILikeCriteria</code> – represents a LIKE criteria that compares string values</para></listitem> </itemizedlist> </sect2> <sect2> - <title>Joins</title> - <para>The FROM clause contains a list of IFromItems. Each IFomItem can either represent a group or a join between two other IFromItems. This allows joins to be composed into a join tree. </para> + <title>The FROM Clause</title> + <para>The FROM clause contains a list of IFromItems. Each IFomItem can + either represent a group or a join between two other IFromItems. This + allows joins to be composed into a join tree.</para> - <figure id="join-tree-hierarchy"> - <title>IJoin Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/join-tree-hierarchy.png"/> - </figure> - <para>The <code>IGroup</code> represents a single group, which must be a leaf of the join tree. The <code>IJoin</code> has a left and right <code>IFromItem</code> and information on the join between the items. </para> + <itemizedlist> + <listitem><para><code>IGroup</code> – represents a single group</para></listitem> + <listitem><para><code>IJoin</code> – has a left and right <code>IFromItem</code> and information on the join between the items</para></listitem> + <listitem><para><code>IInlineView</code> – represents a group defined by an inline <code>IQueryCommand</code></para></listitem> + </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 + 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> </sect2> - + <sect2> + <title>IQueryCommand Structure</title> + <para>IQueryCommand (refered to in SQL as a Query Expression) is the base for both queries and set queries. It may optionally take an IOrderBy (representing a SQL ORDER BY clause) and a ILimit (represent a SQL LIMIT clause)</para> + </sect2> <sect2> <title>IQuery Structure</title> - <para>The following diagram shows the structure of an <code>IQuery</code> command.</para> - - <figure id="iquery-interface-hierarchy"> - <title>IQuery Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/iquery-interface-hierarchy.png"/> - </figure> - <para>Each IQuery will have an ISelect describing the expressions (typically elements) being selected and an IFrom specifying the group or groups being selected from, along with any join information. The IQuery may optionally also supply an ICriteria (representing a SQL WHERE clause), an IGroupBy (representing a SQL GROUP BY clause), and an ICriteria (representing a SQL HAVING clause). </para> + <para>Each IQuery will have an ISelect describing the expressions + (typically elements) being selected and an IFrom specifying the group + or groups being selected from, along with any join information. The + IQuery may optionally also supply an ICriteria (representing a SQL + WHERE clause), an IGroupBy (representing a SQL GROUP BY clause), an + an ICriteria (representing a SQL HAVING clause).</para> </sect2> <sect2> - <title>IUnion Structure</title> - <para>The following diagram shows the structure of an IUnion command.</para> + <title>ISetQuery Structure</title> - <figure id="iunion-interface-hierarchy"> - <title>IUnion Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/iunion-interface-hierarchy.png"/> - </figure> - - <para>IUnion extends from IQuery and allows for one or more additional IQuery objects to be attached as a UNION query. For each additional IQuery, there is a Boolean “ALL” flag that must be set. The ORDER BY clause for the UNION as a whole can also be set on the IUnion object.</para> + <para>An ISetQuery represents on of the SQL set operations (UNION, + INTERSECT, EXCEPT) on two IQueryCommands. The all flag may be set to + indicate UNION ALL (currently INTERSECT and EXCEPT ALL are not allowed + in Teiid)</para> </sect2> <sect2> - <title>IInsert Structure </title> - <para>The following diagram shows the structure of an IInsert command.</para> + <title>IInsert Structure</title> - <figure id="iinsert-interface-hierarchy"> - <title>IInsert Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/iinsert-interface-hierarchy.png"/> - </figure> - <para>Each IInsert will have a single IGroup specifying the group being inserted into. It will also have two matched lists – one a list of IElement specifying the columns of the IGroup that are being inserted into and one a list of ILiteral specifying the values that will be inserted into each matching IElement.</para> + <para>Each IInsert will have a single IGroup specifying the group being + inserted into. It will also a list of + IElements specifying the columns of the IGroup that are being inserted + into and an IInsertValueSource, which will either be a list of IExpression (IInsertExpressionValueSource) or an IQueryCommand.</para> </sect2> <sect2> <title>IUpdate Structure</title> - <para>The following diagram shows the structure of an IUpdate command.</para> - <figure id="iupdate-interface-hierarchy"> - <title>IUpdate Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/iupdate-interface-hierarchy.png"/> - </figure> - - <para>Each IUpdate will have a single IGroup specifying the group being updated. The list of ICompareCriteria are used to specify each element that is being modified. Each compare criteria will be of the form “element = literal”. The IUpdate may optionally provide a criterion specifying which rows should be updated.</para> + <para>Each IUpdate will have a single IGroup specifying the group being + updated. The ISetClauseList contains ISetClause entries that specify + IElement and IExpression pairs for the update. + The IUpdate may optionally provide a + criteria specifying which rows should be updated.</para> </sect2> <sect2> <title>IDelete Structure</title> - <para>The following diagram shows the structure of an IDelete command.</para> - <figure id="idelete-interface-hierarchy"> - <title>IDelete Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/idelete-interface-hierarchy.png"/> - </figure> - <para>Each IDelete will have a single IGroup specifying the group being deleted from. It may also optionally have a criteria specifying which rows should be deleted. </para> + + <para>Each IDelete will have a single IGroup specifying the group being + deleted from. It may also optionally have a criteria specifying which + rows should be deleted. </para> </sect2> <sect2> <title>IProcedure Structure</title> - <para>The following diagram shows the structure of an IProcedure command.</para> - <figure id="iprocedure-interface-hierarchy"> - <title>IProcedure Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/iprocedure-interface-hierarchy.png"/> - </figure> - <para>Each IProcedure has zero or more IParameter objects. The IParameter objects describe the input parameters, the output result set, and the output parameters. </para> + + <para>Each IProcedure has zero or more IParameter objects. The + IParameter objects describe the input parameters, the output result + set, and the output parameters. </para> </sect2> <sect2> - <title>IBulkInsert Structure </title> - <para>The following diagram shows the structure of an IBulkInsert command.</para> - <figure id="ibulkinsert-interface-hierarchy"> - <title>IBulkInsert Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/ibulkinsert-interface-hierarchy.png"/> - </figure> - <para>Each IBulkInsert extends an IInsert but provides a List of Lists of values that need to be placed into the VALUES list of the INSERT. </para> - </sect2> - - <sect2> <title>IBatchedUpdate Structure </title> - <para>The following diagram shows the structure of an IBatchedUpdate command.</para> - <figure id="ibatchedupdate-interface-hierarchy"> - <title>IBatchedUpdate Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/ibatchedupdate-interface-hierarchy.png"/> - </figure> - <para>Each IBatchedUpdate has a list of ICommand objects that compose the batch. </para> + + <para>Each IBatchedUpdate has a list of ICommand objects (which must be + an IInsert, IUpdate, or IDelete) that compose the batch. </para> </sect2> </sect1> @@ -164,64 +195,52 @@ <sect2> <title>Data Types</title> <para>The Connector API contains an interface TypeFacility that defines data types and provides value translation facilities. </para> - <figure id="datatypes-classes"> - <title>IBatchedUpdate Interface Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/datatypes-classes.png"/> - </figure> - - <para>The table below lists the role of each class in the framework.</para> - - <table frame='all'> - <title>Types Facility Classes</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth=".5*"/> - <colspec colname='c3' colwidth="2*"/> - <thead> - <row> - <entry><para>Class</para></entry> - <entry><para>Type</para></entry> - <entry><para>Description</para></entry> - </row> - </thead> - <tbody> - <row> - <entry><para>ConnectorEnvironment</para></entry> - <entry><para>Interface</para></entry> - <entry><para>This interface (provided by Teiid) is a factory to obtain the TypeFacility instance for the connector using the getTypeFacility() method.</para></entry> - </row> - <row> - <entry><para>TypeFacility</para></entry> - <entry><para>Interface</para></entry> - <entry><para>This interface has two methods that support data type transformation. Generally,transformations exist for all valid implicit and explicit data type transformations in the Teiid query engine. </para></entry> - </row> - <row> - <entry><para>TypeFacility.RUNTIME_TYPES</para></entry> - <entry><para>Interface</para></entry> - <entry><para>This is an inner interface of TypeFacility that defines constants for all Teiid runtime data types. All IExpression instances define a data type based on this set of types. These constants are often needed in understanding or creating language interfaces.</para></entry> - </row> - </tbody> - </tgroup> - </table> + + <para>This ConnectorEnvironment (provided by Teiid on connector start) + is a factory to obtain a TypeFacility instance for the connector using + the getTypeFacility() method. + The TypeFacitlity interface has methods that support data type + transformation and detection of appropriate runtime or JDBC types. + The TypeFacility.RUNTIME_TYPES and TypeFacility.RUNTIME_NAMES + interfaces defines constants for all Teiid runtime data types. All + IExpression instances define a data type based on this set of types. + These constants are often needed in understanding or creating + language interfaces.</para> </sect2> - <sect2> <title>Language Manipulation</title> - <para>In connectors that support a fuller set of capabilities (those that generally are translating to a language of comparable to SQL), there is often a need to manipulate or create language interfaces to move closer to the syntax of choice. Some utilities are provided for this purpose:</para> - <para>Similar to the TypeFacility, you can use the ConnectorEnvironment to get a reference to the ILanguageFactory instance for your connector. This interface is a factory that can be used to create new instances of all the concrete language interface objects. </para> - <para>Some helpful utilities for working with ICriteria objects are provided in the LanguageUtil class. This class has methods to combine ICriteria with AND or to break an ICriteria apart based on AND operators. These utilities are helpful for breaking apart a criteria into individual filters that your connector can implement.</para> + <para>In connectors that support a fuller set of capabilities (those + that generally are translating to a language of comparable to SQL), + there is often a need to manipulate or create language interfaces to + move closer to the syntax of choice. Some utilities are provided for + this purpose:</para> + <para>Similar to the TypeFacility, you can use the ConnectorEnvironment + to get a reference to the ILanguageFactory instance for your + connector. This interface is a factory that can be used to create new + instances of all the concrete language interface objects. </para> + <para>Some helpful utilities for working with ICriteria objects are + provided in the LanguageUtil class. This class has methods to combine + ICriteria with AND or to break an ICriteria apart based on AND + operators. These utilities are helpful for breaking apart a criteria + into individual filters that your connector can implement.</para> </sect2> </sect1> <sect1> <title>Runtime Metadata</title> - <para>Teiid uses a library of metadata, known as “runtime metadata” for each virtual database that is deployed in the Teiid Server. The runtime metadata is a subset of metadata as defined by models in the Teiid models that compose the virtual database. </para> - <para>Connectors can access runtime metadata by using the interfaces defined in com.metamatrix.data.metadata.runtime. This class defines interfaces representing a MetadataID, a MetadataObject, and ways to navigate those IDs and objects.</para> + <para>Teiid uses a library of metadata, known as “runtime metadata” for + each virtual database that is deployed in Teiid. The runtime metadata + is a subset of metadata as defined by models in the Teiid models that + compose the virtual database. </para> + <para>Connectors can access runtime metadata by using the interfaces + defined in org.teiid.connector.metadata.runtime. This package defines + interfaces representing a MetadataID, a MetadataObject, and ways to + navigate those IDs and objects.</para> <sect2> <title>Language Objects</title> - <para>One language interface, IMetadataReference describes whether a language object has a reference to a MetadataID. The following interfaces extend IMetadataReference:</para> + <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> @@ -229,27 +248,35 @@ <listitem><para>IParameter</para></listitem> </itemizedlist> - <para>Once a MetadataID has been obtained, it is possible to use the RuntimeMetadata interface to discover metadata about that ID or to find other related IDs or objects.</para> + <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> </sect2> <sect2> <title>Access to Runtime Metadata</title> - <para>The following interfaces are defined in the runtime metadata package:</para> - <figure id="runtime-metadata-classes"> - <title>Runtime MetaData Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/runtime-metadata-classes.png"/> - </figure> - <para>As mentioned in the previous section, a MetadataID is obtained from one of the language objects. That MetadataID can then be used directly to obtain information about the ID, such as the full name or short name. </para> - <para>The RuntimeMetadata interface can be obtained from the ConnectorEnvironment. It provides the ability to look up MetadataObjects based on MetadataIDs. There are several kinds of MetadataObjects and they can be used to find more information about the object in runtime metadata. </para> - <para>Currently, only a subset of the most commonly used runtime metadata is available through these interfaces. In the future, more complete information will be available.</para> + <para>As mentioned in the previous section, a MetadataID is obtained + from one of the language objects. That MetadataID can then be used + directly to obtain information about the ID, such as the full name or + short name. </para> + <para>The RuntimeMetadata interface is passed in for the creation of an Execution. It provides the ability to look up + MetadataObjects based on their fully qualified names in the VDB. There are several kinds of + MetadataObjects and they can be used to find more information about + the object in runtime metadata. </para> + <para>Currently, only a subset of the most commonly used runtime + metadata is available through these interfaces. In the future, more + complete information will be available.</para> + <para><emphasis>Obtaining MetadataObject Properties Example</emphasis></para> - <para>The process of getting an element's properties is needed for most connector development For example to get the NameInSource property or all extension properties:</para> + <para>The process of getting an element's properties is sometimes needed for connector development. For example to get the NameInSource property or all extension properties:</para> <programlisting><![CDATA[ -IMetaDataReference ref = ... //An IGroup in this example -RuntimeMetadata rm = ... //Obtained from the ConnectorEnvironemnt +//getting the Group metadata from an IGroup is straight-forward +IGroup igroup = ... //some group on a command +Group group = igroup.getMetadataObject(); -MetaDataObject group = rm.getObject(ref.getMetadataID()); +//we could also use the runtime metadata +RuntimeMetadata rm = ... //Obtained from the creation of the Execution + +group = rm.getGroup("fully.qualified.name"); String contextName = group.getNameInSource(); //The props will contain extension properties @@ -264,11 +291,7 @@ <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. This diagram describes the relationships of the various classes in the framework:</para> - <figure id="language-visitor-classes"> - <title>LanguageObjectVisitor Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/language-visitor-classes.png"/> - </figure> + <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> 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -2,12 +2,12 @@ <title>Connection Pooling</title> <sect1> <title>Overview</title> - <para>The Query Engine logically obtains and releases a connection - for each command that is executed.</para> - <para>However many enterprise sources maintain persistent - connections that are expensive to create. For these situaions, - Teiid provides a transparent connection pool to reuse rather than - constantly release connections. The connection pool is highly + <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, + Teiid provides a transparent connection pool to reuse, rather than + constantly close, connections. The connection pool is highly configurable through configuration properties and extension APIs for Connections and Connectors</para> <para>Many built-in connector types take advantage of pooling, @@ -40,34 +40,17 @@ <tbody> <row> <entry> - <para>PoolAwareConnection</para> + <para>Connection</para> </entry> <entry> <para>Interface</para> </entry> <entry> - <para>This interface is an extension of the Connection - interface and provides hooks to better interact with Connection - pooling.</para> + <para>The isAlive and closeCalled methods are used for pool interaction.</para> </entry> </row> <row> <entry> - <para>ConnectorIdentityFactory</para> - </entry> - <entry> - <para>Interface</para> - </entry> - <entry> - <para>Defines a factory for creating ConnectorIdentities. - This can optionally be implemented by the concrete Connector - class to properly segregate Connections in the pool. If this - class is not implemented by the Connector, then SingleIdentity - support will be assumed.</para> - </entry> - </row> - <row> - <entry> <para>ConnectorIdentity</para> </entry> <entry> @@ -89,21 +72,21 @@ <para>Class</para> </entry> <entry> - <para>This implementation of the identity class makes all - connections equivalent, thus creating a single pool.</para> + <para>This implementation of ConnectorIdentity makes all + connections equivalent, thus user scoping of connection is ignored.</para> </entry> </row> <row> <entry> - <para>UserIdentity</para> + <para>MappedUserIdentity</para> </entry> <entry> <para>Class</para> </entry> <entry> - <para>This implementation of the identity class makes all - connections equivalent for a particular user, thus creating a - set of per-user connection pools. </para> + <para>This implementation of ConnectorIdentity makes all + connections equivalent for a particular user allowing for per-user connection pools. + </para> </entry> </row> <row> @@ -133,17 +116,19 @@ adding the ConnectionPooling annotation, which defaults to enabled=true, to the Connector implementation class. Automatic Connection pooling can be disabled if either setting is false.</para> - <para>Connector developers can optionally utilize the - PoolAwareConnection and ConnectorIdentityFactory interfaces to refine - the Connector's interactions with Connection pooling. It is important + <para> + It is important to consider providing an implementation for - PoolAwareConnection.isAlive to indicate that a Connection is no + Connection.isAlive to indicate that a Connection is no longer viable and should be purged from the pool. Connection testing is performed upon leases from the pool and optionally at a regular interval that will purge idle Connections. It is also important to consider having the concrete Connector class implement - ConnectorIdentity factory if Connections are made under more than - just a single identity.</para> + ConnectorIdentity factory if Connections are made for multiple + identities. Note that setting connector binding property + UseCredentialMap to true will allow connectors extending BasicConnector + to have their ConnectorIdentity automatically set based upon the user + CredentialMap.</para> </sect1> <sect1> <title>The Connection Lifecycle</title> @@ -151,10 +136,10 @@ </para> <orderedlist> <listitem> - <para>If the Connector implements ConnectorIdentityFactory, the + <para>The ConnectorManager asks the Connector to generate a ConnectorIdentity - for the given SecurityContext, else SingleIdentity is assumed. The - ConnectorIdentity is then stored on the SecurityContext.</para> + for the given ExecutionContext. The + ConnectorIdentity is then stored on the ExecutionContext.</para> </listitem> <listitem> <para>The ConnectorManager asks for a Connection from the pool @@ -169,14 +154,13 @@ <para>After the ConnectorManager has used the Connection to execute a command, it releases the Connection. This call is intercepted by the pool and the method - PoolAwareConnection.releaseCalled is invoked on the Connection - instead. If the Connection does not implement PoolAwareConnection, - it is assumed no action is needed.</para> + Connection.closeCalled is invoked on the Connection + instead. Note that for many sources no action is necessary on closeCalled.</para> </listitem> <listitem> <para>When the Connection fails an isAlive check or becomes too old with pool shrinking enabled, it is purged from the pool and - Connection.release is called.</para> + Connection.close is called.</para> </listitem> </orderedlist> <sect2> 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,398 +1,423 @@ +<!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"> +%CustomDTD; +]> <chapter id="connector_api"> - <title>Connector API</title> - <sect1> - <title>Overview</title> - <para>A component called the Connector Manager is controlling access to your connector. This chapter reviews - the basics of how the Connector Manager interacts with your connector while leaving reference details and - advanced topics to be covered in later chapters.</para> - <para> - A custom connector must implement the following interfaces to connect and query an enterprise Data Source. - These interfaces are in package called - <emphasis>com.metamatrix.data.api:</emphasis> - </para> - <itemizedlist> - <listitem> - <para> - <emphasis>Connector</emphasis> - - This interface is the starting point for all interaction with your connector. It allows the Connector - Manager to obtain a connection and perform lifecycle events. - </para> - </listitem> - <listitem> - <para> - <emphasis>Connection</emphasis> - - This interface represents a connection to your data source. It is used as a starting point for actual - command executions. Connections provided to the Connector Manager will be obtained and released for each - command execution. Teiid provides for extensible automatic connection pooling, as discussed in the <link linkend="connection_pooling">Connection Pooling</link> - chapter. - </para> - </listitem> - <listitem> - <para> - <emphasis>ConnectorCapabilities</emphasis> - - This interface allows a connector to describe the execution capabilities of the connector. Teiid - provides a base implementation of this class called BasicConnectorCapabilities. You can either extend - this basic implementation or implement your own implementation. - </para> - </listitem> - <listitem> - <para> - <emphasis>Execution (and sub-interfaces)</emphasis> - - These interfaces represent a command execution with your Connector. There is a sub-interface for - executing each kinds of command: query, update, and procedure. Your connector can specify via the - ConnectorCapabilities which of these command types it can handle. - </para> - </listitem> - <listitem> - <para> - <emphasis>Batch</emphasis> - - This interface represents a batch of results being sent to the Teiid Server from the custom - connector. Teiid provides a default implementation of this class called BasicBatch. - </para> - </listitem> - </itemizedlist> - <para>The most important interfaces provided by Teiid to the connector are the following:</para> - <itemizedlist> - <listitem> - <para> - <emphasis>ConnectorEnvironment</emphasis> - – an interface describing access to external resources for your connector. - </para> - </listitem> - <listitem> - <para> - <emphasis>ConnectorLogger</emphasis> - – an interface for writing logging information to Teiid logs. - </para> - </listitem> - <listitem> - <para> - <emphasis>SecurityContext / ExecutionContext</emphasis> - – interfaces defining the security information and execution context available to the connector when - executing a command. - </para> - </listitem> - </itemizedlist> - </sect1> - <sect1> - <title>Connector Lifecycle</title> - <sect2> - <title>Initialization</title> - <para> - A Connector will be initialized one time via the initialize() method, which passes in a - <emphasis>ConnectorEnvironment</emphasis> - object provided by the - <emphasis>Connector Manager</emphasis> - . The - <emphasis>ConnectorEnvironment provides</emphasis> - the following resources to the connector: - </para> - <itemizedlist> - <listitem> - <para>Configuration properties – name / value pairs as provided by the connector binding in - the Teiid Console</para> - </listitem> - <listitem> - <para>Logging – ConnectorLogger interface allows a Connector to log messages and errors to - Teiid’s log files.</para> - </listitem> - <listitem> - <para>Runtime metadata – access to the runtime metadata of the model deployed in the Teiid - Server for your physical source</para> - </listitem> - <listitem> - <para>Large object replacement – ability to stream the results of large values (such as blobs and - clobs) through the Teiid system</para> - </listitem> - <listitem> - <para>Type facility – an interface defining runtime datatypes and type conversion facility.</para> - </listitem> - </itemizedlist> - </sect2> - <sect2> - <title>Starting and Stopping</title> - <para>Other methods on the connector allow the Connector Manager to start() or stop() the connector. - Typically the connector is started or stopped in response to system startup, system shutdown, or an - administrator changing these states on connector bindings in the Teiid Console or through Admin API. A - connector should perform whatever actions are necessary in these methods to create or destroy all connector - states, including connections to the actual physical source.</para> - </sect2> - </sect1> - <sect1> - <title>Connections to Source</title> - <sect2> - <title>Obtaining connections</title> - <para>The connector must implement the getConnection() method to allow the Connector Manager to obtain a - connection. The getConnection() method is passed a SecurityContext, which contains information about the - context in which this query is being executed.</para> - <para>The SecurityContext contains the following information:</para> - <itemizedlist> - <listitem> - <para>User name</para> - </listitem> - <listitem> - <para>Virtual database name</para> - </listitem> - <listitem> - <para>Virtual database version</para> - </listitem> - <listitem> - <para>Trusted token</para> - </listitem> - </itemizedlist> - <para>The trusted token is used to pass security information specific to your application through the - Teiid Server. The client can pass the trusted token when they connect via JDBC. This token is then - passed to the Membership Service and may be created, replaced, or modified at that time. In some cases, you - may wish to provide a customer Membership Service implementation to handle security needs specific to your - organization. For more information on implementing a custom Membership Service, contact Teiid - technical support.</para> - </sect2> - <sect2> - <title>Releasing Connections</title> - <para>Once the Connector Manager has obtained a connection, it will use that connection only for the - lifetime of the request. When the request has completed, the release() method will be called on the - connection.</para> - <para> - In cases (such as when a connection is stateful and expensive to create), connections should be pooled. Teiid - provides an extensible connection pool for this purpose, as described in chapter - <link linkend="connection_pooling">Connection Pooling</link>. - </para> - </sect2> - </sect1> - <sect1> - <title>Executing Commands</title> - <sect2> - <title>Execution Modes</title> - <para>The Connector API uses a connection to obtain an execution interface for the command it is - executing. Connectors may support any subset of the available execution modes. The execution modes are - defined by constants in the ConnectorCapabilities.EXECUTION_MODE class. The following execution modes are - available:</para> - <para /> - <table frame='all'> - <title>Types of Execution Modes</title> - <tgroup cols='4' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*" /> - <colspec colname='c2' colwidth="1*" /> - <colspec colname='c3' colwidth="1*" /> - <colspec colname='c4' colwidth="2*" /> - <thead> - <row> - <entry>Execution Mode</entry> - <entry>Execution Interface</entry> - <entry>Command interface(s)</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <emphasis>Synchronous Query</emphasis> - </entry> - <entry> - <code>SynchQueryExecution</code> - </entry> - <entry> - <code>IQuery</code> - </entry> - <entry>A query, corresponding to a SQL SELECT statement</entry> - </row> - <row> - <entry> - <emphasis>Update</emphasis> - </entry> - <entry> - <code>UpdateExecution</code> - </entry> - <entry> - <code>IInsert, IUpdate, IDelete</code> - </entry> - <entry>An insert, update, or delete, corresponding to a SQL INSERT, UPDATE, or DELETE command - </entry> - </row> - <row> - <entry> - <emphasis>Procedure Execution</emphasis> - </entry> - <entry> - <code>ProcedureExecution</code> - </entry> - <entry> - <code>IProcedure</code> - </entry> - <entry>A procedure execution that may return a result set and/or output values.</entry> - </row> - <row> - <entry> - <emphasis>Asynchronous Query</emphasis> - </entry> - <entry> - <code>AsynchQueryExecution</code> - </entry> - <entry> - <code>IQuery</code> - </entry> - <entry>Polled asynchronous execution of a SQL SELECT statement</entry> - </row> - <row> - <entry> - <emphasis>Batched Update</emphasis> - </entry> - <entry> - <code>BatchedUpdatesExecution</code> - </entry> - <entry> - <code>ICommand[]</code> - </entry> - <entry>Execute multiple commands in a batch</entry> - </row> - <row> - <entry> - <emphasis>Bulk Insert</emphasis> - </entry> - <entry> - <code>BatchedUpdatesExecution</code> - </entry> - <entry> - <code>IInsert</code> - </entry> - <entry>Insert a large set of data using the same INSERT command</entry> - </row> - </tbody> - </tgroup> - </table> - <para /> - <para>Following is a class diagram further defining the relationships between the execution - interfaces:</para> - <figure id="execution-interface-hierarchy"> - <title>Execution Interfaces Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/execution-interface-hierarchy.png" /> - </figure> - <para /> - <para>All of the execution interfaces extend the base execution interface that defines how executions are - cancelled and closed. SynchQueryExecution, AsynchQueryExecution, and ProcedureExecution all extend the - BatchedExecution interface, which defines how batched results are returned from an execution.</para> - </sect2> - <sect2> - <title>Synchronous Query Execution</title> - <para> - Most commands executed against connectors are queries. Queries correspond to the SELECT statement in SQL. - The actual queries themselves are sent to connectors in the form of a set of objects, which are further - described in Chapter <link linkend="command_language">Command Language</link>. - </para> - - <para>The following diagram represents the typical sequence of events when executing a query:</para> - - <figure id="query-execution-sequence"> - <title>Query Execution Sequence Diagram</title> - <graphic align="center" scale="100" fileref="../images/query-execution-sequence.png" /> - </figure> - - <para>While the command is being executed, the connector retrieves results in batches via the - BatchedExecution interface. Each time nextBatch() is called, the SynchQueryExecution implementation should - return a batch of no more than maxBatchSize records. The final batch of records should set the isLast flag - to true.</para> - - <para>The maxBatchSize parameter passed to the nextBatch method corresponds to the Connector Batch Size - that can be set on a system-wide bases in the Teiid Console (under System Properties in the buffer - section..) The Connector Batch Size should typically be set in conjunction with the Processor Batch Size - from the same category. For more information on these parameters, see the Teiid Console User Guide. - </para> - </sect2> - <sect2> - <title>Asynchronous Query Execution</title> - <para>In some scenarios, a connector needs to execute queries asynchronously and poll for results. In this - case, your connector should use the asynchronous query execution mode instead of the synchronous query - execution mode. The connector capabilities specify which will be used (only one can be supported at the - same time). </para> - - <para>The following diagram represents the typical sequence of events when executing a query - asynchronously:</para> - - <figure id="async-query-execution-sequence"> - <title>Async Query Execution Sequence Diagram</title> - <graphic align="center" scale="100" fileref="../images/async-query-execution-sequence.png" /> - </figure> - - <para>While the command is being executed, the connector retrieves results in batches via the - BatchedExecution interface. The AsynchQueryExecution interface works similarly to the SynchQueryExecution - interface with one important difference. If the nextBatch method returns an empty batch with the isLast - flag set to false, then the Connector Manager interprets this as no data being available. In this case, - the Connector Manager will wait for the poll interval before asking again for a batch.</para> - - <para>The nextBatch() is not expected to sleep or otherwise block for results as this would tie up a - Connector Manager thread which could be doing other work. Instead, the Connector Manager is designed to - avoid tying up worker threads while waiting for the poll interval, so the connector is expected to return - from the nextBatch() method as quickly as possible.</para> - <para /> - </sect2> - <sect2> - <title>Update Execution</title> - <para>Insert, update, and delete commands correspond to the INSERT, UPDATE, and DELETE commands in - SQL. They are used to insert a single row into a data source, update one or more rows in a data source, or - delete one or more rows in a data source. Each of these commands returns a count specifying the number of - rows updated in the physical source in response to the command.</para> - <para>The following diagram represents the typical sequence of events when executing an insert, update, or - delete:</para> - <figure id="update-query-execution-sequence"> - <title>Update Query Execution Sequence Diagram</title> - <graphic align="center" scale="100" fileref="../images/update-query-execution-sequence.png" /> - </figure> - <para>With an update execution, the execute method is the only call in the execution. No subsequent - interaction will take place. </para> - </sect2> - <sect2> - <title>Batched Update / Bulk Insert Execution</title> - <para>Batched update and bulk insert execution are very similar to update execution except multiple - commands are passed to the connector in a single method call. In the case of a bulk insert, a single - template INSERT command is passed with a set of data rows that need to be inserted with the command. In - the case of batched update, a series of arbitrary commands is sent and the batch must be executed together - for efficiency. </para> - </sect2> - <sect2> - <title>Procedure Execution</title> - <para>Procedure commands correspond to the execution of a stored procedure or some other functional - construct. A procedure takes zero or more input values and can return a result set and zero or more output - values. Examples of procedure execution would be a stored procedure in a relational database or a call to - a web service.</para> - <para>The following diagram represents the typical sequence of events when executing a procedure:</para> - <figure id="procedure-query-execution-sequence"> - <title>Procedure Query Execution Sequence Diagram</title> - <graphic align="center" scale="100" fileref="../images/procedure-query-execution-sequence.png" /> - </figure> - <para>If a result set is expected when a procedure is executed, all rows from it will be retrieved via the - BatchedExecution interface first. Then, if any output values are expected, they will be retrieved via the - getOutputValue() method, which will be called once for each expected output value.</para> - </sect2> - <sect2> - <title>Command Completion</title> - <para>All normal command executions end with the calling of close() on the Execution object. Your - implementation of this method should do the appropriate clean-up work for all state in the Execution - object.</para> - </sect2> - <sect2> - <title>Command Cancellation</title> - <para>Commands submitted to Teiid may be aborted in several scenarios:</para> - <itemizedlist> - <listitem> - <para>Client cancellation via the JDBC API (or other client APIs)</para> - </listitem> - <listitem> - <para>Administrative cancellation via the Teiid Console or Admin API</para> - </listitem> - <listitem> - <para>Clean-up during session termination</para> - </listitem> - <listitem> - <para>Clean-up if a query fails during processing</para> - </listitem> - </itemizedlist> - <para>In these cases, if the command being executed on the connector has not yet finished, Teiid will - call the cancel() method on the execution interface in a separate thread from the thread that may be - blocked calling the execute() method.</para> - <para>Your connector implementation may choose to do nothing in response to this cancellation message. In - this instance, Teiid will call close() on the execution object after current synchronous processing - has completed. Implementing the cancel() method allows for faster termination of queries being processed - and may allow the underlying data source to terminate its operations faster as well.</para> - </sect2> - </sect1> + <title>Connector API</title> + <sect1> + <title>Overview</title> + <para>A component called the Connector Manager is controlling access + to your connector. This chapter reviews + the basics of how the Connector Manager interacts with your connector + while leaving reference details and + advanced topics to be covered in later chapters.</para> + <para> + A custom connector must implement the following interfaces to connect + and query an enterprise Data Source. + These interfaces are in package called + <emphasis>org.teiid.connector.api:</emphasis> + </para> + <itemizedlist> + <listitem> + <para> + <emphasis>Connector</emphasis> + - This interface is the starting point for all interaction with + your connector. It allows the Connector + Manager to obtain a connection and perform lifecycle events. + </para> + </listitem> + <listitem> + <para> + <emphasis>Connection</emphasis> + - This interface represents a connection to your data source. It is + used as a starting point for actual + command executions. Connections provided to the Connector Manager will be + obtained and released for each + command execution. Teiid provides for extensible automatic connection + pooling, as discussed in the + <link linkend="connection_pooling">Connection Pooling</link> + chapter. + </para> + </listitem> + <listitem> + <para> + <emphasis>ConnectorCapabilities</emphasis> + - This interface allows a connector to describe the execution + capabilities of the connector. + </para> + </listitem> + <listitem> + <para> + <emphasis>Execution (and sub-interfaces)</emphasis> + - These interfaces represent a command execution with your + Connector. There is a sub-interface for + executing each kinds of command: ResultSetExecution, UpdateExecution, and ProcedureExecution. + </para> + </listitem> + </itemizedlist> + <para> + Note that many of the interfaces above have base implementations in the + <emphasis>org.teiid.connector.basic</emphasis> + package. Consider extending the corresponding BasicXXX class rather + than fully implementing the interface. + </para> + <para>The most important interfaces provided by Teiid to the connector + are the following:</para> + <itemizedlist> + <listitem> + <para> + <emphasis>ConnectorEnvironment</emphasis> + – an interface describing access to external resources for your + connector. + </para> + </listitem> + <listitem> + <para> + <emphasis>ConnectorLogger</emphasis> + – an interface for writing logging information to Teiid logs. + </para> + </listitem> + <listitem> + <para> + <emphasis>ExecutionContext</emphasis> + – interface defining the execution context available to the connector when + executing a command. + </para> + </listitem> + </itemizedlist> + </sect1> + <sect1> + <title>Connector Lifecycle</title> + <sect2> + <title>Starting</title> + <para> + A Connector instance will be initialized one time via the start + method, which passes in a + <emphasis>ConnectorEnvironment</emphasis> + object provided by the + <emphasis>Connector Manager</emphasis> + . The + <emphasis>ConnectorEnvironment provides</emphasis> + the following resources to the connector: + </para> + <itemizedlist> + <listitem> + <para>Configuration properties – name / value pairs as provided by + the connector binding in + the Teiid Console</para> + </listitem> + <listitem> + <para>Logging – ConnectorLogger interface allows a Connector to log + messages and errors to + Teiid’s log files.</para> + </listitem> + <listitem> + <para>Type facility – an interface defining runtime datatypes and + type conversion facility.</para> + </listitem> + <listitem> + <para>Scheduling facility – repeating tasks can be scheduled and managed by Teiid.</para> + </listitem> + <listitem> + <para>Caching facility – easy methods for caching based upon relevant contexts, such as session or query scope.</para> + </listitem> + </itemizedlist> + </sect2> + <sect2> + <title>Running</title> + <para> + While the connector is running it is expected to return provide + connections and capabilities information in response to system + requests. If the source system is not available ConnectorExceptions or + RuntimeExceptions may be thrown at any time to indicate failure. The + connector should handle failure internally in a graceful manner, since + the system will not automatically perform a stop/start. + </para> + </sect2> + <sect2> + <title>Stopping</title> + <para>The stop method will be called on system shutdown or on an + administrative call that to stop the connector. Once a connector has + been stopped the instance is removed from the system. A new Connector + instance will be created prior to the start call.</para> + </sect2> + </sect1> + <sect1> + <title>Connections to Source</title> + <sect2> + <title>Obtaining connections</title> + <para>The connector must implement the getConnection() method to + allow the Connector Manager to obtain a + connection. The getConnection() method is passed a ExecutionContext, which + contains information about the + context in which this query is being executed.</para> + <para>The ExecutionContext provides the following:</para> + <itemizedlist> + <listitem> + <para>User name</para> + </listitem> + <listitem> + <para>Virtual database name</para> + </listitem> + <listitem> + <para>Virtual database version</para> + </listitem> + <listitem> + <para>The ability to add execution warnings.</para> + </listitem> + <listitem> + <para>Trusted token</para> + </listitem> + </itemizedlist> + <para>The trusted token is used to pass security information specific + to your application through the + Teiid. The client can pass the trusted token when they connect via + JDBC. This token is then + passed to the Membership Service and may be created, replaced, or modified + at that time. In some cases, you + may wish to provide a customer Membership Service implementation to + handle security needs specific to your + organization. For more information on implementing see the <ulink url='&docUrl;'>Server Extension Guide</ulink></para> + </sect2> + <sect2> + <title>Releasing Connections</title> + <para>Once the Connector Manager has obtained a connection, it will + use that connection only for the + lifetime of the request. When the request has completed, the close() + method will be called on the + connection.</para> + <para> + In cases (such as when a connection is stateful and expensive to + create), connections should be pooled. Teiid + provides an extensible connection pool for this purpose, as described in + chapter + <link linkend="connection_pooling">Connection Pooling</link>. + </para> + </sect2> + </sect1> + <sect1> + <title>Executing Commands</title> + <sect2> + <title>Execution Modes</title> + <para> + The Connector API uses a Connection to obtain an execution + interface for the command it is + executing. The actual queries themselves are sent to connectors in the form of a + set of objects, which are further + described in Chapter + <link linkend="command_language">Command Language</link>. Connectors are allowed to support any subset of the available + execution modes. + </para> + <table frame='all'> + <title>Types of Execution Modes</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*" /> + <colspec colname='c2' colwidth="1*" /> + <colspec colname='c3' colwidth="2*" /> + <thead> + <row> + <entry>Execution Interface</entry> + <entry>Command interface(s)</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <code>ResultSetExecution</code> + </entry> + <entry> + <code>IQueryCommand</code> + </entry> + <entry>A query corresponding to a SQL SELECT or set query statement.</entry> + </row> + <row> + <entry> + <code>UpdateExecution</code> + </entry> + <entry> + <code>IInsert, IUpdate, IDelete, IBatchedUpdates</code> + </entry> + <entry>An insert, update, or delete, corresponding to a SQL + INSERT, UPDATE, or DELETE command + </entry> + </row> + <row> + <entry> + <code>ProcedureExecution</code> + </entry> + <entry> + <code>IProcedure</code> + </entry> + <entry>A procedure execution that may return a result set and/or + output values.</entry> + </row> + </tbody> + </tgroup> + </table> + <para>All of the execution interfaces extend the base <code>Execution</code> + interface that defines how executions are + cancelled and closed. ProcedureExecution also extends ResultSetExecution, since procedures may also return resultsets.</para> + </sect2> + <sect2> + <title>ResultSetExecution</title> + <para> + Typically most commands executed against connectors are IQueryCommands. + While the command is being executed, the connector provides + results via the + ResultSetExecution next method. The next method should return null to indicate the end + of results. Note: the expected batch size can be obtained from the + ExecutionContext and used as a hint in fetching results from the EIS. + </para> + </sect2> + <sect2> + <title>Update Execution</title> + <para>Each execution returns the update count(s) expected by the update command. + If possible IBatchedUpdates should be executed atomically. + The ExecutionContext can be used to determine if the execution is already under a transaction.</para> + </sect2> + <sect2> + <title>Procedure Execution</title> + <para>Procedure commands correspond to the execution of a stored + procedure or some other functional + construct. A procedure takes zero or more input values and can return a result + set and zero or more output + values. Examples of procedure execution would be a stored procedure in a + relational database or a call to + a web service.</para> + <para>If a result set is expected when a procedure is executed, all + rows from it will be retrieved via the + ResultSetExecution interface first. Then, if any output values are expected, they will + be retrieved via the + getOutputParameterValues() method. + </para> + </sect2> + <sect2> + <title>Asynchronous Executions</title> + <para>In some scenarios, a connector needs to execute + asynchronously and allow the executing thread to perform other work. To allow this, you should: + </para> + <itemizedlist> + <listitem> + <para>Set either the SynchronousWorkers annotation or the connector + binding property SynchWorkers to false - this overrides the default + behavior in which connector threads stay associated with their + Execution until the Execution is closed.</para> + <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> + <para>Be aware that a connector with asynchronous workers cannot be transactional.</para> + </listitem> + </itemizedlist> + </sect2> + <sect2> + <title>Bulk Execution</title> + <para> + Non batched + <code>IInsert, IUpdate, IDelete</code> + commands may have Iliteral values marked as multiValued if the + ConnectorCapabilities shows support for BulkUpdate. Commands with + multiValued Iliterals represent multiple executions of the same + command with different values. As with IBatchedUpdates, bulk operations should be executed atomically if possible. + </para> + </sect2> + <sect2> + <title>Command Completion</title> + <para>All normal command executions end with the calling of close() + on the Execution object. Your + implementation of this method should do the appropriate clean-up work for all + state in the Execution + object.</para> + </sect2> + <sect2> + <title>Command Cancellation</title> + <para>Commands submitted to Teiid may be aborted in several + scenarios:</para> + <itemizedlist> + <listitem> + <para>Client cancellation via the JDBC API (or other client APIs) + </para> + </listitem> + <listitem> + <para>Administrative cancellation</para> + </listitem> + <listitem> + <para>Clean-up during session termination</para> + </listitem> + <listitem> + <para>Clean-up if a query fails during processing</para> + </listitem> + </itemizedlist> + <para>Unlike the other execution methods, which are handled in a single-threaded manner, calls to cancel happen asynchronously with respect to the execution thread.</para> + <para>Your connector implementation may choose to do nothing in + response to this cancellation message. In + this instance, Teiid will call close() on the execution object after + current processing + has completed. Implementing the cancel() method allows for faster + termination of queries being processed + and may allow the underlying data source to terminate its operations + faster as well.</para> + </sect2> + </sect1> + <sect1> + <title>Monitored Connectors</title> + <para>Teiid can automatically monitor connectors, which will update a + status flag on the connector. This status can be checked via the + AdminApi and is exposed in the console. To use connector + monitoring + effectively: + </para> + <itemizedlist> + <listitem> + <para>Set a positive test interval value on + on the connector binding + (default is 600) indicating the number of + seconds between status + checks. These checks are useful in idle + periods. + </para> + </listitem> + <listitem> + <para>Implement a meaningful isAlive method on your Connector + Connections. + </para> + </listitem> + <listitem> + <para>Use either a pooled Connector or a Connector that supports + single identity. + </para> + </listitem> + </itemizedlist> + <para>Possible status results include:</para> + <itemizedlist> + <listitem> + <para>Not initialized - to indicate not yet started. + </para> + </listitem> + <listitem> + <para>Init failed - to indicate start failed. + </para> + </listitem> + <listitem> + <para>Open - to indicate the running state and that connections can + be obtained form the source. + </para> + </listitem> + <listitem> + <para>Unable to check - to indicate the running state but + connections cannot be obtained administratively. + </para> + </listitem> + <listitem> + <para>Data Source Unavailable - to indicate the running state. + </para> + </listitem> + <listitem> + <para>Closed - to indicate that the Connector has been stopped. + </para> + </listitem> + </itemizedlist> + </sect1> </chapter> \ No newline at end of file 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -30,8 +30,8 @@ <sect1> <title>Connector Type Definition File</title> - <para>A Connector Type Definition file defines a connector in the Teiid Server. The - Connector Type Definition file defines some key properties that allow the Teiid Server to + <para>A Connector Type Definition file defines a connector in Teiid. The + Connector Type Definition file defines some key properties that allow Teiid to use your connector as well as specifying other properties your connector might need. </para> <para>A Connector Type Definition file is in XML format and typically has the extension “.cdk”. It defines a default name for the connector type, the properties expected by the connector, @@ -43,7 +43,7 @@ <sect2> <title>Required Properties</title> - <para>The Connector API requires the following properties for the Teiid Server to load + <para>The Connector API requires the following properties for Teiid to load and use your connector.</para> <table frame='all'> <title>Required Connector Properties</title> @@ -70,7 +70,7 @@ <para>ConnectorClass</para> </entry> <entry> - <para>com.my.connector.MyConnector</para> + <para>foo.MyConnector</para> </entry> <entry> <para>Fully-qualified name of class implementing the Connector interface.</para> @@ -104,7 +104,7 @@ Type Definition file along with their default values and other property metadata. The actual property values can be changed when the connector is deployed in the Teiid Console.</para> <para>Each connector property carries with it several attributes that are used by the - Teiid Console to integrate the connector seamlessly into the Teiid Server.</para> + Teiid Console to integrate the connector seamlessly into Teiid.</para> <table frame='all'> <title>All Properties</title> @@ -250,15 +250,15 @@ <sect2> <title>Extension Modules</title> - <para>Extension Modules are used in the Teiid Server to store code that extends - the Teiid Server in a central managed location. Extension Module JAR files are stored in + <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> <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 the Teiid system + 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 @@ -272,7 +272,7 @@ <sect1> <title>Connector Archive File</title> <para>The Connector Archive file is a bundled version of all files needed by this Connector - to execute in the Teiid server. This file includes the Connector Type Definition file and + to execute in Teiid. This file includes the Connector Type Definition file and all the Extension Modules required by the Connector to create a connector archive file (CAF).. </para> <itemizedlist> @@ -310,7 +310,7 @@ <sect2> <title>Into Teiid Server</title> - <para>To use a new connector type definition in the Teiid Server, the Connector Archive + <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> @@ -368,7 +368,7 @@ <sect2> <title>In Console</title> - <para>To actually use your connector in the Teiid System, you must create a Connector + <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> @@ -418,7 +418,7 @@ <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 the Teiid Server using the Console to correct resources.</para> + when a VDB is deployed to Teiid using the Console to correct resources.</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 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-development-kit.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -116,7 +116,7 @@ </row> <row> <entry> - <para>setSecurityContext</para> + <para>setExecutionContext</para> </entry> <entry> <para>Sets the security context values currently being used to execute commands. @@ -212,10 +212,10 @@ <tbody> <row> <entry> - <para>createSecurityContext</para> + <para>createExecutionContext</para> </entry> <entry> - <para>Creates a securityContext instance.</para> + <para>Creates a ExecutionContext instance.</para> </entry> </row> <row> @@ -458,7 +458,7 @@ </row> <row> <entry> - <para>SetSecurityContext</para> + <para>SetExecutionContext</para> </entry> <entry> <para>VDBName VDBVersion UserName</para> Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/federate-info.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/federate-info.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/federate-info.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,24 +0,0 @@ -<chapter id="federate_info"> - <title>Connecting to Your Enterprise Information System</title> - - <para>The Teiid System offers your organization a way to manage and describe the information across your disparate enterprise information systems. You can even integrate these enterprise information systems into a single, complete data access solution using the Teiid Server.</para> - - <sect1 id="about_federate"> - <title>The Teiid System</title> - <para>The entire Teiid System is comprised of several interconnected products and services:</para> - - <figure id="federate-system"> - <title>Teiid System</title> - <graphic align="center" scale="100" fileref="../images/federate_system.png"/> - </figure> - - <para>The Teiid System, when used in its totality, enables your end user applications to process queries that select (and even update) data from one or more of your enterprise information sources, regardless of the native physical data storage method used by each enterprise information system. This means that a single query can access, reference, and return results from multiple integrated data sources.</para> - - <para>Within the Teiid System, the Teiid products (including the Teiid Designer, the Teiid Server), enable you to create and manage metadata models: representations describing the nature and content of your enterprise information systems.</para> - - <para>Once captured, this valuable metadata can searched, analyzed, and applied by applications throughout your enterprise.</para> - - </sect1> - -</chapter> - Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,9 +1,8 @@ <chapter id="introduction"> - <title>Connectors in the Teiid System</title> - <para>In the Teiid System, a connector handles all request-and-response related communications between the - data tier of the Teiid Server and the individual enterprise information sources, which can include - databases, data feeds, flat files, or any other entity you have modeled</para> - <para>In the Teiid Server, a connector is used to:</para> + <title>Connectors in Teiid</title> + <para>In Teiid a connector handles all communications with individual enterprise information sources, which can include + databases, data feeds, flat files, or any other entity you have modeled.</para> + <para>In Teiid, a connector is used to:</para> <itemizedlist> <listitem> <para>Translate a Teiid-specific command into a native command.</para> @@ -12,10 +11,10 @@ <para>Execute the command.</para> </listitem> <listitem> - <para>Return batches of results to the Teiid Server.</para> + <para>Return batches of results to Teiid.</para> </listitem> </itemizedlist> - <para>The Teiid Server is responsible for reassembling the results from one or more connectors into an + <para>Teiid is responsible for reassembling the results from one or more connectors into an answer for the user’s command.</para> <para> For a more detailed workflow, see the chapter @@ -26,8 +25,7 @@ <sect1> <title>Do You Need a New Connector?</title> <para>Teiid can provide several connectors for common enterprise information system types. If - you can use one of these enterprise information systems, you do not need to develop a custom one. Instead, - you can contact your Teiid Technical Account Manager and ask about purchasing the connector you need. + you can use one of these enterprise information systems, you do not need to develop a custom one. </para> <para>Teiid offers the following connectors:</para> <itemizedlist> @@ -35,7 +33,7 @@ <para> <emphasis>JDBC:</emphasis> Connects to many relational databases. The JDBC Connector is validated against the following database - systems: Oracle, Microsoft SQL Server, IBM DB2, MySQL and Sybase. In addition, the JDBC Connector can + systems: Oracle, Microsoft SQL Server, IBM DB2, MySQL, Postgres, Derby, and Sybase. In addition, the JDBC Connector can often be used with other 3rd-party drivers and provides a wide range of extensibility options to specialize behavior against those drivers. </para> @@ -43,7 +41,7 @@ <listitem> <para> <emphasis>Text:</emphasis> - Connects to ASCII text files. + Connects to text files. </para> </listitem> <listitem> @@ -52,9 +50,19 @@ Connects to XML files on disk or by invoking Web services on other enterprise systems. </para> </listitem> + <listitem> + <para> + <emphasis>LDAP</emphasis> + Connects to LDAP directory services. + </para> + </listitem> + <listitem> + <para> + <emphasis>Salesforce</emphasis> + Connects to Salesforce. + </para> + </listitem> </itemizedlist> - <para>If your enterprise information system can use one of these connectors, you do not need to develop your - own. Instead, you can contact Teiid about acquiring the connector you need.</para> </sect1> <sect1> <title>Required Items to Write a Custom Connector</title> @@ -71,9 +79,12 @@ <para>Configuration and connection information for the system</para> </listitem> <listitem> - <para>Metadata</para> + <para>Expectation for incoming queries/metadata</para> </listitem> <listitem> + <para>The SQL and processing constructs supported by information system.</para> + </listitem> + <listitem> <para>Required properties for the connector, such as URL, user name, etc.</para> </listitem> <listitem> @@ -103,11 +114,10 @@ <para>Test your connector with Connector Development Kit (CDK) test utilities.</para> </listitem> <listitem> - <para>Deploy your connector type into a Teiid Server using the Teiid Console.</para> + <para>Deploy your connector type into Teiid.</para> <itemizedlist> <listitem> - <para>Create your connector type definition file. Import the connector type definition file - </para> + <para>Create and import your connector type definition file.</para> </listitem> <listitem> <para>Create a connector binding using the connector type</para> @@ -118,13 +128,13 @@ </itemizedlist> </listitem> <listitem> - <para>Execute queries via the Teiid JDBC API or QueryBuilder</para> + <para>Execute queries via Teiid.</para> </listitem> </orderedlist> <para> This guide covers how to do each of these steps in detail. It also provides additional information for advanced topics, such as connection pooling, streaming large objects, and transactions. For a sample - connector code, please check the wiki pages at <ulink url="http://teiid.org">Teiid community</ulink> + connector code, please check the <ulink url="http://teiid.org">Teiid community</ulink> </para> </sect1> </chapter> \ No newline at end of file Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,150 +1,125 @@ <chapter id="lob_support"> - <title>Handling Large Objects</title> - <para>This chapter examines how to use facilities provided by the Teiid Connector API to - use large objects such as blobs, clobs, and xml in your connector.</para> - - <sect1> - <title>Large Objects</title> - - <sect2> - <title>Data Types</title> - <para>Teiid supports three large object runtime data types: blob, clob, and xml. - A blob is a “binary large object”, a clob is a “character large object”, and “xml” is a “xml - document”. Columns modeled as a blob, clob, or xml are treated similarly by the connector - framework to support memory-safe streaming. </para> - </sect2> - <sect2> - <title>Why Use Large Object Support?</title> - <para>The Teiid Server allows a Connector to return a large object through the - Teiid Connector API by just returning a reference to the actual large object. The - Teiid Server or JDBC Driver can then access the data via a stream rather than retrieving - the data all at once. This is useful for several reasons:</para> - <orderedlist> - <listitem> - <para>Reduces memory usage when returning the result set to the user.</para> - </listitem> - <listitem> - <para>Improves performance by passing less data in the result set.</para> - </listitem> - <listitem> - <para>Allows access to large objects when needed rather than assuming that users will - always use the large object data.</para> - </listitem> - <listitem> - <para>Allows the passing of arbitrarily large data values within a fixed Teiid - memory usage. </para> - </listitem> - </orderedlist> - <para>However, these benefits can only truly be gained if the Connector itself does not - materialize an entire large object all at once. For example, the JDBC API supports a - streaming interface for blob and clob data. </para> - </sect2> - </sect1> - - <sect1> - <title>Handling Large Objects</title> - <para>The Connector API supports the handling of the large objects (Blob/Clob/SQLXML) through - the creation of special purpose wrapper “type” objects. Each type of LOB object has a - respective wrapper object.</para> - - <table frame="all"> - <title>Lob Types</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*" /> - <colspec colname='c2' colwidth="1*" /> - <thead> - <row> - <entry>Java SQL Type</entry> - <entry>Runtime Type</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>java.sql.Blob</para> - </entry> - <entry> - <para>com.metamatrix.common.types.BlobType</para> - </entry> - </row> - <row> - <entry> - <para>java.sql.Clob</para> - </entry> - <entry> - <para>com.metematrix.common.types.ClobType</para> - </entry> - </row> - <row> - <entry> - <para>com.metamatrix.core.sql.SQLXML</para> - </entry> - <entry> - <para>com.metematrix.common.types.XMLType</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para>In the example below, the physical source returns an object type of Clob, then the - connector should return the corresponding ClobType object.</para> - - <programlisting><![CDATA[ -//Example BatchedExecution.execute method + <title>Handling Large Objects</title> + <para>This chapter examines how to use facilities provided by the Teiid + Connector API to + use large objects such as blobs, clobs, and xml in + your connector.</para> -List columnValues = new ArrayList(); + <sect1> + <title>Large Objects</title> -// building the reference -Clob clob = results.getClob(); -ClobType clobReference = new ClobType(clob); -… -// this is needed to keep the connection open. -executionContext.keepExecutionAlive(true); + <sect2> + <title>Data Types</title> + <para>Teiid supports three large object runtime data types: blob, + clob, and xml. + A blob is a “binary large object”, a clob is a + “character large + object”, and “xml” is a “xml + document”. Columns + modeled as a blob, clob, or xml are treated similarly by + the + connector + framework to support memory-safe streaming. </para> + </sect2> + <sect2> + <title>Why Use Large Object Support?</title> + <para>Teiid allows a Connector to return a large object through the + Teiid Connector API by just returning a reference to the actual + large object. Access to that LOB will be streamed as appropriate rather + than retrieved all at once. This + is useful for several reasons:</para> + <orderedlist> + <listitem> + <para>Reduces memory usage when returning the result set to the + user.</para> + </listitem> + <listitem> + <para>Improves performance by passing less data in the result set. + </para> + </listitem> + <listitem> + <para>Allows access to large objects when needed rather than + assuming that users will + always use the large object data.</para> + </listitem> + <listitem> + <para>Allows the passing of arbitrarily large data values.</para> + </listitem> + </orderedlist> + <para>However, these benefits can only truly be gained if the + Connector itself does not + materialize an entire large object all at + once. For example, the Java JDBC API + supports a + streaming interface + for blob and clob data. </para> + </sect2> + </sect1> -// adding the reference to batch of results -columnValues.add(clobReference); -batch.addRow(columnValues); - ]]></programlisting> - - <para>Once the wrapped object is returned, the streaming of LOB is automatically supported. These LOB objects then can - be used to serve to client results, used in server for query processing, or used in user defined - functions.</para> - - <para>A connector execution is usually closed and the underlying connection is either - closed/released as soon as all rows for that execution have been retrieved. However, LOB - objects may need to be read after their initial retrieval of results. It is very important that the - default closing behavior should be prevented to correctly stream the contents of the LOB based data. - This behavior is communicated to the server through setting a flag in “ExecutionContext” interface by invoking</para> - - <programlisting><![CDATA[ + <sect1> + <title>Handling Large Objects</title> + <para>The Connector API automatically handles large objects + (Blob/Clob/SQLXML) through + the creation of special purpose wrapper + objects when it retrieves results. + </para> + + <para>Once the wrapped object is returned, the streaming of LOB is + automatically supported. These LOB objects then can + for example appear + in client results, in user defined functions, or sent + to other + connectors.</para> + + <para>A connector execution is usually closed and the underlying + connection is either + closed/released as soon as all rows for that + execution have been retrieved. + However, LOB + objects may need to be + read after their initial retrieval of results. When + LOBs are detected + the default closing behavior + is prevented by setting a flag on the + ExecutionContext.</para> + + <para>Now the connector execution + only when the user Statement object + is closed. + Note that connectors may at their discretion have + executions delayed in their closure by directly setting the keep + alive on the ExecutionContext + </para> + + <programlisting><![CDATA[ executionContext.keepExecutionAlive(true); - ]]></programlisting> - - <para>with this call, the server will close the connector execution object only after all returned LOB - objects can no longer be read. i.e. when user Statement object is closed. Note that single call to keepExecutionAlive is needed per - execution – and it must be called before the first batch is returned from connector</para> - - <para>The SQLXML interface allows large xml documents to - be processed by the server without creating memory issues. XML Source Connectors also use this - interface to supply documents to the Teiid XQuery engine.</para> - <para>A new, and important, limitation of using the LOB type objects introduced in the 5.5 - version of the Teiid Server is that streaming is not supported from remote connectors. This - is an issue in clustered environments if connectors intended to return LOBs are deployed on only - a subset of the hosts or in failover situations. The most appropriate workaround to this - limitation is to deploy connectors intended to return LOBs on each host in the cluster. There is - currently no workaround to support streaming LOBs from connectors in remote failover situations.</para> - </sect1> - - <sect1> - <title>Inserting or Updating Large Objects</title> - <para>The Teiid JDBC API also allows the insertion or update of large objects. However, - the JDBC API does not currently stream large objects on insert or update. So, the Teiid - JDBC API will read all of the data and pass it back to the connector in a single materialized - value. </para> - <para>In these cases LOBs will be passed to the Connector in the language objects as an - ILiteral containing a java.sql.Blob, java.sql.Clob, or java.sql.SQLXML. You - can use these interfaces to retrieve the data in the large object and use it for insert or - update.</para> - </sect1> + ]]></programlisting> + + <para>An important limitation of using the LOB type objects + is that + streaming is not supported from remote connectors. + This is an issue in + clustered environments if connectors intended to return + LOBs are + deployed on only + a subset of the hosts or in failover situations. The + most appropriate + workaround to this + limitation is to deploy connectors + intended to return LOBs on each host in the + cluster.</para> + </sect1> + + <sect1> + <title>Inserting or Updating Large Objects</title> + <para>LOBs will be passed to the Connector in the + language objects as + an + ILiteral containing a java.sql.Blob, java.sql.Clob, or + java.sql.SQLXML. You + can use these interfaces to retrieve the data in + the large object and + use it for insert or + update.</para> + </sect1> </chapter> \ No newline at end of file Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/monitored-connector.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/monitored-connector.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/monitored-connector.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,98 +0,0 @@ -<chapter id="monitored_connectors"> - <title>Monitored Connectors</title> - <sect1> - <title>Overview</title> - <para>The Teiid Connector API contains an optional interface that allows connectors to - be automatically monitored by the Teiid Enterprise Server or checked via the Teiid - Admin API. </para> - </sect1> - <sect1> - <title>Monitored Connector Framework Overview</title> - <para>This UML diagram shows the classes involved in the monitored connector classes. - </para> - - <figure id="monitored-connector-framework"> - <title>Monitored Connector Class Diagram</title> - <graphic align="center" scale="100" fileref="../images/monitored-connector-framework.png" /> - </figure> - - <para>The table below lists the role of each class in the framework.</para> - - <table frame="all"> - <title>Monitored Connector Classes</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>Class</para> - </entry> - <entry> - <para>Type</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>MonitoredConnector</para> - </entry> - <entry> - <para>Interface</para> - </entry> - <entry> - <para>This interface can be added to the Connector implementation to indicate that - the connector supports monitoring. </para> - </entry> - </row> - <row> - <entry> - <para>ConnectionStatus</para> - </entry> - <entry> - <para>Class</para> - </entry> - <entry> - <para /> - </entry> - </row> - <row> - <entry> - <para>AliveStatus</para> - </entry> - <entry> - <para>Class</para> - </entry> - <entry> - <para>This class defines an enumeration for valid status values for a - ConnectionStatus.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect1> - <sect1> - <title>Using The Framework</title> - <para>To support connector monitoring, your Connector implementation must extend the - MonitoredConnector interface and implement the single getStatus() method to return a - ConnectionStatus. - </para> - <para>A monitored connector will be polled for status in the Teiid Enterprise Server - (connector monitoring is not supported on Teiid Query or Dimension products). The poll - rate is the value of the metamatrix.server.serviceMonitorInterval system property, which can - be set in the Teiid Console. This property defaults to 60 seconds. If the - ConnectionStatus indicates an AliveStatus of DEAD, then the connector is marked in the service - registry as “data source unavailable”. If the ConnectionStatus indicates an AliveStatus of - ALIVE, the connector is marked as “open”. An AliveStatus of UNKNOWN does not change the state - of the registry.</para> - <para>In addition, the Admin API can be used in Teiid Query and Teiid Enterprise to - obtain the status of connectors at runtime. For more information, see the Admin API Javadoc. - </para> - </sect1> -</chapter> \ No newline at end of file Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,58 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> - -<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<legalnotice id="Legal_Notice"> - <title>Legal Notice</title> - <para> - <address> - <street>1801 Varsity Drive</street> - <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> - <phone>Phone: +1 919 754 3700</phone> - <phone>Phone: 888 733 4281</phone> - <fax>Fax: +1 919 754 3701</fax> - <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> - </address> - </para> - <para> - Copyright <trademark class="copyright"/> 2008 by Red Hat, Inc. This copyrighted material is made available to - anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the - GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published - by the Free Software Foundation. - </para> - <para> - Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. - </para> - <para> - All other trademarks referenced herein are the property of their respective owners. - </para> - <para> - The GPG fingerprint of the security(a)redhat.com key is: - </para> - <para> - CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E - </para> -</legalnotice> Deleted: trunk/documentation/custom.dtd =================================================================== --- trunk/documentation/custom.dtd 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/custom.dtd 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,3 +0,0 @@ -<!ENTITY versionNumber "6.2.0"> -<!ENTITY copyrightYear "2009"> -<!ENTITY copyrightHolder "Red Hat, Inc."> Added: trunk/documentation/docbook/en-US/custom.dtd =================================================================== --- trunk/documentation/docbook/en-US/custom.dtd (rev 0) +++ trunk/documentation/docbook/en-US/custom.dtd 2009-09-11 21:42:50 UTC (rev 1344) @@ -0,0 +1,6 @@ +<!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>"> Added: trunk/documentation/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/docbook/en-US/legal_notice.xml (rev 0) +++ trunk/documentation/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -0,0 +1,61 @@ +<?xml version='1.0' encoding="UTF-8"?> + +<!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"> +%CustomDTD; +]> + +<legalnotice id="Legal_Notice"> + <title>Legal Notice</title> + <para> + <address> + <street>1801 Varsity Drive</street> + <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> + <phone>Phone: +1 919 754 3700</phone> + <phone>Phone: 888 733 4281</phone> + <fax>Fax: +1 919 754 3701</fax> + <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> + </address> + </para> + <para> + Copyright <trademark class="copyright"/> &copyrightYear; by &copyrightHolder; This copyrighted material is made available to + anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the + GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published + by the Free Software Foundation. + </para> + <para> + Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. + </para> + <para> + All other trademarks referenced herein are the property of their respective owners. + </para> + <para> + The GPG fingerprint of the security(a)redhat.com key is: + </para> + <para> + CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E + </para> +</legalnotice> 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/jdbc-connector.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -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 "../../../../../custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> %CustomDTD; ]> @@ -35,19 +35,11 @@ <releaseinfo>&versionNumber;</releaseinfo> <productnumber>&versionNumber;</productnumber> <issuenum>1</issuenum> - <mediaobject> - <imageobject role="fo"> - <imagedata fileref="images/logo.png" align="center"/> - </imageobject> - <imageobject role="html"> - <imagedata fileref="images/logo.png" depth="3cm" /> - </imageobject> - </mediaobject> <copyright> <year>&copyrightYear;</year> <holder>&copyrightHolder;</holder> </copyright> - <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> <toc/> Deleted: trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/jdbc-connector-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,58 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> - -<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<legalnotice id="Legal_Notice"> - <title>Legal Notice</title> - <para> - <address> - <street>1801 Varsity Drive</street> - <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> - <phone>Phone: +1 919 754 3700</phone> - <phone>Phone: 888 733 4281</phone> - <fax>Fax: +1 919 754 3701</fax> - <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> - </address> - </para> - <para> - Copyright <trademark class="copyright"/> 2008 by Red Hat, Inc. This copyrighted material is made available to - anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the - GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published - by the Free Software Foundation. - </para> - <para> - Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. - </para> - <para> - All other trademarks referenced herein are the property of their respective owners. - </para> - <para> - The GPG fingerprint of the security(a)redhat.com key is: - </para> - <para> - CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E - </para> -</legalnotice> Deleted: trunk/documentation/quick-start-example/src/main/docbook/en-US/images/logo.png =================================================================== (Binary files differ) Deleted: trunk/documentation/quick-start-example/src/main/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/quick-start-example/src/main/docbook/en-US/legal_notice.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/quick-start-example/src/main/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,58 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> - -<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<legalnotice id="Legal_Notice"> - <title>Legal Notice</title> - <para> - <address> - <street>1801 Varsity Drive</street> - <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> - <phone>Phone: +1 919 754 3700</phone> - <phone>Phone: 888 733 4281</phone> - <fax>Fax: +1 919 754 3701</fax> - <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> - </address> - </para> - <para> - Copyright <trademark class="copyright"/> 2009 by Red Hat, Inc. This copyrighted material is made available to - anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the - GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published - by the Free Software Foundation. - </para> - <para> - Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. - </para> - <para> - All other trademarks referenced herein are the property of their respective owners. - </para> - <para> - The GPG fingerprint of the security(a)redhat.com key is: - </para> - <para> - CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E - </para> -</legalnotice> 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/quick-start-example/src/main/docbook/en-US/quick_start_example.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -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 "../../../../../custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> %CustomDTD; ]> @@ -37,21 +37,13 @@ <productnumber>&versionNumber; </productnumber> <issuenum>1</issuenum> - <mediaobject> - <imageobject role="fo"> - <imagedata fileref="images/logo.png" align="center" /> - </imageobject> - <imageobject role="html"> - <imagedata fileref="images/logo.png" depth="3cm" /> - </imageobject> - </mediaobject> <copyright> <year>&copyrightYear; </year> <holder>&copyrightHolder; </holder> </copyright> - <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> <toc /> <xi:include href="content/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Modified: trunk/documentation/reference/src/main/docbook/en-US/Reference.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/Reference.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/reference/src/main/docbook/en-US/Reference.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -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 "../../../../../custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> %CustomDTD; ]> @@ -37,21 +37,13 @@ <productnumber>&versionNumber; </productnumber> <issuenum>1</issuenum> -  <copyright> <year>&copyrightYear; </year> <holder>&copyrightHolder; </holder> </copyright> - <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> <toc /> <xi:include href="content/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Deleted: trunk/documentation/reference/src/main/docbook/en-US/images/logo.png =================================================================== (Binary files differ) Deleted: trunk/documentation/reference/src/main/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/legal_notice.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/reference/src/main/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,58 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> - -<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<legalnotice id="Legal_Notice"> - <title>Legal Notice</title> - <para> - <address> - <street>1801 Varsity Drive</street> - <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> - <phone>Phone: +1 919 754 3700</phone> - <phone>Phone: 888 733 4281</phone> - <fax>Fax: +1 919 754 3701</fax> - <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> - </address> - </para> - <para> - Copyright <trademark class="copyright"/> 2008 by Red Hat, Inc. This copyrighted material is made available to - anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the - GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published - by the Free Software Foundation. - </para> - <para> - Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. - </para> - <para> - All other trademarks referenced herein are the property of their respective owners. - </para> - <para> - The GPG fingerprint of the security(a)redhat.com key is: - </para> - <para> - CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E - </para> -</legalnotice> Deleted: trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/images/logo.png =================================================================== (Binary files differ) Deleted: trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,58 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> - -<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<legalnotice id="Legal_Notice"> - <title>Legal Notice</title> - <para> - <address> - <street>1801 Varsity Drive</street> - <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> - <phone>Phone: +1 919 754 3700</phone> - <phone>Phone: 888 733 4281</phone> - <fax>Fax: +1 919 754 3701</fax> - <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> - </address> - </para> - <para> - Copyright <trademark class="copyright"/> 2009 by Red Hat, Inc. This copyrighted material is made available to - anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the - GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published - by the Free Software Foundation. - </para> - <para> - Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. - </para> - <para> - All other trademarks referenced herein are the property of their respective owners. - </para> - <para> - The GPG fingerprint of the security(a)redhat.com key is: - </para> - <para> - CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E - </para> -</legalnotice> 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/salesforce-connector-guide/src/main/docbook/en-US/salesforce_connector_guide.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -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 "../../../../../custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> %CustomDTD; ]> @@ -36,21 +36,13 @@ <productnumber>&versionNumber; </productnumber> <issuenum>1</issuenum> - <mediaobject> - <imageobject role="fo"> - <imagedata fileref="images/logo.png" align="center" /> - </imageobject> - <imageobject role="html"> - <imagedata fileref="images/logo.png" depth="3cm" /> - </imageobject> - </mediaobject> <copyright> <year>&copyrightYear; </year> <holder>&copyrightHolder; </holder> </copyright> - <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> <toc /> <xi:include href="content/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Deleted: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/legal_notice.xml =================================================================== --- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 20:34:45 UTC (rev 1343) +++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/legal_notice.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -1,58 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> - -<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<legalnotice id="Legal_Notice"> - <title>Legal Notice</title> - <para> - <address> - <street>1801 Varsity Drive</street> - <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> - <phone>Phone: +1 919 754 3700</phone> - <phone>Phone: 888 733 4281</phone> - <fax>Fax: +1 919 754 3701</fax> - <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> - </address> - </para> - <para> - Copyright <trademark class="copyright"/> 2008 by Red Hat, Inc. This copyrighted material is made available to - anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the - GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published - by the Free Software Foundation. - </para> - <para> - Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. - </para> - <para> - All other trademarks referenced herein are the property of their respective owners. - </para> - <para> - The GPG fingerprint of the security(a)redhat.com key is: - </para> - <para> - CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E - </para> -</legalnotice> 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 20:34:45 UTC (rev 1343) +++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml 2009-09-11 21:42:50 UTC (rev 1344) @@ -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 "../../../../../custom.dtd"> +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/en-US/custom.dtd"> %CustomDTD; ]> @@ -36,19 +36,11 @@ <releaseinfo>&versionNumber;</releaseinfo> <productnumber>&versionNumber;</productnumber> <issuenum>1</issuenum> - <mediaobject> - <imageobject role="fo"> - <imagedata fileref="images/logo.png" align="center"/> - </imageobject> - <imageobject role="html"> - <imagedata fileref="images/logo.png" depth="3cm" /> - </imageobject> - </mediaobject> <copyright> <year>&copyrightYear;</year> <holder>&copyrightHolder;</holder> </copyright> - <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </bookinfo> <toc/>

16 years, 7 months

1
0
0 / 0

teiid SVN: r1343 - trunk/test-integration/db/src/test/java/org/teiid/test/testcases.

by teiid-commits＠lists.jboss.org

Author: vhalbert(a)redhat.com Date: 2009-09-11 16:34:45 -0400 (Fri, 11 Sep 2009) New Revision: 1343 Removed: trunk/test-integration/db/src/test/java/org/teiid/test/testcases/Alltaests.java Log: Teiid 773 - organize integration test Deleted: trunk/test-integration/db/src/test/java/org/teiid/test/testcases/Alltaests.java =================================================================== --- trunk/test-integration/db/src/test/java/org/teiid/test/testcases/Alltaests.java 2009-09-11 20:01:16 UTC (rev 1342) +++ trunk/test-integration/db/src/test/java/org/teiid/test/testcases/Alltaests.java 2009-09-11 20:34:45 UTC (rev 1343) @@ -1,32 +0,0 @@ -/* - * Copyright � 2000-2008 MetaMatrix, Inc. - * All rights reserved. - */ -package org.teiid.test.testcases; - -import junit.framework.Test; -import junit.framework.TestSuite; - - - -/** - * @since 1.0 - */ -public class Alltaests { - - public static void main(String[] args) { - junit.textui.TestRunner.run(Alltaests.suite()); - } - - public static Test suite() { - TestSuite suite = new TestSuite("All Integration Tests"); //$NON-NLS-1$ - //$JUnit-BEGIN$ - // suite.addTestSuite(LocalTransactionTests.class); - - //$JUnit-END$ - return suite; - } - - - -}

16 years, 7 months

1
0
0 / 0

teiid SVN: r1342 - in trunk/test-integration/db: src and 1 other directory.

by teiid-commits＠lists.jboss.org

Author: vhalbert(a)redhat.com Date: 2009-09-11 16:01:16 -0400 (Fri, 11 Sep 2009) New Revision: 1342 Added: trunk/test-integration/db/howto Removed: trunk/test-integration/db/src/howto Log: Teiid 773 - organize integration test Copied: trunk/test-integration/db/howto (from rev 1341, trunk/test-integration/db/src/howto) =================================================================== --- trunk/test-integration/db/howto (rev 0) +++ trunk/test-integration/db/howto 2009-09-11 20:01:16 UTC (rev 1342) @@ -0,0 +1,52 @@ +This is a howto of the following: + +1. Creating unit tests that use 1 or more datasources +2. Setting up a datasource to be used during testing +3. Executing the db integration tests + + +========================================== +Creating Unit Tests +========================================== + +- Unit test should be created under db/src/test/java +- See SingleSourceTransactionTest.java as an example + + NOTE: the current tests are currently organized by the number of datasources they require in order + to give some organization to the test for tracking purposes. + +- Test should extend org.teiid.transaction.test.BaseAbstractTransactionTestCase + + +- NOTE: the following is used in a post test phase of validating the data in the datasource +- when calling: this.getSource("modelname") --- the "modelname" represents the model for which + you want the connection for + + INFO: to know which source this model is mapped to, find the config properties file being + loaded for this test (default is the default-config.properties) and look for + the model-to-datasource mapping(s) + + The default Transaction.vdb has 2 models: pm1 and pm2 + + +========================================== +Setting up a Datasource to be used during Testing +========================================== + +- see the readme.txt in src/main/resources/datasources regarding defining a datasource +- run the maven profile to execute the process to create the required tables: + a. to setup all sources at one time, run: mvn install -P setupdatasources + b. to setup a specific source, run: mvn install -P singledatasource -Ddatasource=derby + + +========================================== +Executing the db integration tests +========================================== + +The default profile in the pom.xml is set to compile and run the test. So running: mvn clean install +will compile and run the test. +It does not run and setup a datasource. See above "Setting up a Datasource to be used during Testing". + + + + \ No newline at end of file Deleted: trunk/test-integration/db/src/howto =================================================================== --- trunk/test-integration/db/src/howto 2009-09-11 19:53:36 UTC (rev 1341) +++ trunk/test-integration/db/src/howto 2009-09-11 20:01:16 UTC (rev 1342) @@ -1,52 +0,0 @@ -This is a howto of the following: - -1. Creating unit tests that use 1 or more datasources -2. Setting up a datasource to be used during testing -3. Executing the db integration tests - - -========================================== -Creating Unit Tests -========================================== - -- Unit test should be created under db/src/test/java -- See SingleSourceTransactionTest.java as an example - - NOTE: the current tests are currently organized by the number of datasources they require in order - to give some organization to the test for tracking purposes. - -- Test should extend org.teiid.transaction.test.BaseAbstractTransactionTestCase - - -- NOTE: the following is used in a post test phase of validating the data in the datasource -- when calling: this.getSource("modelname") --- the "modelname" represents the model for which - you want the connection for - - INFO: to know which source this model is mapped to, find the config properties file being - loaded for this test (default is the default-config.properties) and look for - the model-to-datasource mapping(s) - - The default Transaction.vdb has 2 models: pm1 and pm2 - - -========================================== -Setting up a Datasource to be used during Testing -========================================== - -- see the readme.txt in src/main/resources/datasources regarding defining a datasource -- run the maven profile to execute the process to create the required tables: - a. to setup all sources at one time, run: mvn install -P setupdatasources - b. to setup a specific source, run: mvn install -P singledatasource -Ddatasource=derby - - -========================================== -Executing the db integration tests -========================================== - -The default profile in the pom.xml is set to compile and run the test. So running: mvn clean install -will compile and run the test. -It does not run and setup a datasource. See above "Setting up a Datasource to be used during Testing". - - - - \ No newline at end of file

16 years, 7 months

1
0
0 / 0

teiid SVN: r1341 - trunk/test-integration/db/src.

by teiid-commits＠lists.jboss.org

Author: vhalbert(a)redhat.com Date: 2009-09-11 15:53:36 -0400 (Fri, 11 Sep 2009) New Revision: 1341 Modified: trunk/test-integration/db/src/howto Log: Teiid 773 - organize integration test Modified: trunk/test-integration/db/src/howto =================================================================== --- trunk/test-integration/db/src/howto 2009-09-11 19:45:30 UTC (rev 1340) +++ trunk/test-integration/db/src/howto 2009-09-11 19:53:36 UTC (rev 1341) @@ -10,10 +10,14 @@ ========================================== - Unit test should be created under db/src/test/java -- See LocalTransactionTests.java as an example -- Test should extend org.teiid.transaction.test.AbstractTransactionTestCase +- See SingleSourceTransactionTest.java as an example + NOTE: the current tests are currently organized by the number of datasources they require in order + to give some organization to the test for tracking purposes. + +- Test should extend org.teiid.transaction.test.BaseAbstractTransactionTestCase + - NOTE: the following is used in a post test phase of validating the data in the datasource - when calling: this.getSource("modelname") --- the "modelname" represents the model for which you want the connection for @@ -30,16 +34,17 @@ ========================================== - see the readme.txt in src/main/resources/datasources regarding defining a datasource -- run the maven profile to create the required tables: - a. to setup all sources at one time, run: mvn -P setupdatasources - b. to setup a specific source, run: mvn -P singledatasource -Ddatasource=derby +- run the maven profile to execute the process to create the required tables: + a. to setup all sources at one time, run: mvn install -P setupdatasources + b. to setup a specific source, run: mvn install -P singledatasource -Ddatasource=derby ========================================== Executing the db integration tests ========================================== -The default profile in the pom.xml is to compile and run the test. +The default profile in the pom.xml is set to compile and run the test. So running: mvn clean install +will compile and run the test. It does not run and setup a datasource. See above "Setting up a Datasource to be used during Testing".

16 years, 7 months

1
0
0 / 0

teiid SVN: r1340 - trunk/test-integration/db/src/main/resources.

by teiid-commits＠lists.jboss.org

Author: vhalbert(a)redhat.com Date: 2009-09-11 15:45:30 -0400 (Fri, 11 Sep 2009) New Revision: 1340 Removed: trunk/test-integration/db/src/main/resources/mysql/ Log: Teiid 773 - organize integration test

16 years, 7 months

1
0
0 / 0

teiid SVN: r1339 - in trunk/test-integration/db/src/main/resources: mysql and 1 other directory.

by teiid-commits＠lists.jboss.org

Author: vhalbert(a)redhat.com Date: 2009-09-11 15:42:02 -0400 (Fri, 11 Sep 2009) New Revision: 1339 Removed: trunk/test-integration/db/src/main/resources/mysql/connection.properties Modified: trunk/test-integration/db/src/main/resources/datasources/readme.txt Log: Teiid 773 - organize integration test Modified: trunk/test-integration/db/src/main/resources/datasources/readme.txt =================================================================== --- trunk/test-integration/db/src/main/resources/datasources/readme.txt 2009-09-11 19:41:19 UTC (rev 1338) +++ trunk/test-integration/db/src/main/resources/datasources/readme.txt 2009-09-11 19:42:02 UTC (rev 1339) @@ -3,7 +3,9 @@ To setup a datasource, do the following: -1. open datasource_mapping.xml to see the name of the directory ("dir") name to use associated the type of datasource -1. create the directory, if it doesn't exist -2. create (or place) a connection.properties file in the newly created directory -3. \ No newline at end of file +1. open datasource_mapping.xml and find the datasource you would like to setup. + Use the name of the directory ("dir") as the name of the folder to create for the datasource. +1. create the directory (if it doesn't exist) +2. create (or place) a connection.properties file in the newly created directory. See the + example_connection.properties in the derby directory as a starting point. + \ No newline at end of file Deleted: trunk/test-integration/db/src/main/resources/mysql/connection.properties =================================================================== --- trunk/test-integration/db/src/main/resources/mysql/connection.properties 2009-09-11 19:41:19 UTC (rev 1338) +++ trunk/test-integration/db/src/main/resources/mysql/connection.properties 2009-09-11 19:42:02 UTC (rev 1339) @@ -1,22 +0,0 @@ -db.type=mysql -driver=com.mysql.jdbc.Driver -URL=jdbc:mysql://slntds03.mm.atl2.redhat.com:3306/rep_unit_test -User=rep_unit_test -#rep_unit_test -Password=mm - -servername=slntds03.mm.atl2.redhat.com -databasename=rep_unit_test -portnumber=3306 -ds-jndiname=slntds03_mysql - -Immutable=true - -#adminuser=root -#adminpassword=mmroot -#adminurl=jdbc:mysql://slntds03.mm.atl2.redhat.com:3306 - - - - -

16 years, 7 months

1
0
0 / 0

teiid SVN: r1338 - trunk/test-integration/db/src/main/resources/datasources/derby.

by teiid-commits＠lists.jboss.org

Author: vhalbert(a)redhat.com Date: 2009-09-11 15:41:19 -0400 (Fri, 11 Sep 2009) New Revision: 1338 Modified: trunk/test-integration/db/src/main/resources/datasources/derby/example_connection.properties Log: Teiid 773 - organize integration test Modified: trunk/test-integration/db/src/main/resources/datasources/derby/example_connection.properties =================================================================== --- trunk/test-integration/db/src/main/resources/datasources/derby/example_connection.properties 2009-09-11 19:41:04 UTC (rev 1337) +++ trunk/test-integration/db/src/main/resources/datasources/derby/example_connection.properties 2009-09-11 19:41:19 UTC (rev 1338) @@ -1,3 +1,4 @@ +# db.type must match a ddl folder and it also represents the ANT sql datatype used during execution db.type=derby driver=org.apache.derby.jdbc.ClientDriver URL=jdbc:derby://localhost:1527//(derby location) @@ -5,7 +6,7 @@ Password= servername=localhost -databasename= +databasename=(databasename) portnumber=1527 ds-jndiname=localhost_1527

16 years, 7 months

1
0
0 / 0

teiid SVN: r1337 - in trunk/test-integration/db/src/main/resources/datasources: mysql and 1 other directory.

by teiid-commits＠lists.jboss.org

Author: vhalbert(a)redhat.com Date: 2009-09-11 15:41:04 -0400 (Fri, 11 Sep 2009) New Revision: 1337 Added: trunk/test-integration/db/src/main/resources/datasources/mysql/ trunk/test-integration/db/src/main/resources/datasources/mysql/example_connection.properties Log: Teiid 773 - organize integration test Copied: trunk/test-integration/db/src/main/resources/datasources/mysql (from rev 1328, trunk/test-integration/db/src/main/resources/mysql) Added: trunk/test-integration/db/src/main/resources/datasources/mysql/example_connection.properties =================================================================== --- trunk/test-integration/db/src/main/resources/datasources/mysql/example_connection.properties (rev 0) +++ trunk/test-integration/db/src/main/resources/datasources/mysql/example_connection.properties 2009-09-11 19:41:04 UTC (rev 1337) @@ -0,0 +1,18 @@ +# db.type must match a ddl folder and it also represents the ANT sql datatype used during execution +db.type=mysql +driver=com.mysql.jdbc.Driver +URL=jdbc:mysql://(servername):3306/(databasename) +User= +Password= + +servername=(servername) +databasename=(databasename) +portnumber=3306 +ds-jndiname=mysql_3306 + +Immutable=true + + + + + Property changes on: trunk/test-integration/db/src/main/resources/datasources/mysql/example_connection.properties ___________________________________________________________________ Name: svn:mime-type + text/plain

16 years, 7 months

1
0
0 / 0

teiid SVN: r1336 - trunk/test-integration/db/src/main/resources/ddl.

by teiid-commits＠lists.jboss.org

Author: vhalbert(a)redhat.com Date: 2009-09-11 15:31:15 -0400 (Fri, 11 Sep 2009) New Revision: 1336 Removed: trunk/test-integration/db/src/main/resources/ddl/adminparms.txt Log: Teiid 773 - organize integration test - removing file that isn't needed Deleted: trunk/test-integration/db/src/main/resources/ddl/adminparms.txt =================================================================== --- trunk/test-integration/db/src/main/resources/ddl/adminparms.txt 2009-09-11 19:29:32 UTC (rev 1335) +++ trunk/test-integration/db/src/main/resources/ddl/adminparms.txt 2009-09-11 19:31:15 UTC (rev 1336) @@ -1,57 +0,0 @@ -sa --- DB2 parms - (databasename) - (username) - - On DB2, remember an OS user must be created first with the same name as the db2user - - --- oracle parms -(username) -(password) - --- mysql -(username) -(password) - --- postgres -(username) -(password) - --- sqlserver -(username) -(password) --- On sql server, CHECK AND CHANGE THE PATH OF THE DATAFILES TO WHAT YOUR DB IS SETUP WITH - - -SQLSERVER -slntdb02 2000 (8.00.859) Repositories sa mmsa -slntds05 2000 (8.00.859) Data Source sa mmsa -slntdb07 2005 (9.00.1399.06) Repositories sa metamatrix -ENGNTDBS14 2008 sa metamatrix - -ORACLE -slntdb03, SID=DB03 9i (9.2.0.4.0) Repositories system mmsystem -slntdb08, SID=DB08 10g (10.1.0.2.0) Repositories system mmsystem -slntds04, SID=DS04 9i (9.2.0.1.0) Data Source system mmsystem -slntds08, SID=DS08 10g (10.1.0.2.0) Data Source system mmsystem -dbo3 machine administrator quad -ds04 administrator jboss42 -englxdbs11 11 sys mm system mm - -DB2 -slntds05, DATABASE=DS05 8.1.11.973(Previously 8.1.8.762) Data Source db2admin mm -ENGNTDBS12 db2admin mm - -SYBASE -slntds17 12.5.1 Data Source sa metamatrix - -MYSQL -slntds03 4.1.14 Data Source root mmroot -slwxp174 5 root mmroot - -POSTGRESQL -slntds04 8.3 both metamatrix -slntds11 8.1.2 Data Source postgres metamatrix - - -* For Oracle system will do to create users, but for admin work I use sys/mmsys as SYSDBA login

16 years, 7 months

1
0
0 / 0

2026

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

teiid-commits September 2009