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

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"?> -<!-- - - JBoss, Home of Professional Open Source. - Copyright (C) 2008 Red Hat, Inc. - Licensed to Red Hat, Inc. under one or more contributor - license agreements. See the copyright.txt file in the - distribution for a full listing of individual contributors. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301 USA. - ---> -<!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 =, &gt;, &lt;, 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 =, &gt;, &lt;, etc.</para></listitem> + <listitem><para><code>IBaseInCriteria</code> – base class for an IN criteria</para></listitem> + <listitem><para><code>IInCriteria</code> – represents an IN criteria that has a set of expressions for values</para></listitem> + <listitem><para><code>ISubqueryInCriteria</code> – represents an IN criteria that uses a subquery to produce the value set</para></listitem> + <listitem><para><code>IIsNullCriteria</code> – represents an IS NULL criteria</para></listitem> + <listitem><para><code>IExistsCriteria</code> – represents an EXISTS criteria that determines whether a subquery will return any values</para></listitem> + <listitem><para><code>ILikeCriteria</code> – represents a LIKE criteria that compares string values</para></listitem> </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"?> -<!-- - - JBoss, Home of Professional Open Source. - Copyright (C) 2008 Red Hat, Inc. - Licensed to Red Hat, Inc. under one or more contributor - license agreements. See the copyright.txt file in the - distribution for a full listing of individual contributors. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301 USA. - ---> -<!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"?> +<!-- + + JBoss, Home of Professional Open Source. + Copyright (C) 2008 Red Hat, Inc. + Licensed to Red Hat, Inc. under one or more contributor + license agreements. See the copyright.txt file in the + distribution for a full listing of individual contributors. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301 USA. + +--> +<!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"?> -<!-- - - JBoss, Home of Professional Open Source. - Copyright (C) 2008 Red Hat, Inc. - Licensed to Red Hat, Inc. under one or more contributor - license agreements. See the copyright.txt file in the - distribution for a full listing of individual contributors. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301 USA. - ---> -<!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"?> -<!-- - - JBoss, Home of Professional Open Source. - Copyright (C) 2008 Red Hat, Inc. - Licensed to Red Hat, Inc. under one or more contributor - license agreements. See the copyright.txt file in the - distribution for a full listing of individual contributors. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301 USA. - ---> -<!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> - <!-- <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/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"?> -<!-- - - JBoss, Home of Professional Open Source. - Copyright (C) 2008 Red Hat, Inc. - Licensed to Red Hat, Inc. under one or more contributor - license agreements. See the copyright.txt file in the - distribution for a full listing of individual contributors. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301 USA. - ---> -<!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"?> -<!-- - - JBoss, Home of Professional Open Source. - Copyright (C) 2008 Red Hat, Inc. - Licensed to Red Hat, Inc. under one or more contributor - license agreements. See the copyright.txt file in the - distribution for a full listing of individual contributors. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301 USA. - ---> -<!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"?> -<!-- - - JBoss, Home of Professional Open Source. - Copyright (C) 2008 Red Hat, Inc. - Licensed to Red Hat, Inc. under one or more contributor - license agreements. See the copyright.txt file in the - distribution for a full listing of individual contributors. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301 USA. - ---> -<!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/>