[teiid-commits] teiid SVN: r2622 - in branches/7.1.x/documentation/developer-guide: src/main/docbook/en-US and 1 other directories.

Author: shawkins Date: 2010-10-04 10:46:41 -0400 (Mon, 04 Oct 2010) New Revision: 2622 Added: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Book_Info.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Developer_Guide.xml Removed: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/main.xml Modified: branches/7.1.x/documentation/developer-guide/pom.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/logging.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/security.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml Log: TEIID-1285 TEIID-1286 updating the developer's guide and fixing a broken link Modified: branches/7.1.x/documentation/developer-guide/pom.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/pom.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/pom.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -36,7 +36,7 @@ </dependency> </dependencies> <configuration> - <sourceDocumentName>main.xml</sourceDocumentName> + <sourceDocumentName>Developer_Guide.xml</sourceDocumentName> <imageResource> <directory>${basedir}/src/main/docbook/en-US</directory> <excludes> Added: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Book_Info.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Book_Info.xml (rev 0) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Book_Info.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -0,0 +1,37 @@ +<?xml version="1.0" ?> +<!DOCTYPE bookinfo PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> +%CustomDTD; +]> + +<bookinfo> + <title>Teiid - Scalable Information Integration</title> + <subtitle>Teiid Developer's Guide</subtitle> + <releaseinfo>&versionNumber;</releaseinfo> + <productnumber>&versionNumber;</productnumber> + <issuenum>1</issuenum> + + <abstract> + <para> + This guide contains information for developers creating custom solutions + with Teiid. It covers creating JEE JCA connectors with the Teiid framework, + Teiid Translators, Teiid User Defined Functions (UDFs) as well as related topics. + </para> + </abstract> + + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/images/title_logo.svg"/> + </imageobject> + </inlinemediaobject> + </corpauthor> + + <copyright> + <year>&copyrightYear;</year> + <holder>&copyrightHolder;</holder> + </copyright> + + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</bookinfo> Property changes on: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Book_Info.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Added: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Developer_Guide.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Developer_Guide.xml (rev 0) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Developer_Guide.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -0,0 +1,23 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> +%CustomDTD; +]> + +<book> + <xi:include href="Book_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/develop-adapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/translator-api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/extending-jdbc.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/udf.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/adminapi.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/appendix-b.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + +</book> + Property changes on: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/Developer_Guide.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -2,56 +2,70 @@ <title>ra.xml file Template</title> <para> This appendix contains an example of the ra.xml file that can be used as a template when creating a new Connector.</para> - <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> - + <programlisting role="XML" language="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://java.sun.com/xml/ns/j2ee" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee - http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" - version="1.5"> + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee + http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" version="1.5"> <vendor-name>${comapany-name}</vendor-name> <eis-type>${type-of-connector}</eis-type> <resourceadapter-version>1.0</resourceadapter-version> <license> - <description> - ${license text} - </description> + <description>${license text}</description> <license-required>true</license-required> </license> + <resourceadapter> <resourceadapter-class>org.teiid.resource.spi.BasicResourceAdapter</resourceadapter-class> - <outbound-resourceadapter> <connection-definition> - <managedconnectionfactory-class>${connection-factory-class}</managedconnectionfactory-class> + <managedconnectionfactory-class>${connection-factory}</managedconnectionfactory-class> <!-- repeat for every configuration property --> <config-property> - <description>{$display:"${short-name}",$description:"${description}", $allowed:[${value-list}], $required:"${required-boolean}", $defaultValue:"${default-value}"}</description> - <config-property-name>${property-name}</config-property-name> - <config-property-type>${property-type}</config-property-type> - <config-property-value>${optional-property-value}</config-property-value> + <description> + {$display:"${short-name}",$description:"${description}",$allowed:[${value-list}], + $required:"${required-boolean}", $defaultValue:"${default-value}"} + </description> + <config-property-name>${property-name}</config-property-name> + <config-property-type>${property-type}</config-property-type> + <config-property-value>${optional-property-value}</config-property-value> </config-property> - + <!-- use the below as is if you used the Connection Factory interface --> - - <connectionfactory-interface>javax.resource.cci.ConnectionFactory</connectionfactory-interface> - <connectionfactory-impl-class>org.teiid.resource.spi.WrappedConnectionFactory</connectionfactory-impl-class> - <connection-interface>javax.resource.cci.Connection</connection-interface> - <connection-impl-class>org.teiid.resource.spi.WrappedConnection</connection-impl-class> + <connectionfactory-interface> + javax.resource.cci.ConnectionFactory + </connectionfactory-interface> + <connectionfactory-impl-class> + org.teiid.resource.spi.WrappedConnectionFactory + </connectionfactory-impl-class> + + <connection-interface> + javax.resource.cci.Connection + </connection-interface> + + <connection-impl-class> + org.teiid.resource.spi.WrappedConnection + </connection-impl-class> + </connection-definition> - + <transaction-support>NoTransaction</transaction-support> - - <authentication-mechanism> + + <authentication-mechanism> <authentication-mechanism-type>BasicPassword</authentication-mechanism-type> - <credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface> - </authentication-mechanism> - <reauthentication-support>false</reauthentication-support> + <credential-interface> + javax.resource.spi.security.PasswordCredential + </credential-interface> + </authentication-mechanism> + <reauthentication-support>false</reauthentication-support> + </outbound-resourceadapter> + </resourceadapter> + </connector>]]></programlisting> <para>${...} indicates a value to be supplied by the developer.</para> -</appendix> \ No newline at end of file +</appendix> Modified: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/develop-adapter.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -10,11 +10,11 @@ developers, we provided a base implementation framework. If you already have a JCA Connector or some other mechanism to get data from your source system, you can skip this chapter.</para> - <para>If you are not familiar with JCA API, please read the <ulink url="http://java.sun.com/j2ee/connector/">JCA 1.5 Specification</ulink>. + <para>If you are not familiar with JCA API, please read the JCA 1.5 Specification at <ulink url="http://java.sun.com/j2ee/connector/"/>;. There are lot of online tutorials on how to design and build a JCA Connector. The below we show you to build very simple connector, however building actual connector that supports transactions, security can get much more complex.</para> - <para>Check out the following links <ulink url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch7.chapt.htm... on JBoss</ulink> </para> + <para>Refer to the JBoss Application Server Connectors documentation at <ulink url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch7.chapt.htm... <section> <title>Using the Teiid Framework</title> @@ -45,46 +45,44 @@ attribute for each configuration variable, and then provide both "getter" and "setter" methods for them. Note to use only "java.lang" objects as the attributes, DO NOT use Java primitives for defining and accessing the properties. See the following code for an example.</para> - <programlisting><![CDATA[public class MyManagedConnectionFactory extends BasicManagedConnectionFactory { - @Override - public Object createConnectionFactory() throws ResourceException { - return new MyConnectionFactory(); - } - - // config property name (metadata for these are defined inside the ra.xml) - String userName; - public String getUserName() { - return this.userName; - } - public void setUserName(String name) { - this.userName = name; - } - - // config property count (metadata for these are defined inside the ra.xml) - Integer count; - public Integer getCount() { - return this.count; - } - public void setCount(Integer value) { - this.count = value; - } + <programlisting language="Java" role="JAVA"><![CDATA[public class MyManagedConnectionFactory extends BasicManagedConnectionFactory +{ + @Override + public Object createConnectionFactory() throws ResourceException + { + return new MyConnectionFactory(); + } + + // config property name (metadata for these are defined inside the ra.xml) + String userName; + public String getUserName() { return this.userName; } + public void setUserName(String name){ this.userName = name; } + + // config property count (metadata for these are defined inside the ra.xml) + Integer count; + public Integer getCount() { return this.count; } + public void setCount(Integer value) { this.count = value; } + }]]></programlisting> </section> <section> <title>Define the Connection Factory class</title> <para>Extend the <code>BasicConnectionFactory</code> class, and provide a implementation for the "getConnection()" method.</para> - <programlisting><![CDATA[public class MyConnectionFactory extends BasicConnectionFactory { - @Override - public MyConnection getConnection() throws ResourceException { - return new MyConnection(); - } + <programlisting language="Java" role="JAVA"><![CDATA[public class MyConnectionFactory extends BasicConnectionFactory +{ + @Override + public MyConnection getConnection() throws ResourceException + { + return new MyConnection(); + } }]]></programlisting> <para>Since the Managed connection object created the "ConnectionFactory" class it has access to all the configuration parameters, if "getConnection" method needs to do pass any of credentials to the underlying EIS system. The Connection Factory class can also get reference to the calling user's <code>javax.security.auth.Subject</code> during "getConnection" method by calling - - <programlisting><![CDATA[Subject subject = ConnectionContext.getSubject();]]></programlisting> + </para> + <programlisting language="Java" role="JAVA"><![CDATA[Subject subject = ConnectionContext.getSubject();]]></programlisting> + <para> This "Subject" object can give access to logged-in user's credentials and roles that are defined. Note that this may be null. </para> <para>Note that you can define "security-domain" for this resource adapter, that is separate from @@ -98,29 +96,34 @@ of the Connection object in the Translator. If your connection is stateful, then override "isAlive()" and "cleanup()" methods and provide proper implementations. These are called to check if a Connection is stale or need to flush them from the connection pool etc. by the Container.</para> - <programlisting><![CDATA[public class MyConnection extends BasicConnection { - - public void doSomeOperation(command){ - // do some operation with EIS system.. - // This is method you use in the Translator, you should know - // what need to be done here for your source.. - } + <programlisting language="Java" role="JAVA"><![CDATA[public class MyConnection extends BasicConnection +{ + public void doSomeOperation(command) + { + // do some operation with EIS system.. + // This is method you use in the Translator, you should know + // what need to be done here for your source.. + } - @Override - public boolean isAlive() { - return true; - } - @Override - public void cleanUp() { + @Override + public boolean isAlive() + { + return true; + } + + @Override + public void cleanUp() + { - } + } }]]></programlisting> </section> <section> <title>XA Transactions</title> - <para>If you EIS source can participate in XA transactions, then on your <link linkend="connection">Connection</link> object, - override the "getXAResource()" method and provide the "XAResource" object for the EIS system. + <para>If your EIS source can participate in XA transactions, then on your Connection object, + override the "getXAResource()" method and provide the "XAResource" object for the EIS system. + Refer to <xref linkend="connection"/>. Also, You need to extend the "BasicResourceAdapter" class and provide implementation for method "public XAResource[] getXAResources(ActivationSpec[] specs)" to participate in crash recovery. </para> @@ -131,17 +134,26 @@ <section> <title>Define the configuration properties in a "ra.xml" file</title> - <para>Define a "ra.xml" file (sample shown in the <link linkend="appendix_a">appendix-a</link>) in "META-INF" directory of your RAR file. - For every configuration property defined inside the <link linkend="managed_connection_factory">ManagedConnectionFactory</link> + <para> + Define a "ra.xml" file in "META-INF" directory of your RAR file. + An example file is provided in <xref linkend="appendix_a"/>. + </para> + <para> + For every configuration property defined inside the ManagedConnectionFactory class, define the following XML configuration fragment inside the "ra.xml" file. These properties are used by user to configure instance of this Connector inside a Container. Also, during the startup the Container reads these properties from this file and knows how to inject - provided values in the "-ds.xml" file into a instance of "ManagedConnectionFactory" to create the Connection.</para> - <programlisting><![CDATA[<config-property> - <description>{$display:"${display-name}",$description:"${description}", $allowed="${allowed}", $required="${true|false}", $defaultValue="${default-value}"}</description> - <config-property-name>${property-name}</config-property-name> - <config-property-type>${property-type}</config-property-type> - <config-property-value>${optioal-property-value}</config-property-value> + provided values in the "-ds.xml" file into a instance of "ManagedConnectionFactory" to create the Connection. + Refer to <xref linkend="managed_connection_factory"/>. + </para> + <programlisting role="XML" language="XML"><![CDATA[<config-property> + <description> + {$display:"${display-name}",$description:"${description}", $allowed="${allowed}", + $required="${true|false}", $defaultValue="${default-value}"} + </description> + <config-property-name>${property-name}</config-property-name> + <config-property-type>${property-type}</config-property-type> + <config-property-value>${optioal-property-value}</config-property-value> </config-property>]]></programlisting> <para>The format and contents of "&lt;description&gt;" element may be used as extended metadata for tooling. The special format must begin and end with curly braces e.g. {...}. This use of the special format and all properties is optional. Property names begin with '$' and are separated from the value with ':'. Double quotes identifies a single value. A pair of square brackets, e.g. [...], containing comma separated double quoted entries denotes a list value. @@ -193,37 +205,39 @@ <para>Maven: If you are using maven, use &lt;packaging&gt; element value as "rar". Teiid uses maven, you can look at any of the "connector" projects for sample "pom.xml" file. Here is sample pom.xml file.</para> - <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> -<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> - <modelVersion>4.0.0</modelVersion> - <artifactId>connector-{name}</artifactId> - <groupId>org.company.project</groupId> - <name>Name Connector</name> - <packaging>rar</packaging> - <description>This connector is a sample</description> + <programlisting role="XML" language="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> + <modelVersion>4.0.0</modelVersion> + <artifactId>connector-{name}</artifactId> + <groupId>org.company.project</groupId> + <name>Name Connector</name> + <packaging>rar</packaging> + <description>This connector is a sample</description> - <dependencies> - <dependency> - <groupId>org.jboss.teiid</groupId> - <artifactId>teiid-api</artifactId> - <scope>provided</scope> - </dependency> - <dependency> - <groupId>org.jboss.teiid</groupId> - <artifactId>teiid-common-core</artifactId> - <scope>provided</scope> - </dependency> - <dependency> - <groupId>javax.resource</groupId> - <artifactId>connector-api</artifactId> - <scope>provided</scope> - </dependency> - </dependencies> + <dependencies> + <dependency> + <groupId>org.jboss.teiid</groupId> + <artifactId>teiid-api</artifactId> + <scope>provided</scope> + </dependency> + <dependency> + <groupId>org.jboss.teiid</groupId> + <artifactId>teiid-common-core</artifactId> + <scope>provided</scope> + </dependency> + <dependency> + <groupId>javax.resource</groupId> + <artifactId>connector-api</artifactId> + <scope>provided</scope> + </dependency> + </dependencies> + </project>]]></programlisting> </listitem> </itemizedlist> <para>Make sure that the RAR file, under its "META-INF" directory has the "ra.xml" file. If you are using maven - see <ulink url="http://maven.apache.org/plugins/maven-rar-plugin/"><... the root of the RAR file, + refer to <ulink url="http://maven.apache.org/plugins/maven-rar-plugin/"/>;. In the root of the RAR file, you can embed the JAR file containing your connector code and any dependent library JAR files. </para> </section> @@ -239,25 +253,29 @@ <itemizedlist> <listitem> - <para>Create "${name}-ds.xml" file, and copy it into "deploy" directory of JBoss AS. - <programlisting><![CDATA[<!DOCTYPE connection-factories PUBLIC - "-//JBoss//DTD JBOSS JCA Config 1.5//EN" - "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd"> + <para> + Create "${name}-ds.xml" file, and copy it into "deploy" directory of JBoss AS. + </para> + <programlisting language="XML" role="XML"><![CDATA[<!DOCTYPE connection-factories PUBLIC + "-//JBoss//DTD JBOSS JCA Config 1.5//EN" "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd"> <connection-factories> - <no-tx-connection-factory> - <jndi-name>${jndi-name}</jndi-name> - <rar-name>${name}.rar</rar-name> - <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition> - - <!-- define all the properties defined in the "ra.xml" that required or needs to be modified from defaults --> - <!-- each property is defined in single element --> - <config-property name="prop-name" type="java.lang.String">prop-value</config-property> - - </no-tx-connection-factory> + <no-tx-connection-factory> + <jndi-name>${jndi-name}</jndi-name> + <rar-name>${name}.rar</rar-name> + <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition> + + <!-- + define all the properties defined in the "ra.xml" that required or needs to be + modified from defaults each property is defined in single element + --> + <config-property name="prop-name" type="java.lang.String">prop-value</config-property> + +</no-tx-connection-factory> </connection-factories>]]></programlisting> - There are lot more properties that you can define for pooling, transactions, security etc in this file. - Check JBoss AS documentation for all the avaialble properties. + <para> + There are lot more properties that you can define for pooling, transactions, security etc in this file. + Check JBoss AS documentation for all the avaialble properties. </para> </listitem> <listitem> Modified: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/extending-jdbc.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -40,7 +40,7 @@ <section> <title>Capabilities Extension</title> <para>This extension must override the methods that begin with "supports" that describe translator capabilities. - For all the available translator capabilities please see <link linkend="translator_capabilities">this</link>.</para> + Refer to <xref linkend="translator_capabilities"/> for all the available translator capabilities.</para> <para>The most common example is adding support for a scalar function – this requires both declaring that the translator has the capability @@ -59,15 +59,20 @@ <para>Change basic SQL syntax options. See the useXXX methods, e.g. useSelectLimit returns true for SQLServer to indicate that limits are applied in the SELECT clause.</para> </listitem> <listitem> - <para>Register one or more <link linkend="function_modifiers">FunctionModifiers</link> that define how a scalar function should be modified or transformed.</para> + <para>Register one or more FunctionModifiers that define how a scalar function should be modified or transformed.</para> </listitem> <listitem> - <para>Modify a LanguageObject. - see the translate, translateXXX, and <link linkend="function_modifiers">FunctionModifiers</link>.translate methods. Modify the passed in object and return null to indicate that the standard syntax output should be used.</para> + <para>Modify a LanguageObject. - see the translate, translateXXX, and FunctionModifiers.translate methods. Modify the passed in object and return null to indicate that the standard syntax output should be used.</para> </listitem> <listitem> - <para>Change the way SQL strings are formed for a LanguageObject. - - see the translate, translateXXX, and <link linkend="function_modifiers">FunctionModifiers</link>.translate methods. Return a list of parts, which can contain strings and LanguageObjects, that will be appended in order to the SQL string. If the in coming LanguageObject appears in the returned list it will not be translated again.</para> + <para>Change the way SQL strings are formed for a LanguageObject. - - see the translate, translateXXX, and FunctionModifiers.translate methods. Return a list of parts, which can contain strings and LanguageObjects, that will be appended in order to the SQL string. If the in coming LanguageObject appears in the returned list it will not be translated again.</para> </listitem> </itemizedlist> + + <para> + Refer to <xref linkend="function_modifiers"/>. + </para> + </section> <section> @@ -86,7 +91,7 @@ <section> <title>Adding Function Support</title> - <para>See <link linkend="udfs">User Defined Functions</link> for adding new functions to Teiid. This example will show you how to declare support for the function + <para>Refer to <xref linkend="udfs"/> for adding new functions to Teiid. This example will show you how to declare support for the function and modify how the function is passed to the data source.</para> <para>Following is a summary of all coding steps in supporting a new scalar function:</para> <orderedlist> @@ -99,25 +104,27 @@ </orderedlist> <para>There is a capabilities method getSupportedFunctions() that declares all supported scalar functions.</para> <informalexample> - <para>An example of an extended capabilities class to add support for the “abs” absolute value function:</para> - <programlisting><![CDATA[package my.connector; - + <para>An example of an extended capabilities class to add support for the "abs" absolute value function:</para> + <programlisting language="Java" role="JAVA"><![CDATA[package my.connector; + import java.util.ArrayList; import java.util.List; -public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory { - @Override - public List getSupportedFunctions() { - List supportedFunctions = new ArrayList(); - supportedFunctions.addAll(super.getSupportedFunctions()); - supportedFunctions.add("ABS"); - return supportedFunctions; - } +public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory +{ + @Override + public List getSupportedFunctions() + { + List supportedFunctions = new ArrayList(); + supportedFunctions.addAll(super.getSupportedFunctions()); + supportedFunctions.add("ABS"); + return supportedFunctions; + } }]]></programlisting></informalexample> <para>In general, it is a good idea to call super.getSupportedFunctions() to ensure that you retain any function support provided by the translator you are extending.</para> <para>This may be all that is needed to support a Teiid function if the JDBC data source supports the - same syntax as Teiid. The built-in SQL translation will translate most functions as: “function(arg1, arg2, …)”.</para> + same syntax as Teiid. The built-in SQL translation will translate most functions as: "function(arg1, arg2, …)".</para> <section id="function_modifiers"> <title>Using FunctionModifiers</title> <para>In some cases you may need to translate the function differently or even insert @@ -129,18 +136,19 @@ <informalexample> <para>An example of overriding the translate method to change the MOD(a, b) function into an infix operator for Sybase (a % b). The translate method returns a list of strings and language objects that will be assembled by the translator into a final string. The strings will be used as is and the language objects will be further processed by the translator.</para> - <programlisting><![CDATA[public class ModFunctionModifier implements FunctionModifier { - - public List translate(Function function) { - List parts = new ArrayList(); - parts.add("("); - Expression[] args = function.getParameters(); - parts.add(args[0]); - parts.add(" % "); - parts.add(args[1]); - parts.add(")"); - return parts; - } + <programlisting language="Java" role="JAVA"><![CDATA[public class ModFunctionModifier implements FunctionModifier +{ + public List translate(Function function) + { + List parts = new ArrayList(); + parts.add("("); + Expression[] args = function.getParameters(); + parts.add(args[0]); + parts.add(" % "); + parts.add(args[1]); + parts.add(")"); + return parts; + } }]]></programlisting> </informalexample> @@ -150,8 +158,8 @@ <table frame='all'> <title>Common Modifiers</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth=".4*"/> - <colspec colname='c2' colwidth="1*"/> + <colspec colname='c1' colwidth="2*"/> + <colspec colname='c2' colwidth="5*"/> <thead> <row> <entry><para>Modifier</para></entry> @@ -161,7 +169,7 @@ <tbody> <row> <entry><para>AliasModifier</para></entry> - <entry><para>Handles simply renaming a function (“ucase” to “upper” for example)</para></entry> + <entry><para>Handles simply renaming a function ("ucase" to "upper" for example)</para></entry> </row> <row> <entry><para>EscapeSyntaxModifier</para></entry> @@ -172,18 +180,20 @@ </table> <para>To register the function modifiers for your supported functions, you must call the <code>ExecutionFactory.registerFunctionModifier(String name, FunctionModifier modifier)</code> method. - <programlisting><![CDATA[public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory - - @Override - public void start() { - super.start(); - - // register functions. - registerFunctionModifier("abs", new MyAbsModifier()); - registerFunctionModifier("concat", new AliasModifier(“concat2”)); - } -}]]></programlisting></para> - <para>Support for the two functions being registered (“abs” and “concat”) must be declared + </para> + <programlisting language="Java" role="JAVA"><![CDATA[public class ExtendedJDBCExecutionFactory extends JDBCExecutionFactory +{ + @Override + public void start() + { + super.start(); + + // register functions. + registerFunctionModifier("abs", new MyAbsModifier()); + registerFunctionModifier("concat", new AliasModifier("concat2")); + } +}]]></programlisting> + <para>Support for the two functions being registered ("abs" and "concat") must be declared in the capabilities as well. Functions that do not have modifiers registered will be translated as usual. </para> </section> @@ -192,10 +202,13 @@ <section> <title>Installing Extensions</title> <para>Once you have developed an extension to the JDBC translator, you must install it into the Teiid Server. - The process of <link linkend="translator_package">packaging</link> or <link linkend="translator_deploy">deploying</link> the + The process of packaging or deploying the extended JDBC translators is exactly as any other other translator. Since the RDMS is accessible already through its JDBC driver, there is no need to develop a resource adapter for this source as JBoss AS provides a wrapper JCA connector (DataSource) for any JDBC driver. </para> + <para> + Refer to <xref linkend="translator_package"/> and <xref linkend="translator_deploy"/> for more details. + </para> </section> </chapter> Modified: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -8,7 +8,7 @@ <section> <title>Introduction to the Teiid Connector Architecture</title> - <itemizedlist> + <orderedlist> <para>Integrating data from a Enterprise Information System (EIS) into Teiid, is separated into two parts.</para> <listitem> <para>A Translator, which is required.</para> @@ -16,20 +16,20 @@ <listitem> <para>An optional Resource Adapter, which will typically be a JCA Resource Adapter (also called a JEE Connector) </para> </listitem> - </itemizedlist> + </orderedlist> <para>A Translator is used to:</para> - <itemizedlist> + <orderedlist> <listitem> - <para>Translate a Teiid-specific command into a native command.</para> + <para>Translate a Teiid-specific command into a native command,</para> </listitem> <listitem> - <para>Execute the command.</para> + <para>Execute the command,</para> </listitem> <listitem> <para>Return batches of results translated to expected Teiid types.</para> </listitem> - </itemizedlist> + </orderedlist> <para>A Resource Adapter:</para> <itemizedlist> @@ -37,9 +37,11 @@ <para>Handles all communications with individual enterprise information system (EIS), which can include databases, data feeds, flat files, etc.</para> </listitem> <listitem> - <para>Can be a <ulink url="http://java.sun.com/j2ee/connector/">JCA Connector</ulink> or any other custom connection provider. + <para>Can be a JCA Connector or any other custom connection provider. The reason Teiid recommends and uses JCA is this specification defines how one can write, package, and configure access to EIS system in consistent manner. There are also various commercial/open source software vendors already providing JCA Connectors to access a variety of back-end systems.</para> + <para> + Refer to <ulink url="http://java.sun.com/j2ee/connector/"/>.</para> </listitem> <listitem> <para>Abstracts Translators from many common concerns, such as connection information, resource pooling, or authentication.</para> @@ -55,47 +57,76 @@ you can use one of these enterprise information systems, you do not need to develop a custom one. </para> <para>Teiid offers the following translators:</para> - <itemizedlist> - <listitem> - <para> - <emphasis>JDBC:</emphasis> - Works with many relational databases. The JDBC translator is validated against the following database - systems: Oracle, Microsoft SQL Server, IBM DB2, MySQL, Postgres, Derby, Sybase, H2, and HSQL. In addition, the JDBC Translator can - often be used with other 3rd-party drivers and provides a wide range of extensibility options to - specialize behavior against those drivers. - </para> - </listitem> - <listitem> - <para> - <emphasis>File:</emphasis> - Provides a procedural way to access the file system to handle text files. - </para> - </listitem> - <listitem> - <para> - <emphasis>WS:</emphasis> Provides procedural access to XML content via Web Services. - </para> - </listitem> - <listitem> - <para> - <emphasis>LDAP:</emphasis> Accesses to LDAP directory services. - </para> - </listitem> - <listitem> - <para> - <emphasis>Salesforce:</emphasis> Works with Salesforce interfaces. - </para> - </listitem> - </itemizedlist> + + <variablelist> + <varlistentry> + <term>JDBC Translator</term> + <listitem> + <para> + Works with many relational databases. The JDBC translator is validated + against the following database systems: Oracle, Microsoft SQL Server, + IBM DB2, MySQL, Postgres, Derby, Sybase, H2, and HSQL. In addition, the + JDBC Translator can often be used with other 3rd-party drivers and provides + a wide range of extensibility options to specialize behavior against those + drivers. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>File Translator</term> + <listitem> + <para> + Provides a procedural way to access the file system to handle text files. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WS Translator</term> + <listitem> + <para> + Provides procedural access to XML content using Web Services. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>LDAP Translator</term> + <listitem> + <para> + Accesses to LDAP directory services. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Salesforce Translator</term> + <listitem> + <para> + Works with Salesforce interfaces. + </para> + </listitem> + </varlistentry> + </variablelist> + <section> <title>Custom Translators</title> - <orderedlist numeration="arabic"> - <para>High-level Translator development procedure:</para> + + <para> + Below are the high-level steps for creating custom Translators. This guide covers + how to do each of these steps in detail. It also provides additional information for + advanced topics, such as streaming large objects. + </para> + + <para> + For sample Translator code, refer to the Teiid source code at + <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/"/>;. + </para> + + <orderedlist> <listitem> - <para><link linkend="custom_ra_intro"></link>Create a new or reuse an existing Resource Adapater for the EIS system, to be used with this Translator</para> + <para>Create a new or reuse an existing Resource Adapater for the EIS system, to be used with this Translator.</para> + <para>Refer to <xref linkend="custom_ra_intro"/>.</para> </listitem> <listitem> - <para>Implement the required classes defined by the <link linkend="translator_api">Translator API</link>.</para> + <para>Implement the required classes defined by the Translator API.</para> <itemizedlist> <listitem> <para>Create an ExecutionFactory – Extend the <code>org.teiid.translator.ExecutionFactory</code> class</para> @@ -104,29 +135,27 @@ <para>Create relevant Executions (and sub-interfaces) – specifies how to execute each type of command</para> </listitem> </itemizedlist> + <para>Refer to <xref linkend="translator_api"/>.</para> </listitem> <listitem> - <para>Define the <link linkend="translator_package">template</link> for exposing configuration properties.</para> + <para>Define the template for exposing configuration properties. + Refer to <xref linkend="translator_package"/>.</para> </listitem> <listitem> - <para><link linkend="translator_deploy">Deploy</link> your Translator.</para> - <itemizedlist> - <listitem> - <para>Deploy a Virtual Database (VDB) utilizing your Translator.</para> - </listitem> - </itemizedlist> + <para>Deploy your Translator. + Refer to <xref linkend="translator_deploy"/>.</para> </listitem> + <listitem> + <para>Deploy a Virtual Database (VDB) that uses your Translator.</para> + </listitem> <listitem> <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 streaming large objects. For sample - Translator code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">... source code</ulink> - </para> + + + </section> </section> - </section> <section> <title>Do You Need a New Resource Adapter?</title> <para>As mentioned above, for every Translator that needs to gather data from external source systems, it requires a resource adapter. @@ -160,7 +189,8 @@ <orderedlist numeration="arabic"> <para>High-level Resource Adapter development procedure:</para> <listitem> - <para>Understand the <ulink url="http://java.sun.com/j2ee/connector/">JEE Connector</ulink> specification to have basic idea about what JCA connectors are how they are developed and packaged.</para> + <para>Understand the JEE Connector specification to have basic idea about what JCA connectors are how they are developed and packaged.</para> + <para>Refer to <ulink url="http://java.sun.com/j2ee/connector/"/>.</para> </listitem> <listitem> <para>Gather all necessary information about your Enterprise Information System (EIS). You will need @@ -198,16 +228,16 @@ </itemizedlist> </listitem> <listitem> - <para><link linkend="ra_package">Package</link> your resource adapter.</para> + <para>Package your resource adapter. Refer to <xref linkend="ra_package"/>.</para> </listitem> <listitem> - <para><link linkend="ra_package">Deploy</link> your resource adapter.</para> + <para>Deploy your resource adapter. Refer to <xref linkend="ra_package"/>.</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 transactions. For a sample - resource adapter code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">... Source code</ulink> + advanced topics, such as transactions. For sample + resource adapter code refer to the Teiid Source code at <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/"/>;. </para> </section> </section> @@ -217,13 +247,13 @@ <para>Teiid is highly extensible in other ways:</para> <itemizedlist> <listitem> - <para>You may add <link linkend="udfs">User Defined Functions</link>.</para> + <para>You may add User Defined Functions. Refer to <xref linkend="udfs"/>.</para> </listitem> <listitem> - <para>You may adapt <link linkend="logging">logging</link> to your needs, which is especially useful for custom audit or command logging.</para> + <para>You may adapt logging to your needs, which is especially useful for custom audit or command logging. Refer to <xref linkend="logging"/>.</para> </listitem> <listitem> - <para>You may change the <link linkend="custom_security">security</link> subsystem for custom authentication and authorization.</para> + <para>You may change the subsystem for custom authentication and authorization. Refer to <xref linkend="custom_login_modules"/>.</para> </listitem> </itemizedlist> </section> Modified: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/logging.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/logging.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/logging.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -8,23 +8,23 @@ <section id="custom_logging"> <title>Customized Logging</title> <para> - The Teiid system provides a wealth of information via logging. To - control logging level, contexts, and log locations, you should be - familiar with - <ulink url="http://logging.apache.org/log4j/">log4j</ulink> - and the container's jboss-log4j.xml configuration file. - Teiid also provides a &lt;profile&gt;/conf/jboss-teiid-log4j.xml containing much of information from chapter. - Check out Admin Guide for more details about different Teiid contexts available. + The Teiid system provides a wealth of information using logging. To control logging level, + contexts, and log locations, you should be familiar with log4j and the container's + <filename>jboss-log4j.xml</filename> configuration file. Teiid also provides a + <filename><replaceable>PROFILE</replaceable>/conf/jboss-teiid-log4j.xml</filename> containing + much of information from this chapter. Refer to the Administrator Guide for more details about + different Teiid contexts available. Refer to <ulink url="http://logging.apache.org/log4j/"/> + for more information about log4j. </para> <para> If the default log4j logging mechanisms are not sufficient for your - logging needs you may need a different appender - see - <ulink url="http://logging.apache.org/log4j/1.2/apidocs/index.html">... log4j javadocs</ulink>. + logging needs you may need a different appender, refer to the log4j javadocs at + <ulink url="http://logging.apache.org/log4j/1.2/apidocs/index.html"/>;. Note that log4j already provides quite a few appenders including JMS, RDBMS, and SMTP. </para> - <para>If you want a custom appender, follow the Log4J directions to write a custom appender. See instructions - <ulink url="http://logging.apache.org/log4net/release/faq.html">her...;. If you develop a custom + <para>If you want a custom appender, follow the Log4J directions to write a custom appender. Refer to + the instructions at <ulink url="http://logging.apache.org/log4net/release/faq.html"/>;. If you develop a custom logging solution, the implementation jar should be placed in the "lib" directory of the JBoss AS server profile Teiid is installed in. </para> Modified: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/security.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/security.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/security.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -8,37 +8,88 @@ <para> LoginModules are an essential part of the JAAS security framework and provide Teiid customizable user authentication and the - ability to reuse existing LoginModules defined for JBossAS. See - <ulink - url="http://docs.jboss.org/jbossas/admindevel326/html/ch8.chapter.ht... Security</ulink> - for general information on configuring security in JBossAS.</para> + ability to reuse existing LoginModules defined for JBossAS. Refer to + the JBoss Application Server security documentation for information about + configuring security in JBoss Application Server, + <ulink url="http://docs.jboss.org/jbossas/admindevel326/html/ch8.chapter.ht...;. + </para> <section> <title>Built-in LoginModules</title> - <para>JBossAS provides several LoginModules for common authentication needs, such as authenticating from text files or LDAP. - The below are are some of the available in JBoss AS </para> + <para> + JBoss Application Server provides several LoginModules for common + authentication needs, such as authenticating from text files or LDAP. + </para> - <para>See for all the available <ulink url="http://community.jboss.org/docs/DOC-11287"> login modules.</ulink></para> + <para> + Below are are some of those available in JBoss Application Server: + </para> + + <variablelist> - <para>See <ulink url="http://community.jboss.org/docs/DOC-12510">UserRoles LoginModule configuration</ulink> - for utilizing simple file based authentication.</para> - <para>See <ulink url="http://community.jboss.org/docs/DOC-11253">LDAP LoginModule configuration</ulink> for - utilizing LDAP based authentication. </para> - <para>See <ulink url="http://community.jboss.org/docs/DOC-9511">Database LoginModule configuration</ulink> for - utilizing Database based authentication. </para> + <varlistentry> + <term>UserRoles LoginModule</term> + <listitem> + <para> + Login module that uses simple file based authentication. + </para> + <para> + Refer to <ulink url="http://community.jboss.org/docs/DOC-12510"/>;. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>LDAP LoginModule</term> + <listitem> + <para> + Login module that uses LDAP based authentication. + </para> + <para> + Refer to <ulink url="http://community.jboss.org/docs/DOC-11253"/>;. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Database LoginModule</term> + <listitem> + <para> + Login module that uses Database-based authentication. + </para> + <para> + Refer to <ulink url="http://community.jboss.org/docs/DOC-9511"/>;. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Cert LoginModule</term> + <listitem> + <para> + Login module that uses X509 certificate based authentication. + </para> + <para> + See <ulink url="http://community.jboss.org/docs/DOC-9160"/>;. + </para> + </listitem> + </varlistentry> + + </variablelist> - <para>See <ulink url="http://community.jboss.org/docs/DOC-9160">Cert LoginModule configuration</ulink> for - utilizing X509 certificate based authentication. </para> - </section> + <para> + For all the available login modules refer to <ulink url="http://community.jboss.org/docs/DOC-11287"/>;. + </para> + + </section> + <section> <title>Custom LoginModules</title> <para> - If your authentication needs go beyond the provided LoginModules, please consult the - <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMD... development guide</ulink>. + If your authentication needs go beyond the provided LoginModules, please refer + to the JAAS development guide at + <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMD...;. There are also numerous guides available. </para> - <para>If you are extending one of the built-in LoginModules, please see - <ulink url="http://community.jboss.org/docs/DOC-9466">this</ulin... + <para>If you are extending one of the built-in LoginModules, refer to + <ulink url="http://community.jboss.org/docs/DOC-9466"/>.</para> </section> </chapter> \ No newline at end of file Modified: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -32,22 +32,26 @@ <para>Every software program requires some external configuration, that defines ways user can alter the behavior of a program. If this translator needs configurable properties define a variable for every property as an attribute in the extended "ExecutionFactory" class. Then define a "get" and "set" methods for each of them. Also, annotate each "get" method with - <code>@TranslatorProperty</code> annotation and provide the metadata about the property. For example, if you need a - property called "foo", - <programlisting><![CDATA[private String foo = "balh"; - + <code>@TranslatorProperty</code> annotation and provide the metadata about the property. + </para> + <para> + For example, if you need a property called "foo", by providing the annotation on + these properties, the Teiid tooling will automatically interrogate and provide + graphical way to configure your Translator. + </para> + <programlisting language="Java" role="JAVA"><![CDATA[private String foo = "blah"; @TranslatorProperty(display="Foo property", description="description about Foo") -public String getFoo() { - return foo; +public String getFoo() +{ + return foo; } -public void setFoo(String value) { - return this.foo = value; +public void setFoo(String value) +{ + return this.foo = value; }]]> </programlisting> - - by providing the annotation on these properties, the Teiid tooling will automatically interrogate and - provide graphical way to configure your - Translator. Only java primitive (int), primitive object wrapper (java.lang.Integer), or Enum types are supported as Translator properties. + <para> + Only java primitive (int), primitive object wrapper (java.lang.Integer), or Enum types are supported as Translator properties. The default value will be derived from calling the getter, if available, on a newly constructed instance. All properties <emphasis>should</emphasis> have a default value. If there is no applicable default, then the property should be marked in the annotation as required. Initialization will fail if a required property value is not provided. @@ -84,7 +88,7 @@ <title>TranslatorCapabilities</title> <para>These are various methods that typically begin with method signature "supports" on the "ExecutionFactory" class. These methods need to be overridden to describe the execution - capabilities of the Translator. See <link linkend="translator_capabilities">Translator Capabilities</link> for more on these methods.</para> + capabilities of the Translator. Refer to <xref linkend="translator_capabilities"/> for more on these methods.</para> </section> <section> @@ -161,16 +165,19 @@ </para> </section> </section> + <section> - <title>Executing Commands</title> - <section> + <title>Executing Commands</title> + <section> <title>Execution Modes</title> - <para> - The Teiid query engine uses the "ExecutionFactory" class to obtain the "Execution" interface for the command it is - executing. The actual queries themselves are sent to translators in the form of a set of objects, which are further - described in <link linkend="command_language">Command Language</link>. - translators are allowed to support any subset of the available execution modes. - </para> + <para> + The Teiid query engine uses the "ExecutionFactory" class to obtain the "Execution" + interface for the command it is executing. The actual queries themselves are sent + to translators in the form of a set of objects, which are further described in + Command Language. Refer to <xref linkend="command_language"/>. Translators 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'> @@ -311,9 +318,8 @@ package. These objects can be combined to represent any possible command that Teiid may send to the Translator. However, it is possible to notify Teiid that your Translator can only accept certain kinds of - constructs via the capabilities defined on the "ExecutionFactory" class. See the section on using - <link linkend="translator_capabilities">Translator Capabilities</link> - for more information. + constructs via the capabilities defined on the "ExecutionFactory" class. Refer to + <xref linkend="translator_capabilities"/> for more information. </para> <para>The language objects all extend from the <code>LanguageObject</code> interface. Language objects should be thought of as a tree where each node is a @@ -322,7 +328,7 @@ <para>All commands sent to your Translator are in the form of these language trees, where the root of the tree is a subclass of <code>Command</code>. Command has several sub-interfaces, namely: - + </para> <itemizedlist> <listitem><para><code>QueryExpression</code></para></listitem> <listitem><para><code>Insert</code></para></listitem> @@ -331,11 +337,13 @@ <listitem><para><code>BatchedUpdates</code></para></listitem> <listitem><para><code>Call</code></para></listitem> </itemizedlist> - - Important components of these commands are expressions, criteria, and joins, which are examined - in closer detail below. Also see the <ulink url="&javaDocUrl;">Teiid JavaDocs</ulink> - for more on the classes and interfaces described here. - </para> + + <para> + Important components of these commands are expressions, criteria, and joins, + which are examined in closer detail below. For more on the classes and interfaces + described here, refer to the Teiid JavaDocs <ulink url="&javaDocUrl;"/>. + </para> + <section> <title>Expressions</title> <para>An expression represents a single value in context, although in @@ -430,9 +438,8 @@ <code>Join</code> s with a single root. This latter form is the ANSI perfered style. If you wish all pushdown queries containing joins to be in ANSI style have the - capability "useAnsiJoin" return true. See - <link linkend="command_form_capabilities">Command Form Capabilities</link> - for more information. + capability "useAnsiJoin" return true. Refer to + <xref linkend="command_form_capabilities"/> for more information. </para> </section> <section> @@ -542,7 +549,7 @@ <section> <title>Runtime Metadata</title> - <para>Teiid uses a library of metadata, known as "runtime metadata” for + <para>Teiid uses a library of metadata, known as "runtime metadata" for each virtual database that is deployed in Teiid. The runtime metadata is a subset of metadata as defined by models in the Teiid models that compose the virtual database.  While builing your VDB in the Designer, you can define what @@ -578,14 +585,12 @@ <title>Obtaining Metadata Properties</title> <para>The process of getting a Table's properties is sometimes needed for translator development.  For example to get the "NameInSource" property or all extension properties:</para> - <programlisting><![CDATA[ -//getting the Table metadata from an Table is straight-forward + <programlisting language="Java" role="JAVA"><![CDATA[//getting the Table metadata from an Table is straight-forward Table table = runtimeMetadata.getTable("table-name"); String contextName = table.getNameInSource(); //The props will contain extension properties -Map<String, String> props = table.getProperties(); - ]]></programlisting> +Map<String, String> props = table.getProperties();]]></programlisting> </example> </section> @@ -661,8 +666,7 @@ not processing order.</para> <para>Write code to execute your visitor using the utility methods on DelegatingHierarchyVisitor:</para> - <programlisting><![CDATA[ -// Get object tree + <programlisting language="Java" role="JAVA"><![CDATA[// Get object tree LanguageObject objectTree = … // Create your visitor initialize as necessary @@ -672,8 +676,7 @@ DelegatingHierarchyVisitor.preOrderVisit(visitor, objectTree); // Retrieve state collected while visiting -int count = visitor.getCount(); - ]]></programlisting> +int count = visitor.getCount();]]></programlisting> </section> </section> <section id="translator_capabilities"> @@ -698,9 +701,9 @@ <table frame='all'> <title>Available Capabilities</title> <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1.5*" /> + <colspec colname='c1' colwidth="1*" /> <colspec colname='c2' colwidth="1*" /> - <colspec colname='c3' colwidth="2*" /> + <colspec colname='c3' colwidth="3*" /> <thead> <row> <entry> @@ -824,7 +827,7 @@ <para/> </entry> <entry> - <para>Translator can support comparison criteria with the operator "=”.</para> + <para>Translator can support comparison criteria with the operator "=".</para> </entry> </row> <row> @@ -835,7 +838,7 @@ <para/> </entry> <entry> - <para>Translator can support comparison criteria with the operator "&gt;” or "&lt;".</para> + <para>Translator can support comparison criteria with the operator "&gt;" or "&lt;".</para> </entry> </row> <row> @@ -1140,7 +1143,7 @@ <para /> </entry> <entry> - <para>Translator can support "searched” CASE expressions anywhere that expressions are + <para>Translator can support "searched" CASE expressions anywhere that expressions are accepted.</para> </entry> </row> @@ -1287,8 +1290,8 @@ <para>The method <code>ExecutionFactory.getSupportedFunctions()</code> can be used to specify which scalar functions the Translator supports.  The set of possible functions is based on the set of functions supported - by Teiid.  This set can be found in the <ulink url="&docUrl;">Reference</ulink> - documentation.  If the Translator states that it supports a function, + by Teiid. This set can be found in the Reference documentation at + <ulink url="&docUrl;"/>. If the Translator states that it supports a function, it must support all type combinations and overloaded forms of that function.</para> <para>There are also five standard operators that can also be specified in the @@ -1339,9 +1342,9 @@ <section> <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 + clob, and xml. A blob is a "binary large object", a clob is a + "character large object", and "xml" is a "xml + document". Columns modeled as a blob, clob, or xml are treated similarly by the translator framework to support memory-safe streaming.  </para> </section> <section> @@ -1389,7 +1392,7 @@ <para>When the "keepAlive" alive flag is set, then the execution object is only closed when user's Statement is closed.</para> - <programlisting><![CDATA[executionContext.keepExecutionAlive(true);]]></programlisting> + <programlisting language="Java" role="JAVA"><![CDATA[executionContext.keepExecutionAlive(true);]]></programlisting> </section> @@ -1405,17 +1408,21 @@ <section id="translator_package"> <title>Packaging</title> - <para>Once the "ExecutionFactory" class is implemented, package it in a JAR file. The only - additional requirement is provide a file called "jboss-beans.xml" in the "META-INF" directory of the JAR file, with - following contents. - <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + <para> + Once the "ExecutionFactory" class is implemented, package it in a JAR file. The only + additional requirement is provide a file called "jboss-beans.xml" in the "META-INF" + directory of the JAR file, with following contents. Replace ${name} with name of your + translator, and replace ${execution-factory-class} with your overridden ExecutionFactory + class name. This will register the Translator for use with tooling and Admin API. + </para> + <programlisting role="XML" language="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <deployment xmlns="urn:jboss:bean-deployer:2.0"> - + <bean name="translator-${name}-template" class="org.teiid.templates.TranslatorDeploymentTemplate"> <property name="info"><inject bean="translator-${name}"/></property> <property name="managedObjectFactory"><inject bean="ManagedObjectFactory"/></property> </bean> - + <bean name="translator-${name}" class="org.teiid.templates.TranslatorTemplateInfo"> <constructor factoryMethod="createTemplateInfo"> <factory bean="TranslatorDeploymentTemplateInfoFactory"/> @@ -1425,11 +1432,10 @@ <parameter class="java.lang.String">${name}</parameter> </constructor> </bean> - + </deployment>]]></programlisting> - replace ${name} with name of your translator, and replace ${execution-factory-class} with your - overridden ExecutionFactory class name. This will register the Translator for use with tooling and Admin API.</para> + </section> <section id="translator_deploy"> Modified: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/content/udf.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -95,7 +95,7 @@ functions score and contains: </para> <informalexample> - <programlisting>SELECT score(1), ID, FREEDATA FROM Docs WHERE contains(freedata, 'nick', 1) &gt; 0</programlisting> + <programlisting language="SQL">SELECT score(1), ID, FREEDATA FROM Docs WHERE contains(freedata, 'nick', 1) &gt; 0</programlisting> </informalexample> <para> The @@ -136,7 +136,9 @@ <listitem> <para> Create a new translator jar containing your custom - ExecutionFactory. See <link linkend="translator_package">packaging</link> and <link linkend="translator_deploy">deployment</link> instructions for using the jar.</para> + ExecutionFactory. Refer to <xref linkend="translator_package"/> and + <xref linkend="translator_deploy"/> for instructions on using the JAR file. + </para> </listitem> </itemizedlist> </section> @@ -163,8 +165,7 @@ <listitem> <para> Number of input arguments and types must match the function metadata defined - in section - <link linkend="define_udf">Install user-defined functions</link> + in <xref linkend="define_udf"/>. </para> </listitem> <listitem> @@ -181,22 +182,24 @@ This <code>CommandContext</code> parameter does not need to be delared in the function metadata.</para> <example> <title>Sample code</title> - <programlisting><![CDATA[package org.something; + <programlisting language="Java" role="JAVA"><![CDATA[package org.something; -public class TempConv { - - /** - * Converts the given Celsius temperature to Fahrenheit, and returns the - * value. - * @param doubleCelsiusTemp - * @return Fahrenheit - */ - public static Double celsiusToFahrenheit(Double doubleCelsiusTemp){ - if (doubleCelsiusTemp == null) { - return null; - } - return (doubleCelsiusTemp)*9/5 + 32; - } +public class TempConv +{ + /** + * Converts the given Celsius temperature to Fahrenheit, and returns the + * value. + * @param doubleCelsiusTemp + * @return Fahrenheit + */ + public static Double celsiusToFahrenheit(Double doubleCelsiusTemp) + { + if (doubleCelsiusTemp == null) + { + return null; + } + return (doubleCelsiusTemp)*9/5 + 32; + } }]]></programlisting> </example> </section> Deleted: branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/main.xml =================================================================== --- branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/main.xml 2010-10-01 15:43:39 UTC (rev 2621) +++ branches/7.1.x/documentation/developer-guide/src/main/docbook/en-US/main.xml 2010-10-04 14:46:41 UTC (rev 2622) @@ -1,60 +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 book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> -%CustomDTD; -]> - -<book> - - <bookinfo> - <title>Teiid - Scalable Information Integration</title> - <subtitle>Teiid Developer's Guide</subtitle> - <releaseinfo>&versionNumber;</releaseinfo> - <productnumber>&versionNumber;</productnumber> - <issuenum>1</issuenum> - <copyright> - <year>&copyrightYear;</year> - <holder>&copyrightHolder;</holder> - </copyright> - <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </bookinfo> - - <toc/> - - <xi:include href="content/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/develop-adapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/translator-api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/extending-jdbc.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/udf.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/adminapi.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/appendix-b.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - -</book> -