Teiid-NightlyBuild - Build # 853 - Failure!
by jboss-qa-internal＠redhat.com
Teiid-NightlyBuild - Build # 853 - Failure:
Check console output at http://hudson.qa.jboss.com/hudson/job/Teiid-NightlyBuild/853/ to view the results.
14 years, 6 months
- 1
- 0
Teiid - Continuous Build - Build # 1171 - Failure!
by jboss-qa-internal＠redhat.com
Teiid - Continuous Build - Build # 1171 - Failure:
Check console output at http://hudson.qa.jboss.com/hudson/job/Teiid%20-%20Continuous%20Build/1171/ to view the results.
14 years, 6 months
- 1
- 0
teiid SVN: r2225 - in trunk/connectors/translator-jdbc/src: main/java/org/teiid/translator/jdbc/modeshape and 3 other directories.
by teiid-commits＠lists.jboss.org
Author: vhalbert(a)redhat.com
Date: 2010-06-11 14:31:39 -0400 (Fri, 11 Jun 2010)
New Revision: 2225
Added:
trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/modeshape/
trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/modeshape/ModeShapeExecutionFactory.java
trunk/connectors/translator-jdbc/src/test/java/org/teiid/translator/jdbc/modeshape/
trunk/connectors/translator-jdbc/src/test/java/org/teiid/translator/jdbc/modeshape/TestModeShapeSqlTranslator.java
trunk/connectors/translator-jdbc/src/test/resources/ModeShape.vdb
Log:
Teiid-1106 : Adding the ModeShape translator, which uses the base JDBC translator. This includes testcases validating support for simple queries. More semantics will be added once the initial integration has been validated.
Added: trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/modeshape/ModeShapeExecutionFactory.java
===================================================================
--- trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/modeshape/ModeShapeExecutionFactory.java (rev 0)
+++ trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/modeshape/ModeShapeExecutionFactory.java 2010-06-11 18:31:39 UTC (rev 2225)
@@ -0,0 +1,234 @@
+/*
+ * JBoss, Home of Professional Open Source.
+ * See the COPYRIGHT.txt file distributed with this work for information
+ * regarding copyright ownership. Some portions may be licensed
+ * to Red Hat, Inc. under one or more contributor license agreements.
+ *
+ * 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.
+ */
+
+package org.teiid.translator.jdbc.modeshape;
+
+import java.sql.Date;
+import java.sql.Time;
+import java.sql.Timestamp;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import org.teiid.language.ColumnReference;
+import org.teiid.language.Command;
+import org.teiid.language.Expression;
+import org.teiid.language.Function;
+import org.teiid.language.LanguageObject;
+import org.teiid.language.Literal;
+import org.teiid.language.NamedTable;
+import org.teiid.metadata.RuntimeMetadata;
+import org.teiid.translator.ExecutionContext;
+import org.teiid.translator.Translator;
+import org.teiid.translator.TranslatorException;
+import org.teiid.translator.TranslatorProperty;
+import org.teiid.translator.UpdateExecution;
+import org.teiid.translator.jdbc.ConvertModifier;
+import org.teiid.translator.jdbc.FunctionModifier;
+import org.teiid.translator.jdbc.JDBCExecutionFactory;
+import org.teiid.translator.jdbc.SQLConversionVisitor;
+
+
+
+/**
+ * Translator class for accessing the ModeShape JCR repository.
+ */
+@Translator(name="modeshape")
+public class ModeShapeExecutionFactory extends JDBCExecutionFactory {
+
+ private String version = "2.0";
+
+ @Override
+ public void start() throws TranslatorException {
+ super.start();
+
+ registerFunctionModifier("PATH", new FunctionModifier() {
+
+ @Override
+ public List<?> translate(Function function) {
+ List<Object> objs = new ArrayList<Object>();
+
+ List<Expression> parms = function.getParameters();
+
+ for (Expression s : parms)
+ {
+ String v = s.toString();
+ v.replace('\'', ' ');
+ objs.add(v);
+ }
+
+ return objs;
+ }
+ } );
+
+
+
+
+ //add in type conversion
+ ConvertModifier convertModifier = new ConvertModifier();
+
+
+ convertModifier.addTypeMapping("boolean", FunctionModifier.BOOLEAN); //$NON-NLS-1$
+ convertModifier.addTypeMapping("smallint", FunctionModifier.BYTE, FunctionModifier.SHORT); //$NON-NLS-1$
+ convertModifier.addTypeMapping("integer", FunctionModifier.INTEGER); //$NON-NLS-1$
+ convertModifier.addTypeMapping("bigint", FunctionModifier.LONG); //$NON-NLS-1$
+ convertModifier.addTypeMapping("real", FunctionModifier.FLOAT); //$NON-NLS-1$
+ convertModifier.addTypeMapping("float8", FunctionModifier.DOUBLE); //$NON-NLS-1$
+ convertModifier.addTypeMapping("numeric(38)", FunctionModifier.BIGINTEGER); //$NON-NLS-1$
+ convertModifier.addTypeMapping("decimal", FunctionModifier.BIGDECIMAL); //$NON-NLS-1$
+ convertModifier.addTypeMapping("char(1)", FunctionModifier.CHAR); //$NON-NLS-1$
+ convertModifier.addTypeMapping("varchar(4000)", FunctionModifier.STRING); //$NON-NLS-1$
+ convertModifier.addTypeMapping("date", FunctionModifier.DATE); //$NON-NLS-1$
+ convertModifier.addTypeMapping("time", FunctionModifier.TIME); //$NON-NLS-1$
+ convertModifier.addTypeMapping("timestamp", FunctionModifier.TIMESTAMP); //$NON-NLS-1$
+ convertModifier.addConvert(FunctionModifier.TIME, FunctionModifier.TIMESTAMP, new FunctionModifier() {
+ @Override
+ public List<?> translate(Function function) {
+ return Arrays.asList(function.getParameters().get(0), " + TIMESTAMP '1970-01-01'"); //$NON-NLS-1$
+ }
+ });
+ convertModifier.addConvert(FunctionModifier.TIMESTAMP, FunctionModifier.TIME, new FunctionModifier() {
+ @Override
+ public List<?> translate(Function function) {
+ return Arrays.asList("cast(date_trunc('second', ", function.getParameters().get(0), ") AS time)"); //$NON-NLS-1$ //$NON-NLS-2$
+ }
+ });
+ convertModifier.addConvert(FunctionModifier.DATE, FunctionModifier.STRING, new ConvertModifier.FormatModifier("to_char", "YYYY-MM-DD")); //$NON-NLS-1$ //$NON-NLS-2$
+ convertModifier.addConvert(FunctionModifier.TIME, FunctionModifier.STRING, new ConvertModifier.FormatModifier("to_char", "HH24:MI:SS")); //$NON-NLS-1$ //$NON-NLS-2$
+ convertModifier.addConvert(FunctionModifier.TIMESTAMP, FunctionModifier.STRING, new ConvertModifier.FormatModifier("to_char", "YYYY-MM-DD HH24:MI:SS.UF")); //$NON-NLS-1$ //$NON-NLS-2$
+ convertModifier.addConvert(FunctionModifier.BOOLEAN, FunctionModifier.STRING, new FunctionModifier() {
+ @Override
+ public List<?> translate(Function function) {
+ Expression stringValue = function.getParameters().get(0);
+ return Arrays.asList("CASE WHEN ", stringValue, " THEN 'true' WHEN not(", stringValue, ") THEN 'false' END"); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
+ }
+ });
+ convertModifier.addSourceConversion(new FunctionModifier() {
+ @Override
+ public List<?> translate(Function function) {
+ ((Literal)function.getParameters().get(1)).setValue("integer"); //$NON-NLS-1$
+ return null;
+ }
+ }, FunctionModifier.BOOLEAN);
+ }
+
+
+
+ @Override
+ public SQLConversionVisitor getSQLConversionVisitor() {
+ return new ModeShapeSQLConversionVisitor(this);
+ }
+
+
+
+ @Override
+ public List<?> translate(LanguageObject obj, ExecutionContext context) {
+
+ if (obj instanceof NamedTable) {
+
+ NamedTable nt = (NamedTable) obj;
+ List<String> ntlist = new ArrayList<String>(1);
+
+ ntlist.add("[" + nt.getMetadataObject().getNameInSource() + "]");
+ return ntlist;
+ }
+
+ if (obj instanceof ColumnReference) {
+ ColumnReference elem = (ColumnReference) obj;
+ List<String> ntlist = new ArrayList<String>(1);
+ ntlist.add("[" + elem.getMetadataObject().getNameInSource() + "]");
+ return ntlist;
+
+ }
+
+ return super.translate(obj, context);
+ }
+
+ @Override
+ public String translateLiteralBoolean(Boolean booleanValue) {
+ if(booleanValue.booleanValue()) {
+ return "TRUE"; //$NON-NLS-1$
+ }
+ return "FALSE"; //$NON-NLS-1$
+ }
+
+
+
+ @Override
+ public List<?> translateCommand(Command command, ExecutionContext context) {
+ return super.translateCommand(command, context);
+ }
+
+
+
+ @Override
+ public String translateLiteralDate(Date dateValue) {
+ return "DATE '" + formatDateValue(dateValue) + "'"; //$NON-NLS-1$//$NON-NLS-2$
+ }
+
+ @Override
+ public String translateLiteralTime(Time timeValue) {
+ return "TIME '" + formatDateValue(timeValue) + "'"; //$NON-NLS-1$//$NON-NLS-2$
+ }
+
+ @Override
+ public String translateLiteralTimestamp(Timestamp timestampValue) {
+ return "TIMESTAMP '" + formatDateValue(timestampValue) + "'"; //$NON-NLS-1$//$NON-NLS-2$
+ }
+
+ @Override
+ public int getTimestampNanoPrecision() {
+ return 6;
+ }
+
+ @Override
+ public List<String> getSupportedFunctions() {
+ List<String> supportedFunctions = new ArrayList<String>();
+ supportedFunctions.addAll(super.getSupportedFunctions());
+ supportedFunctions.add("PATH"); //$NON-NLS-1$
+ supportedFunctions.add("NAME"); //$NON-NLS-1$
+ supportedFunctions.add("ISCHILDNODE"); //$NON-NLS-1$
+
+ return supportedFunctions;
+
+ }
+
+ @TranslatorProperty(description= "ModeShape Repository Version")
+ public String getDatabaseVersion() {
+ return this.version;
+ }
+
+ public void setDatabaseVersion(String version) {
+ this.version = version;
+ }
+
+ @Override
+ public boolean useBindVariables() {
+ return false;
+ }
+
+ @Override
+ public UpdateExecution createUpdateExecution(Command command, ExecutionContext executionContext, RuntimeMetadata metadata, Object connectionFactory) throws TranslatorException {
+ throw new TranslatorException("Unsupported Execution");//$NON-NLS-1$
+ }
+
+}
Property changes on: trunk/connectors/translator-jdbc/src/main/java/org/teiid/translator/jdbc/modeshape/ModeShapeExecutionFactory.java
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Added: trunk/connectors/translator-jdbc/src/test/java/org/teiid/translator/jdbc/modeshape/TestModeShapeSqlTranslator.java
===================================================================
--- trunk/connectors/translator-jdbc/src/test/java/org/teiid/translator/jdbc/modeshape/TestModeShapeSqlTranslator.java (rev 0)
+++ trunk/connectors/translator-jdbc/src/test/java/org/teiid/translator/jdbc/modeshape/TestModeShapeSqlTranslator.java 2010-06-11 18:31:39 UTC (rev 2225)
@@ -0,0 +1,127 @@
+/*
+ * JBoss, Home of Professional Open Source.
+ * See the COPYRIGHT.txt file distributed with this work for information
+ * regarding copyright ownership. Some portions may be licensed
+ * to Red Hat, Inc. under one or more contributor license agreements.
+ *
+ * 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.
+ */
+
+package org.teiid.translator.jdbc.modeshape;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.BeforeClass;
+import org.junit.Ignore;
+import org.junit.Test;
+import org.mockito.Mockito;
+import org.teiid.core.util.UnitTestUtil;
+import org.teiid.language.Command;
+import org.teiid.translator.ExecutionContext;
+import org.teiid.translator.TranslatorException;
+import org.teiid.translator.jdbc.TranslatedCommand;
+
+import com.metamatrix.cdk.api.TranslationUtility;
+
+/**
+ */
+public class TestModeShapeSqlTranslator {
+
+ private static ModeShapeExecutionFactory TRANSLATOR;
+
+ private static String MODESHAPE_VDB = (UnitTestUtil.getTestDataPath() != null ? UnitTestUtil.getTestDataPath() : "src/test/resources") + "/ModeShape.vdb";
+
+ @BeforeClass
+ public static void setUp() throws TranslatorException {
+ TRANSLATOR = new ModeShapeExecutionFactory();
+ TRANSLATOR.start();
+
+ }
+
+
+ public void helpTestVisitor(TranslationUtility util, String input, String expectedOutput) throws TranslatorException {
+ // Convert from sql to objects
+ Command obj = util.parseCommand(input);
+
+ TranslatedCommand tc = new TranslatedCommand(Mockito.mock(ExecutionContext.class), TRANSLATOR);
+ tc.translateCommand(obj);
+
+ System.out.println("Input: "+ tc.getSql() + " Expected: " + expectedOutput);
+ assertEquals("Did not get correct sql", expectedOutput, tc.getSql()); //$NON-NLS-1$
+ }
+
+ @Test
+ public void testSimpleSelect() throws Exception {
+ String input = "select Model from Car"; //$NON-NLS-1$
+ String output = "SELECT [car:Model] FROM [car:Car]"; //$NON-NLS-1$
+
+ // FakeTranslationFactory.getInstance().getExampleTranslationUtility(),
+ helpTestVisitor(new TranslationUtility(MODESHAPE_VDB),
+ input,
+ output);
+
+ }
+
+ @Test
+ public void testWhereClause() throws Exception {
+
+ String input = "select Model from Car WHERE Make = 'Honda'"; //$NON-NLS-1$
+ String output = "SELECT [car:Model] FROM [car:Car] WHERE [car:Make] = 'Honda'"; //$NON-NLS-1$
+
+ // FakeTranslationFactory.getInstance().getExampleTranslationUtility(),
+ helpTestVisitor(new TranslationUtility(MODESHAPE_VDB), input, output);
+
+ }
+
+ @Test
+ public void testOrderBy() throws Exception {
+
+ String input = "select Model from Car ORDER BY Make"; //$NON-NLS-1$
+ String output = "SELECT [car:Model] FROM [car:Car] ORDER BY [car:Make]"; //$NON-NLS-1$
+
+ // FakeTranslationFactory.getInstance().getExampleTranslationUtility(),
+ helpTestVisitor(new TranslationUtility(MODESHAPE_VDB), input, output);
+
+ }
+
+ @Ignore
+ @Test
+ public void testUsingAlias() throws Exception {
+
+ String input = "select c.Model from Car As c"; //$NON-NLS-1$
+ String output = "SELECT c.[car:Model] FROM [car:Car] As c"; //$NON-NLS-1$
+
+ // FakeTranslationFactory.getInstance().getExampleTranslationUtility(),
+ helpTestVisitor(new TranslationUtility(MODESHAPE_VDB), input, output);
+
+ }
+
+ @Ignore
+ @Test
+ public void testUsingNameFunction() throws Exception {
+
+ String input = "select Model from Car as car WHERE PATH('car') LIKE '%/Hybrid/%'"; //$NON-NLS-1$
+ String output = "SELECT [car:Model] FROM [car:Car] WHERE PATH(car:Car) LIKE '%/Hybrid/%'"; //$NON-NLS-1$
+
+ // FakeTranslationFactory.getInstance().getExampleTranslationUtility(),
+ helpTestVisitor(new TranslationUtility(MODESHAPE_VDB), input, output);
+
+
+ }
+
+
+
+}
Property changes on: trunk/connectors/translator-jdbc/src/test/java/org/teiid/translator/jdbc/modeshape/TestModeShapeSqlTranslator.java
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Added: trunk/connectors/translator-jdbc/src/test/resources/ModeShape.vdb
===================================================================
(Binary files differ)
Property changes on: trunk/connectors/translator-jdbc/src/test/resources/ModeShape.vdb
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
14 years, 6 months
- 1
- 0
teiid SVN: r2224 - in trunk: documentation/quick-start-example and 1 other directory.
by teiid-commits＠lists.jboss.org
Author: rareddy
Date: 2010-06-11 14:30:24 -0400 (Fri, 11 Jun 2010)
New Revision: 2224
Modified:
trunk/build/assembly/jboss-container/dist.xml
trunk/documentation/quick-start-example/pom.xml
Log:
Misc: adding pdf documents to the kit and also the schema file
Modified: trunk/build/assembly/jboss-container/dist.xml
===================================================================
--- trunk/build/assembly/jboss-container/dist.xml 2010-06-11 16:49:34 UTC (rev 2223)
+++ trunk/build/assembly/jboss-container/dist.xml 2010-06-11 18:30:24 UTC (rev 2224)
@@ -37,9 +37,46 @@
</includes>
<outputDirectory>lib</outputDirectory>
</fileSet>
-
+
+ <fileSet>
+ <directory>target/distribution/teiid-${version}-docs.dir/admin-guide/en-US/pdf</directory>
+ <includes>
+ <include>teiid_admin_guide.pdf</include>
+ </includes>
+ <outputDirectory>teiid-docs</outputDirectory>
+ </fileSet>
+ <fileSet>
+ <directory>target/distribution/teiid-${version}-docs.dir/reference/en-US/pdf</directory>
+ <includes>
+ <include>teiid_reference.pdf</include>
+ </includes>
+ <outputDirectory>teiid-docs</outputDirectory>
+ </fileSet>
+ <fileSet>
+ <directory>target/distribution/teiid-${version}-docs.dir/quick-start-example/en-US/pdf</directory>
+ <includes>
+ <include>quick_start_example.pdf</include>
+ </includes>
+ <outputDirectory>teiid-docs</outputDirectory>
+ </fileSet>
+ <fileSet>
+ <directory>target/distribution/teiid-${version}-docs.dir/connector-developer-guide/en-US/pdf</directory>
+ <includes>
+ <include>connector_developer_guide.pdf</include>
+ </includes>
+ <outputDirectory>teiid-docs</outputDirectory>
+ </fileSet>
+ <fileSet>
+ <directory>client/src/main/resources</directory>
+ <includes>
+ <include>vdb-deployer.xsd</include>
+ </includes>
+ <outputDirectory>teiid-docs/schema</outputDirectory>
+ </fileSet>
</fileSets>
+
+
<!-- these have external dependent clients like connectors-->
<moduleSets>
<moduleSet>
Modified: trunk/documentation/quick-start-example/pom.xml
===================================================================
--- trunk/documentation/quick-start-example/pom.xml 2010-06-11 16:49:34 UTC (rev 2223)
+++ trunk/documentation/quick-start-example/pom.xml 2010-06-11 18:30:24 UTC (rev 2224)
@@ -6,7 +6,7 @@
<version>7.0.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
- <artifactId>quick-start-guide</artifactId>
+ <artifactId>quick-start-example</artifactId>
<packaging>jdocbook</packaging>
<name>Quick Start Guide</name>
<description>The Teiid Quick Start guide</description>
14 years, 6 months
- 1
- 0
teiid SVN: r2223 - trunk/documentation.
by teiid-commits＠lists.jboss.org
Author: rareddy
Date: 2010-06-11 12:49:34 -0400 (Fri, 11 Jun 2010)
New Revision: 2223
Modified:
trunk/documentation/pom.xml
Log:
TEIID-315: server-extension-guide is merged with connector-developer-guide now
Modified: trunk/documentation/pom.xml
===================================================================
--- trunk/documentation/pom.xml 2010-06-11 16:49:04 UTC (rev 2222)
+++ trunk/documentation/pom.xml 2010-06-11 16:49:34 UTC (rev 2223)
@@ -15,7 +15,6 @@
<module>admin-guide</module>
<module>reference</module>
<module>connector-developer-guide</module>
- <module>server-extensions-guide</module>
<module>quick-start-example</module>
<module>salesforce-connector-guide</module>
</modules>
14 years, 6 months
- 1
- 0
teiid SVN: r2222 - trunk/documentation.
by teiid-commits＠lists.jboss.org
Author: rareddy
Date: 2010-06-11 12:49:04 -0400 (Fri, 11 Jun 2010)
New Revision: 2222
Removed:
trunk/documentation/server-extensions-guide/
Log:
TEIID-315: server-extension-guide is merged with connector-developer-guide now
14 years, 6 months
- 1
- 0
teiid SVN: r2221 - in trunk/documentation: client-developers-guide and 9 other directories.
by teiid-commits＠lists.jboss.org
Author: rareddy
Date: 2010-06-11 12:44:33 -0400 (Fri, 11 Jun 2010)
New Revision: 2221
Added:
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-b.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/logging.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/security.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/main.xml
Removed:
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml
trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml
trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/logging.xml
trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml
Modified:
trunk/documentation/admin-guide/pom.xml
trunk/documentation/client-developers-guide/pom.xml
trunk/documentation/connector-developer-guide/pom.xml
trunk/documentation/quick-start-example/pom.xml
trunk/documentation/reference/pom.xml
trunk/documentation/salesforce-connector-guide/pom.xml
trunk/documentation/server-extensions-guide/pom.xml
trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml
Log:
TEIID-1120: Single HTML Page
Modified: trunk/documentation/admin-guide/pom.xml
===================================================================
--- trunk/documentation/admin-guide/pom.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/admin-guide/pom.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -19,6 +19,11 @@
<extensions>true</extensions>
<dependencies>
<dependency>
+ <groupId>net.sf.docbook</groupId>
+ <artifactId>docbook</artifactId>
+ <version>1.74.0</version>
+ </dependency>
+ <dependency>
<groupId>org.jboss</groupId>
<artifactId>jbossorg-docbook-xslt</artifactId>
<version>1.1.0</version>
@@ -47,11 +52,11 @@
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
<finalName>teiid_admin_guide.pdf</finalName>
</format>
- <!-- <format>
+ <format>
<formatName>html_single</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
<finalName>index.html</finalName>
- </format> -->
+ </format>
<format>
<formatName>html</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
@@ -60,6 +65,8 @@
</formats>
<options>
<xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <docbookVersion>1.72.0</docbookVersion>
<localeSeparator>-</localeSeparator>
<useRelativeImageUris>false</useRelativeImageUris>
</options>
Modified: trunk/documentation/client-developers-guide/pom.xml
===================================================================
--- trunk/documentation/client-developers-guide/pom.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/client-developers-guide/pom.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -19,6 +19,11 @@
<extensions>true</extensions>
<dependencies>
<dependency>
+ <groupId>net.sf.docbook</groupId>
+ <artifactId>docbook</artifactId>
+ <version>1.74.0</version>
+ </dependency>
+ <dependency>
<groupId>org.jboss</groupId>
<artifactId>jbossorg-docbook-xslt</artifactId>
<version>1.1.0</version>
@@ -47,11 +52,11 @@
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
<finalName>client_developers_guide.pdf</finalName>
</format>
- <!-- <format>
+ <format>
<formatName>html_single</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
<finalName>index.html</finalName>
- </format> -->
+ </format>
<format>
<formatName>html</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
@@ -60,6 +65,8 @@
</formats>
<options>
<xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <docbookVersion>1.72.0</docbookVersion>
<localeSeparator>-</localeSeparator>
<useRelativeImageUris>false</useRelativeImageUris>
</options>
Modified: trunk/documentation/connector-developer-guide/pom.xml
===================================================================
--- trunk/documentation/connector-developer-guide/pom.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/connector-developer-guide/pom.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -19,6 +19,11 @@
<extensions>true</extensions>
<dependencies>
<dependency>
+ <groupId>net.sf.docbook</groupId>
+ <artifactId>docbook</artifactId>
+ <version>1.74.0</version>
+ </dependency>
+ <dependency>
<groupId>org.jboss</groupId>
<artifactId>jbossorg-docbook-xslt</artifactId>
<version>1.1.0</version>
@@ -31,7 +36,7 @@
</dependency>
</dependencies>
<configuration>
- <sourceDocumentName>connector_developer_guide.xml</sourceDocumentName>
+ <sourceDocumentName>main.xml</sourceDocumentName>
<imageResource>
<directory>${basedir}/src/main/docbook/en-US</directory>
<excludes>
@@ -47,11 +52,11 @@
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
<finalName>connector_developer_guide.pdf</finalName>
</format>
- <!-- <format>
+ <format>
<formatName>html_single</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
<finalName>index.html</finalName>
- </format> -->
+ </format>
<format>
<formatName>html</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
@@ -60,6 +65,8 @@
</formats>
<options>
<xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <docbookVersion>1.72.0</docbookVersion>
<localeSeparator>-</localeSeparator>
<useRelativeImageUris>false</useRelativeImageUris>
</options>
Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -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 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 Translator and Resource Adapter Developer's Guide</subtitle>
- <releaseinfo>&versionNumber;</releaseinfo>
- <productnumber>&versionNumber;</productnumber>
- <issuenum>1</issuenum>
- <copyright>
- <year>©rightYear;</year>
- <holder>©rightHolder;</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/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/lob-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/extending-jdbc-connector.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/jdbc-translator-examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
-</book>
-
Copied: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-b.xml (from rev 2217, trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml)
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-b.xml (rev 0)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-b.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -0,0 +1,23 @@
+<appendix id="advanced_topics">
+ <title>Advanced Topics</title>
+ <sect1>
+ <title>Migration From Previous Versions</title>
+ <para>It is recommended that customers who have utilized the internal JDBC membership domain from releases
+ prior to MetaMatrix 5.5 migrate those users and groups to an LDAP compliant directory server. Several free
+ and open source directory servers can be used including:</para>
+ <para>
+ The Fedora Directory Server
+ <ulink url="http://directory.fedoraproject.org/">http://directory.fedoraproject.org/</ulink>
+ </para>
+ <para>
+ Open LDAP
+ <ulink url="http://www.openldap.org/">http://www.openldap.org/</ulink>
+ </para>
+ <para>
+ Apache Directory Server
+ <ulink url="http://directory.apache.org/">http://directory.apache.org/</ulink>
+ </para>
+ <para>If there are additional questions or the need for guidance in the migration process, please contact
+ technical support.</para>
+ </sect1>
+</appendix>
\ No newline at end of file
Copied: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/logging.xml (from rev 2217, trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/logging.xml)
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/logging.xml (rev 0)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/logging.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -0,0 +1,278 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
+%CustomDTD;
+]>
+<chapter id="logging">
+ <title>Logging</title>
+ <sect1 id="general_logging">
+ <title>General 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 <profile>/conf/jboss-teiid-log4j.xml containing much of information from chapter.
+ </para>
+ <para>
+ All the logs
+ produced by Teiid are prefixed by org.teiid. This
+ makes it extremely
+ easy to control of of Teiid logging from a single
+ context. Note however that changes to the log configuration file
+ require a restart to take affect
+ </para>
+ <sect2>
+ <title>Logging Contexts</title>
+ <para>While all of Teiid's logs are prefixed with org.teiid, there
+ are more specific contexts depending on the functional area of the
+ system. Note that logs originating from third-party code, including
+ integrated org.jboss components, will be logged through their
+ respective contexts and not through org.teiid. See the table below for information on contexts
+ relevant to Teiid. See the container's jboss-log4j.xml for a more
+ complete listing of logging contexts used in the container.
+ </para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>Context</para>
+ </entry>
+ <entry>
+ <para>Description</para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>com.arjuna</para>
+ </entry>
+ <entry>
+ <para>Third-party transaction manager. This will include
+ information about all transactions, not just those for Teiid.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid</para>
+ </entry>
+ <entry>
+ <para>Root context for all Teiid logs. Note: there are
+ potentially other contexts used under org.teiid than are shown
+ in this table.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.PROCESSOR</para>
+ </entry>
+ <entry>
+ <para>Query processing logs. See also org.teiid.PLANNER for
+ query planning logs.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.PLANNER</para>
+ </entry>
+ <entry>
+ <para>Query planning logs.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.SECURITY</para>
+ </entry>
+ <entry>
+ <para>Session/Authentication events - see also AUDIT logging</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.TRANSPORT</para>
+ </entry>
+ <entry>
+ <para>Events related to the socket transport.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.RUNTIME</para>
+ </entry>
+ <entry>
+ <para>Events related to work management and system start/stop.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.CONNECTOR</para>
+ </entry>
+ <entry>
+ <para>Connector logs.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.BUFFER_MGR</para>
+ </entry>
+ <entry>
+ <para>Buffer and storage management logs.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.TXN_LOG</para>
+ </entry>
+ <entry>
+ <para>Detail log of all transaction operations.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.COMMAND_LOG</para>
+ </entry>
+ <entry>
+ <para>
+ See
+ <link linkend="command_logigng">command logging</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.AUDIT_LOG</para>
+ </entry>
+ <entry>
+ <para>
+ See
+ <link linkend="audit_logigng">audit logging</link>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>org.teiid.ADMIN_API</para>
+ </entry>
+ <entry>
+ <para>Admin API logs.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+ <sect2>
+ <title>Command Logging API</title>
+ <para>
+ If the default log4j logging mechanisms are not sufficient for your
+ logging needs you may need a appender - see
+ <ulink url="http://logging.apache.org/log4j/1.2/apidocs/index.html">the log4j javadocs</ulink>
+ . Note that log4j already provides quite a few appenders including
+ JMS, RDBMS, and SMTP.
+ </para>
+ <para>If you develop a custom logging solution, the implementation
+ jar should be placed in the lib directory of the server profile
+ Teiid is installed in.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="command_logging">
+ <title>Command Logging</title>
+ <para>Command logging captures executing commands in the
+ Teiid System.
+ Both user commands (that have been submitted
+ to Teiid)
+ and data source
+ commands (that are being executed by the
+ connectors)
+ are tracked
+ through command logging.</para>
+ <para>To enable command logging to the default log location, simply
+ enable the DETAIL level of logging for the org.teiid.COMMAND_LOG
+ context.</para>
+ <para>
+ To enable command logging to an alternative file location,
+ configure a
+ separate file appender for the DETAIL logging of the
+ org.teiid.COMMAND_LOG context. An example of this is shown below and
+ can also be found in the jboss-log4j.xml distributed with Teiid.
+ <programlisting><![CDATA[
+ <appender name="COMMAND" class="org.apache.log4j.RollingFileAppender">
+ <param name="File" value="log/command.log"/>
+ <param name="MaxFileSize" value="1000KB"/>
+ <param name="MaxBackupIndex" value="25"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %p [%t] %c - %m%n"/>
+ </layout>
+ </appender>
+
+ <category name="org.teiid.COMMAND_LOG">
+ <priority value="INFO"/>
+ <appender-ref ref="COMMAND"/>
+ </category>
+ ]]>
+ </programlisting>
+ </para>
+ <sect2>
+ <title>Command Logging API</title>
+ <para>
+ If the default log4j logging mechanisms are not sufficient for
+ your
+ command logging needs, you may need a custom log4j appender.
+ The
+ custom appender will have access to log4j LoggingEvents to the
+ COMMAND_LOG context, which have a
+ message that is an instance of
+ org.teiid.logging.api.CommandLogMessage defined in the
+ teiid-connector-api-&versionNumber;.jar.
+ </para>
+ <para>
+ See
+ <link linkend="general_logging">General Logging</link>
+ for more information on utilizing log4j.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="audit_logging">
+ <title>Audit Logging</title>
+ <para>Audit logging captures important security events. This includes
+ the enforcement of permissions, authentication success/failures, etc.
+ </para>
+ <para>To enable audit logging to the default log location, simply
+ enable the DETAIL level of logging for the org.teiid.AUDIT_LOG
+ context.</para>
+ <para>To enable audit logging to an alternative file location,
+ configure a separate file appender for the DETAIL logging of the
+ org.teiid.AUDIT_LOG context. An example of this is already in
+ the
+ log4j.xml distributed with Teiid.</para>
+ <sect2>
+ <title>Audit Logging API</title>
+ <para>
+ If the default log4j logging mechanisms are not sufficient for
+ your
+ audit logging needs, you may need a custom log4j appender.
+ The
+ custom
+ appender will have access to log4j LoggingEvents to the
+ AUDIT_LOG
+ context, which have a
+ message that is an instance of
+ org.teiid.logging.api.AuditMessage defined in the
+ teiid-connector-api-&versionNumber;.jar.
+ AuditMessages include
+ information about user, the action, and the
+ target(s) of the action.
+ </para>
+ <para>
+ See
+ <link linkend="general_logging">General Logging</link>
+ for more information on utilizing log4j.
+ </para>
+ </sect2>
+ </sect1>
+</chapter>
\ No newline at end of file
Copied: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/security.xml (from rev 2217, trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml)
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/security.xml (rev 0)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/security.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="custom_security">
+ <title>Teiid Security</title>
+ <para>The Teiid system provides a range of built-in and extensible
+ security features to enable the
+ secure access of data. </para>
+ <sect1>
+ <title>Authentication</title>
+ <para>JDBC clients may use simple passwords to authenticate a user.
+ </para>
+ <para>Typically a user name is required, however user names may be
+ considered optional if the
+ identity of the user can be discerned by
+ the password credential alone. In
+ any case it is up
+ to the configured
+ security domain to determine whether a user can be
+ authenticated.
+ </para>
+ </sect1>
+ <sect1>
+ <title>Authorization</title>
+ <para>Authorization covers both administrative activities and
+ data
+ roles. A data role is a collection of permissions (also referred to
+ as entitlements) and a
+ collection of entitled principals or groups.
+ With the deployment of a VDB
+ the deployer can choose which principals
+ and groups have which data roles.</para>
+ </sect1>
+ <sect1>
+ <title>Encryption</title>
+ <para>At a transport level Teiid provides built-in support for JDBC
+ over SSL or just sensitive message encryption when SSL is not in use.
+ </para>
+ <para>
+ Passwords in configuration files however are by default stored in
+ plain text. If you need these values to be encrypted, please see
+ <ulink
+ url="http://community.jboss.org/wiki/maskingpasswordsinjbossasxmlconfiguration">encrypting passwords</ulink>
+ for instructions on encryption facilities provided by the container.
+ </para>
+ </sect1>
+ <sect1>
+ <title>LoginModules</title>
+ <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.html">JBossAS Security</ulink>
+ for general information on configuring security in JBossAS.</para>
+ <para>
+ Teiid can be configured with multiple named application policies
+ that group together relevant LoginModules. Each of these application
+ policy (or domains) names can be used to fully
+ qualify user names to
+ authenticate only against that domain. The format for a qualified
+ name is username@domainname.
+ </para>
+ <para>If a user name is not fully qualified, then the installed
+ domains will be consulted in order until a domain
+ successfully or unsuccessfully authenticates the
+ user.
+ </para>
+ <para>If no domain can authenticate the user, the logon
+ attempt will fail.
+ Details of the failed attempt including invalid users, which
+ domains were consulted, etc. will be in the server log with appropriate
+ levels of severity.</para>
+ <sect2>
+ <title>Built-in LoginModules</title>
+ <para>JBossAS provides several LoginModules for common authentication needs, such as authenticating from text files or LDAP.</para>
+ <para>The UsersRolesLoginModule, which utilizes simple text files
+ to authenticate users and to define
+ their groups. The teiid-jboss-beans.xml configuration file contains an example of how to use UsersRolesLoginModule.
+ Note that this is typically not for production use.
+ </para>
+ <para>See <ulink url="http://community.jboss.org/docs/DOC-11253">LDAP LoginModule configuration</ulink> for utilizing LDAP based authentication.
+ </para>
+ </sect2>
+ <sect2>
+ <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/JAASLMDevGuide.html">JAAS development guide</ulink>.
+ There are also numerous guides available.
+ </para>
+ </sect2>
+ </sect1>
+</chapter>
\ No newline at end of file
Copied: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/main.xml (from rev 2220, trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml)
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/main.xml (rev 0)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/main.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -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 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 Translator and Resource Adapter Developer's Guide</subtitle>
+ <releaseinfo>&versionNumber;</releaseinfo>
+ <productnumber>&versionNumber;</productnumber>
+ <issuenum>1</issuenum>
+ <copyright>
+ <year>©rightYear;</year>
+ <holder>©rightHolder;</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/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/lob-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/extending-jdbc-connector.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/jdbc-translator-examples.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>
+
Modified: trunk/documentation/quick-start-example/pom.xml
===================================================================
--- trunk/documentation/quick-start-example/pom.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/quick-start-example/pom.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -19,6 +19,11 @@
<extensions>true</extensions>
<dependencies>
<dependency>
+ <groupId>net.sf.docbook</groupId>
+ <artifactId>docbook</artifactId>
+ <version>1.74.0</version>
+ </dependency>
+ <dependency>
<groupId>org.jboss</groupId>
<artifactId>jbossorg-docbook-xslt</artifactId>
<version>1.1.0</version>
@@ -47,11 +52,11 @@
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
<finalName>quick_start_example.pdf</finalName>
</format>
- <!-- <format>
+ <format>
<formatName>html_single</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
<finalName>index.html</finalName>
- </format> -->
+ </format>
<format>
<formatName>html</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
@@ -60,6 +65,8 @@
</formats>
<options>
<xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <docbookVersion>1.72.0</docbookVersion>
<localeSeparator>-</localeSeparator>
<useRelativeImageUris>false</useRelativeImageUris>
</options>
Modified: trunk/documentation/reference/pom.xml
===================================================================
--- trunk/documentation/reference/pom.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/reference/pom.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -19,6 +19,11 @@
<extensions>true</extensions>
<dependencies>
<dependency>
+ <groupId>net.sf.docbook</groupId>
+ <artifactId>docbook</artifactId>
+ <version>1.74.0</version>
+ </dependency>
+ <dependency>
<groupId>org.jboss</groupId>
<artifactId>jbossorg-docbook-xslt</artifactId>
<version>1.1.0</version>
@@ -47,11 +52,11 @@
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
<finalName>teiid_reference.pdf</finalName>
</format>
- <!-- <format>
+ <format>
<formatName>html_single</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
<finalName>index.html</finalName>
- </format> -->
+ </format>
<format>
<formatName>html</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
@@ -59,6 +64,8 @@
</format>
</formats>
<options>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <docbookVersion>1.72.0</docbookVersion>
<xincludeSupported>true</xincludeSupported>
<localeSeparator>-</localeSeparator>
<useRelativeImageUris>false</useRelativeImageUris>
Modified: trunk/documentation/salesforce-connector-guide/pom.xml
===================================================================
--- trunk/documentation/salesforce-connector-guide/pom.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/salesforce-connector-guide/pom.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -19,6 +19,11 @@
<extensions>true</extensions>
<dependencies>
<dependency>
+ <groupId>net.sf.docbook</groupId>
+ <artifactId>docbook</artifactId>
+ <version>1.74.0</version>
+ </dependency>
+ <dependency>
<groupId>org.jboss</groupId>
<artifactId>jbossorg-docbook-xslt</artifactId>
<version>1.1.0</version>
@@ -47,11 +52,11 @@
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
<finalName>salesforce_connector_guide.pdf</finalName>
</format>
- <!-- <format>
+ <format>
<formatName>html_single</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
<finalName>index.html</finalName>
- </format> -->
+ </format>
<format>
<formatName>html</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
@@ -60,6 +65,8 @@
</formats>
<options>
<xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <docbookVersion>1.72.0</docbookVersion>
<localeSeparator>-</localeSeparator>
<useRelativeImageUris>false</useRelativeImageUris>
</options>
Modified: trunk/documentation/server-extensions-guide/pom.xml
===================================================================
--- trunk/documentation/server-extensions-guide/pom.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/server-extensions-guide/pom.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -19,6 +19,11 @@
<extensions>true</extensions>
<dependencies>
<dependency>
+ <groupId>net.sf.docbook</groupId>
+ <artifactId>docbook</artifactId>
+ <version>1.74.0</version>
+ </dependency>
+ <dependency>
<groupId>org.jboss</groupId>
<artifactId>jbossorg-docbook-xslt</artifactId>
<version>1.1.0</version>
@@ -28,7 +33,7 @@
<artifactId>jbossorg-jdocbook-style</artifactId>
<version>1.1.0</version>
<type>jdocbook-style</type>
- </dependency>
+ </dependency>
</dependencies>
<configuration>
<sourceDocumentName>server_extensions_guide.xml</sourceDocumentName>
@@ -47,11 +52,11 @@
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
<finalName>server_extensions_guide.pdf</finalName>
</format>
- <!-- <format>
+ <format>
<formatName>html_single</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
<finalName>index.html</finalName>
- </format> -->
+ </format>
<format>
<formatName>html</formatName>
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
@@ -60,6 +65,8 @@
</formats>
<options>
<xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <docbookVersion>1.72.0</docbookVersion>
<localeSeparator>-</localeSeparator>
<useRelativeImageUris>false</useRelativeImageUris>
</options>
Deleted: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml
===================================================================
--- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -1,23 +0,0 @@
-<appendix id="advanced_topics">
- <title>Advanced Topics</title>
- <sect1>
- <title>Migration From Previous Versions</title>
- <para>It is recommended that customers who have utilized the internal JDBC membership domain from releases
- prior to MetaMatrix 5.5 migrate those users and groups to an LDAP compliant directory server. Several free
- and open source directory servers can be used including:</para>
- <para>
- The Fedora Directory Server
- <ulink url="http://directory.fedoraproject.org/">http://directory.fedoraproject.org/</ulink>
- </para>
- <para>
- Open LDAP
- <ulink url="http://www.openldap.org/">http://www.openldap.org/</ulink>
- </para>
- <para>
- Apache Directory Server
- <ulink url="http://directory.apache.org/">http://directory.apache.org/</ulink>
- </para>
- <para>If there are additional questions or the need for guidance in the migration process, please contact
- technical support.</para>
- </sect1>
-</appendix>
\ No newline at end of file
Deleted: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/logging.xml
===================================================================
--- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/logging.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/logging.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -1,278 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
-%CustomDTD;
-]>
-<chapter id="logging">
- <title>Logging</title>
- <sect1 id="general_logging">
- <title>General 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 <profile>/conf/jboss-teiid-log4j.xml containing much of information from chapter.
- </para>
- <para>
- All the logs
- produced by Teiid are prefixed by org.teiid. This
- makes it extremely
- easy to control of of Teiid logging from a single
- context. Note however that changes to the log configuration file
- require a restart to take affect
- </para>
- <sect2>
- <title>Logging Contexts</title>
- <para>While all of Teiid's logs are prefixed with org.teiid, there
- are more specific contexts depending on the functional area of the
- system. Note that logs originating from third-party code, including
- integrated org.jboss components, will be logged through their
- respective contexts and not through org.teiid. See the table below for information on contexts
- relevant to Teiid. See the container's jboss-log4j.xml for a more
- complete listing of logging contexts used in the container.
- </para>
- <informaltable frame="all">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- <para>Context</para>
- </entry>
- <entry>
- <para>Description</para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>com.arjuna</para>
- </entry>
- <entry>
- <para>Third-party transaction manager. This will include
- information about all transactions, not just those for Teiid.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid</para>
- </entry>
- <entry>
- <para>Root context for all Teiid logs. Note: there are
- potentially other contexts used under org.teiid than are shown
- in this table.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.PROCESSOR</para>
- </entry>
- <entry>
- <para>Query processing logs. See also org.teiid.PLANNER for
- query planning logs.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.PLANNER</para>
- </entry>
- <entry>
- <para>Query planning logs.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.SECURITY</para>
- </entry>
- <entry>
- <para>Session/Authentication events - see also AUDIT logging</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.TRANSPORT</para>
- </entry>
- <entry>
- <para>Events related to the socket transport.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.RUNTIME</para>
- </entry>
- <entry>
- <para>Events related to work management and system start/stop.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.CONNECTOR</para>
- </entry>
- <entry>
- <para>Connector logs.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.BUFFER_MGR</para>
- </entry>
- <entry>
- <para>Buffer and storage management logs.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.TXN_LOG</para>
- </entry>
- <entry>
- <para>Detail log of all transaction operations.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.COMMAND_LOG</para>
- </entry>
- <entry>
- <para>
- See
- <link linkend="command_logigng">command logging</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.AUDIT_LOG</para>
- </entry>
- <entry>
- <para>
- See
- <link linkend="audit_logigng">audit logging</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>org.teiid.ADMIN_API</para>
- </entry>
- <entry>
- <para>Admin API logs.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- <sect2>
- <title>Command Logging API</title>
- <para>
- If the default log4j logging mechanisms are not sufficient for your
- logging needs you may need a appender - see
- <ulink url="http://logging.apache.org/log4j/1.2/apidocs/index.html">the log4j javadocs</ulink>
- . Note that log4j already provides quite a few appenders including
- JMS, RDBMS, and SMTP.
- </para>
- <para>If you develop a custom logging solution, the implementation
- jar should be placed in the lib directory of the server profile
- Teiid is installed in.
- </para>
- </sect2>
- </sect1>
- <sect1 id="command_logging">
- <title>Command Logging</title>
- <para>Command logging captures executing commands in the
- Teiid System.
- Both user commands (that have been submitted
- to Teiid)
- and data source
- commands (that are being executed by the
- connectors)
- are tracked
- through command logging.</para>
- <para>To enable command logging to the default log location, simply
- enable the DETAIL level of logging for the org.teiid.COMMAND_LOG
- context.</para>
- <para>
- To enable command logging to an alternative file location,
- configure a
- separate file appender for the DETAIL logging of the
- org.teiid.COMMAND_LOG context. An example of this is shown below and
- can also be found in the jboss-log4j.xml distributed with Teiid.
- <programlisting><![CDATA[
- <appender name="COMMAND" class="org.apache.log4j.RollingFileAppender">
- <param name="File" value="log/command.log"/>
- <param name="MaxFileSize" value="1000KB"/>
- <param name="MaxBackupIndex" value="25"/>
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%d %p [%t] %c - %m%n"/>
- </layout>
- </appender>
-
- <category name="org.teiid.COMMAND_LOG">
- <priority value="INFO"/>
- <appender-ref ref="COMMAND"/>
- </category>
- ]]>
- </programlisting>
- </para>
- <sect2>
- <title>Command Logging API</title>
- <para>
- If the default log4j logging mechanisms are not sufficient for
- your
- command logging needs, you may need a custom log4j appender.
- The
- custom appender will have access to log4j LoggingEvents to the
- COMMAND_LOG context, which have a
- message that is an instance of
- org.teiid.logging.api.CommandLogMessage defined in the
- teiid-connector-api-&versionNumber;.jar.
- </para>
- <para>
- See
- <link linkend="general_logging">General Logging</link>
- for more information on utilizing log4j.
- </para>
- </sect2>
- </sect1>
- <sect1 id="audit_logging">
- <title>Audit Logging</title>
- <para>Audit logging captures important security events. This includes
- the enforcement of permissions, authentication success/failures, etc.
- </para>
- <para>To enable audit logging to the default log location, simply
- enable the DETAIL level of logging for the org.teiid.AUDIT_LOG
- context.</para>
- <para>To enable audit logging to an alternative file location,
- configure a separate file appender for the DETAIL logging of the
- org.teiid.AUDIT_LOG context. An example of this is already in
- the
- log4j.xml distributed with Teiid.</para>
- <sect2>
- <title>Audit Logging API</title>
- <para>
- If the default log4j logging mechanisms are not sufficient for
- your
- audit logging needs, you may need a custom log4j appender.
- The
- custom
- appender will have access to log4j LoggingEvents to the
- AUDIT_LOG
- context, which have a
- message that is an instance of
- org.teiid.logging.api.AuditMessage defined in the
- teiid-connector-api-&versionNumber;.jar.
- AuditMessages include
- information about user, the action, and the
- target(s) of the action.
- </para>
- <para>
- See
- <link linkend="general_logging">General Logging</link>
- for more information on utilizing log4j.
- </para>
- </sect2>
- </sect1>
-</chapter>
\ No newline at end of file
Deleted: trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml
===================================================================
--- trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/content/security.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -1,93 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="custom_security">
- <title>Teiid Security</title>
- <para>The Teiid system provides a range of built-in and extensible
- security features to enable the
- secure access of data. </para>
- <sect1>
- <title>Authentication</title>
- <para>JDBC clients may use simple passwords to authenticate a user.
- </para>
- <para>Typically a user name is required, however user names may be
- considered optional if the
- identity of the user can be discerned by
- the password credential alone. In
- any case it is up
- to the configured
- security domain to determine whether a user can be
- authenticated.
- </para>
- </sect1>
- <sect1>
- <title>Authorization</title>
- <para>Authorization covers both administrative activities and
- data
- roles. A data role is a collection of permissions (also referred to
- as entitlements) and a
- collection of entitled principals or groups.
- With the deployment of a VDB
- the deployer can choose which principals
- and groups have which data roles.</para>
- </sect1>
- <sect1>
- <title>Encryption</title>
- <para>At a transport level Teiid provides built-in support for JDBC
- over SSL or just sensitive message encryption when SSL is not in use.
- </para>
- <para>
- Passwords in configuration files however are by default stored in
- plain text. If you need these values to be encrypted, please see
- <ulink
- url="http://community.jboss.org/wiki/maskingpasswordsinjbossasxmlconfiguration">encrypting passwords</ulink>
- for instructions on encryption facilities provided by the container.
- </para>
- </sect1>
- <sect1>
- <title>LoginModules</title>
- <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.html">JBossAS Security</ulink>
- for general information on configuring security in JBossAS.</para>
- <para>
- Teiid can be configured with multiple named application policies
- that group together relevant LoginModules. Each of these application
- policy (or domains) names can be used to fully
- qualify user names to
- authenticate only against that domain. The format for a qualified
- name is username@domainname.
- </para>
- <para>If a user name is not fully qualified, then the installed
- domains will be consulted in order until a domain
- successfully or unsuccessfully authenticates the
- user.
- </para>
- <para>If no domain can authenticate the user, the logon
- attempt will fail.
- Details of the failed attempt including invalid users, which
- domains were consulted, etc. will be in the server log with appropriate
- levels of severity.</para>
- <sect2>
- <title>Built-in LoginModules</title>
- <para>JBossAS provides several LoginModules for common authentication needs, such as authenticating from text files or LDAP.</para>
- <para>The UsersRolesLoginModule, which utilizes simple text files
- to authenticate users and to define
- their groups. The teiid-jboss-beans.xml configuration file contains an example of how to use UsersRolesLoginModule.
- Note that this is typically not for production use.
- </para>
- <para>See <ulink url="http://community.jboss.org/docs/DOC-11253">LDAP LoginModule configuration</ulink> for utilizing LDAP based authentication.
- </para>
- </sect2>
- <sect2>
- <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/JAASLMDevGuide.html">JAAS development guide</ulink>.
- There are also numerous guides available.
- </para>
- </sect2>
- </sect1>
-</chapter>
\ No newline at end of file
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 2010-06-11 00:22:28 UTC (rev 2220)
+++ trunk/documentation/server-extensions-guide/src/main/docbook/en-US/server_extensions_guide.xml 2010-06-11 16:44:33 UTC (rev 2221)
@@ -46,9 +46,6 @@
<toc/>
<xi:include href="content/introduction.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" />
</book>
14 years, 6 months
- 1
- 0
teiid SVN: r2220 - in trunk/documentation/connector-developer-guide/src/main/docbook/en-US: content and 1 other directory.
by teiid-commits＠lists.jboss.org
Author: rareddy
Date: 2010-06-10 20:22:28 -0400 (Thu, 10 Jun 2010)
New Revision: 2220
Added:
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml
Removed:
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml
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/content/connector-api.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml
Log:
TEIID-315: Adding the updated chapters for the extending the JDBC Translator.
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-10 23:14:14 UTC (rev 2219)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-11 00:22:28 UTC (rev 2220)
@@ -51,7 +51,7 @@
<xi:include href="content/command-language.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/lob-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/extending-jdbc-connector.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/jdbc-translator-examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-10 23:14:14 UTC (rev 2219)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-11 00:22:28 UTC (rev 2220)
@@ -321,7 +321,7 @@
</sect2>
</sect1>
- <sect1>
+ <sect1 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
@@ -353,7 +353,7 @@
available properties in configuration for this Translator for tooling and Admin API.</para>
</sect1>
- <sect1>
+ <sect1 id="translator_deploy">
<title>Deployment</title>
<para>Copy the JAR file that defines the Translator into "deploy" directory of the JBoss AS's chosen profile, and
Translator will be deployed automatically. There is no restriction that, JBoss AS need to be restarted. However, if your Translator
Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml 2010-06-10 23:14:14 UTC (rev 2219)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml 2010-06-11 00:22:28 UTC (rev 2220)
@@ -1,212 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="examples">
- <title>JDBC Extension Examples</title>
- <para>This chapter contains a series of examples showing how to extend the JDBC Connector for different common scenarios. </para>
- <sect1>
- <title>Adding Support for a Scalar Function</title>
- <sect2>
- <title>Overview</title>
- <para>For this example we consider how a connector might provide support for accepting a function supported by MetaMatrix. See the following section for adding support for a new function unknown to MetaMatrix. 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 the steps in supporting a new scalar function:</para>
- <orderedlist>
- <listitem>
- <para>Modify the capabilities class to declare support for the function (REQUIRED)</para>
- </listitem>
- <listitem>
- <para>Implement a FunctionModifier to change how a function is translated (OPTIONAL)</para>
- </listitem>
- <listitem>
- <para>Implement a SQLTranslator extension and register the new function modifier (OPTIONAL)</para>
- </listitem>
- </orderedlist>
- <para>The capabilities class has a method getSupportedFunctions() that declares all the scalar functions that can be supported by the connector. To add support for a new function, extend an existing capabilities class (like the base JDBC class JDBCCapabilities or the provided base class in the Connector API, BasicConnectorCapabilities). </para>
- <para>Below is an example of an extended capabilities class to add support for the “abs” absolute value function:</para>
- <programlisting><![CDATA[
- package my.connector;
-
- import java.util.ArrayList;
- import java.util.List;
- import com.metamatrix.connector.jdbc.JDBCCapabilities;
-
- public class ExtendedCapabilities extends JDBCCapabilities {
- public List getSupportedFunctions() {
- List supportedFunctions = new ArrayList();
- supportedFunctions.addAll(super.getSupportedFunctions());
- supportedFunctions.add("ABS");
- return supportedFunctions;
- }
- }
- ]]></programlisting>
- <para>In general, it is a good idea to call super.getSupportedFunctions() to ensure that you retain any function support provided by the connector you are extending.</para>
- <para>This may be all that is needed to support a MetaMatrix function if the JDBC data source supports the same syntax as MetaMatrix. The built-in SQL translation will translate most functions as: “function(arg1, arg2, …)”.</para>
- </sect2>
- <sect2>
- <title>Using FunctionModifiers</title>
- <para>In some cases you may need to translate the function differently or even insert additional function calls above or below the function being translated. The JDBC Connector provides an interface FunctionModifier and a base class BasicFunctionModifier that can be used to register function translations in a SQLTranslator extension. </para>
- <para>The FunctionModifier interface has two methods: modify and translate. Generally, it is recommended to subclass BasicFunctionModifier and override one method or the other, but not both. Use the modify method to modify the function language objects or otherwise change the attributes of the existing function. Use the translate method to change the way the function is represented; this is typically only necessary when using a non-standard function form with special operators or ways of representing parameters. </para>
- <para>Below is an example of using a FunctionModifier to modify the incoming function. This particular example is from the Oracle JDBC Connector and is translating the MetaMatrix function HOUR(ts) which takes a timestamp and returns the hour part into the Oracle equivalent TO_NUMBER(TO_CHAR(ts, ‘HH24’)). It demonstrates the use of the ILanguageFactory to construct new functions and literal values.</para>
- <programlisting><![CDATA[
- package com.metamatrix.connector.jdbc.oracle;
-
- import com.metamatrix.connector.jdbc.extension.FunctionModifier;
- import com.metamatrix.connector.jdbc.extension.impl.BasicFunctionModifier;
- import com.metamatrix.data.language.*;
-
- /**
- * Convert the HOUR function into an equivalent Oracle function.
- * HOUR(ts) --> TO_NUMBER(TO_CHAR(ts, 'HH24'))
- */
- public class HourFunctionModifier extends BasicFunctionModifier implements FunctionModifier {
-
- private ILanguageFactory langFactory;
-
- public HourFunctionModifier(ILanguageFactory langFactory) {
- this.langFactory = langFactory;
- }
-
- public IExpression modify(IFunction function) {
- IExpression[] args = function.getParameters();
-
- IFunction innerFunction = langFactory.createFunction("TO_CHAR",
- new IExpression[] {
- args[0],
- langFactory.createLiteral("HH24", String.class)},
- String.class);
-
- IFunction outerFunction = langFactory.createFunction("TO_NUMBER",
- new IExpression[] { innerFunction },
- Integer.class);
-
- return outerFunction;
- }
- }
- ]]></programlisting>
-
- <para>Below is an example of overriding just the translate method to translate the MOD(a, b) function into an operator form 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[
- package com.metamatrix.connector.jdbc.sybase;
-
- import java.util.ArrayList;
- import java.util.List;
-
- import com.metamatrix.connector.jdbc.extension.FunctionModifier;
- import com.metamatrix.data.language.IExpression;
- import com.metamatrix.data.language.IFunction;
-
- public class ModFunctionModifier implements FunctionModifier {
-
- public IExpression modify(IFunction function) {
- return function;
- }
-
- public List translate(IFunction function) {
- List parts = new ArrayList();
- parts.add("(");
- IExpression[] args = function.getParameters();
- parts.add(args[0]);
- parts.add(" % ");
- parts.add(args[1]);
- parts.add(")");
- return parts;
- }
- }
- ]]></programlisting>
-
- <para>In addition to building your own FunctionModifiers, there are a number of pre-built generic function modifiers that are provided with the connector. </para>
-
- <table frame='all'>
- <title>Connection Factories</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth=".5*"/>
- <thead>
- <row>
- <entry><para>Modifier</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>AliasModifier</para></entry>
- <entry><para>Handles simply renaming a function (“ucase” to “upper” for example)</para></entry>
- </row>
- <row>
- <entry><para>DropFunctionModifier</para></entry>
- <entry><para>Replaces a function with the function’s first argument, effectively dropping the function call if it is unnecessary – useful with unneeded type conversions</para></entry>
- </row>
- <row>
- <entry><para>EscapeSyntaxModifier</para></entry>
- <entry><para>Wraps a function in the standard JDBC escape syntax for functions: {fn xxxx()}</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>To register the function modifiers for your supported functions, you must implement a SQLTranslator extension class. Below is an example that registers some functions.</para>
- <programlisting><![CDATA[
- package my.connector;
-
- import java.util.HashMap;
- import java.util.Map;
-
- import com.metamatrix.connector.jdbc.extension.impl.BasicSQLTranslator;
- import com.metamatrix.data.api.ConnectorEnvironment;
- import com.metamatrix.data.exception.ConnectorException;
- import com.metamatrix.data.metadata.runtime.RuntimeMetadata;
-
- public class ExtendedSQLTranslator extends BasicSQLTranslator {
-
- private Map modifiers;
-
- public void initialize(ConnectorEnvironment env, RuntimeMetadata metadata)
- throws ConnectorException {
-
- super.initialize(env, metadata);
-
- modifiers = new HashMap(super.getFunctionModifiers());
- modifiers.put("abs", new MyAbsModifier());
- modifiers.put("concat", new AliasModifier(“concat2”));
- }
-
- public Map getFunctionModifiers() {
- return this.modifiers;
- }
- }
- ]]></programlisting>
- <para>Support for the two functions being registered (“abs” and “concat”) must be declared in the capabilities class as well. Functions that do not have modifiers registered will be translated as usual. In this example, no attempt is made to add to the list of modifiers for the parent class as it does not register any modifiers. However, if you are extending an existing SQLTranslator, you may need to take this into account to add support rather than replace those modifiers defined by the parent class.</para>
- </sect2>
- </sect1>
- <sect1>
- <title>Pushdown Scalar Functions</title>
- <para>“Pushdown” scalar functions are special in that they are functions new to MetaMatrix that can be “pushed down” to the connector. Implementing support for a pushdown scalar function is identical to implementing support for a standard MetaMatrix function except that the function must be declared to MetaMatrix as such. This allows MetaMatrix to properly parse and resolve queries using the pushdown function.</para>
- <para>Pushdown scalar functions are modeled as user-defined functions with a special attribute. They differ from normal user-defined functions in that no code is provided and the MetaMatrix engine does not how to execute the function. Pushdown functions typically must be passed to the connector for evaluation. User-defined scalar functions have a special pushdown attribute that should be set to “Required” when modeling a pushdown function. </para>
- <para>For more information on modeling user-defined scalar functions, see the MetaMatrix Custom Scalar Functions Tutorial.</para>
- </sect1>
-
- <sect1>
- <title>Connection Pool Test Queries</title>
- <para>The JDBCSourceConnectionFactory provides a method createConnectionStrategy() that allows subclasses to provide a custom implementation of the ConnectionStrategy interface. The ConnectionStrategy interface provides a means to check a JDBC Connection for whether it is alive or dead. If no ConnectionStrategy is specified by returning null (the default), then the Connection.isClosed() method is used to check this. </para>
- <para>However, the isClosed() method does not actively test the connection to the database in most JDBC drivers. By providing an instance of the ConnectionQueryStrategy, you can cause a test query to be executed against the data source instead. </para>
- <para>Below is an example from the DB2 Connector that creates a custom connection factory that uses a DB2-specific test query to test connection liveliness:</para>
-
- <programlisting><![CDATA[
- package com.metamatrix.connector.jdbc.db2;
-
- import com.metamatrix.connector.jdbc.ConnectionQueryStrategy;
- import com.metamatrix.connector.jdbc.ConnectionStrategy;
- import com.metamatrix.connector.jdbc.JDBCSingleIdentityConnectionFactory;
-
- public class DB2SingleIdentityConnectionFactory extends JDBCSingleIdentityConnectionFactory{
- private String queryTest = "Select 'x' from sysibm.systables where 1 = 2";
-
- protected ConnectionStrategy createConnectionStrategy() {
- return new ConnectionQueryStrategy(queryTest,
- this.sourceConnectionTestInterval);
- }
- }
- ]]></programlisting>
-
- <para>It is recommended that you for any custom JDBC Connector you should implement a custom connection factory extension as this will allow the pool to better manage connections and detect data source failures accurately.</para>
- </sect1>
-</chapter>
\ No newline at end of file
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml 2010-06-10 23:14:14 UTC (rev 2219)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/extending-jdbc-connector.xml 2010-06-11 00:22:28 UTC (rev 2220)
@@ -2,47 +2,38 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="extendingjdbc">
<title>Extending the JDBC Connector</title>
- <para>The JDBC Connector can be extended to handle new JDBC drivers and database versions. This chapter outlines the process by which a customer or consultant can modify the behavior of the JDBC Connector for a new source</para>
+ <para>The JDBC Connector can be extended to handle new JDBC drivers and database versions. This chapter
+ outlines the process by which a user can modify the behavior of the JDBC Connector for a new source</para>
<sect1>
<title>Extension Interfaces</title>
- <para>The JDBC Connector provides four extension interfaces that can be used to customize its behavior. Activate an extension by implementing the appropriate interface and specifying the implementation class name in the appropriate connector binding property.</para>
- <para>The JDBC Connector loads each of the implementations of these interfaces via reflection and requires that each of these classes have a no-argument constructor. Each extension class will be loaded exactly once and use for the life of a connector binding. Connector bindings never share instances of the extension classes.</para>
- <para>This table summarizes the available extension points and their purpose. Following the table is a more detailed look at each extension type.</para>
+ <para>To design JDBC Translator for any RDMS that are not already provided by the Teiid, extend the
+ <emphasis>org.teiid.translator.jdbc.JDBCExecutionFactory</emphasis> class in the "translator-jdbc" module. There
+ are three types of methods that you can override from the base class to define the behavior of the Translator.</para>
<table frame='all'>
- <title>Extension Interfaces</title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <title>Extension methods</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth=".5*"/>
- <colspec colname='c3' colwidth="2*"/>
+ <colspec colname='c2' colwidth="2*"/>
<thead>
<row>
<entry><para>Extension</para></entry>
- <entry><para>Connector Property</para></entry>
<entry><para>Purpose</para></entry>
</row>
</thead>
<tbody>
<row>
- <entry><para>Connection Factory</para></entry>
- <entry><para>ExtensionConnectionFactoryClass</para></entry>
- <entry><para>Customize connection creation and pooling.</para></entry>
- </row>
- <row>
- <entry><para>Connector Capabilities</para></entry>
- <entry><para>ExtensionCapabilityClass</para></entry>
+ <entry><para>Translator Capabilities</para></entry>
<entry><para>Specify the SQL syntax and functions the source supports.</para></entry>
</row>
<row>
<entry><para>SQL Translator</para></entry>
- <entry><para>ExtensionSQLTranslationClass</para></entry>
<entry><para>Customize what SQL syntax is used, how source-specific functions are supported, how procedures are executed.</para></entry>
</row>
<row>
<entry><para>Results Translator</para></entry>
- <entry><para>ExtensionResultsTranslationClass</para></entry>
<entry><para>Customize how results are retrieved from JDBC and translated.</para></entry>
</row>
</tbody>
@@ -50,78 +41,22 @@
</table>
<sect2>
- <title>Connection Factory Extension</title>
- <para>The Connection Factory extension can be used to plug in a new factory for creating JDBC Connection objects. The factory class is used within the JDBC connection pool and also controls how connections are pooled and maintained. The Connection Factory implementation class is constructed once and reused throughout the life of the connector.</para>
- <para>The interface to implement is the standard connection factory interface from the Connector API connection pool utility: com.metamatrix.data.pool.SourceConnectionFactory. This interface and its implementation are described in detail in the Connector Developer’s Guide chapter on connection pooling. </para>
- <para>However, the JDBC Connector provides a number of useful abstract implementations that can make the implementation somewhat easier:</para>
-
- <table frame='all'>
- <title>Connection Factories</title>
- <tgroup cols='4' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth=".5*"/>
- <colspec colname='c3' colwidth="2*"/>
- <colspec colname='c4' colwidth="2*"/>
- <thead>
- <row>
- <entry><para>Class</para></entry>
- <entry><para>Pooling</para></entry>
- <entry><para>Connection Type</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>SourceConnection Factory</para></entry>
- <entry><para>Depends on implementation</para></entry>
- <entry><para>Depends on implementation</para></entry>
- <entry><para>This is the basic interface – implementing at this level gives you complete freedom to create connections and control pooling in whatever way necessary.</para></entry>
- </row>
- <row>
- <entry><para>JDBCSource ConnectionFactory</para></entry>
- <entry><para>Depends on implementation</para></entry>
- <entry><para>Depends on implementation</para></entry>
- <entry><para>Adds JDBC-specific facilities for connection events, interpreting transaction isolation levels, strategies for determing whether connection is alive, etc.</para></entry>
- </row>
- <row>
- <entry><para>JDBCSingleIdentity ConnectionFactory</para></entry>
- <entry><para>Create a single connection pool for all connections in a connector binding using the connector binding connection properties.</para></entry>
- <entry><para>DriverManager</para></entry>
- <entry><para>Uses a single pool (the most common usage) and DriverManager to obtain connections.</para></entry>
- </row>
- <row>
- <entry><para>JDBCSingleIdentity DSConnectionFactory</para></entry>
- <entry><para>Create a single connection pool for all connections in a connector binding using the connector binding connection properties.</para></entry>
- <entry><para>DataSource</para></entry>
- <entry><para>Uses a single pool (the most common usage) and a DataSource to obtain connections.</para></entry>
- </row>
- <row>
- <entry><para>JDBCUserIdentity ConnectionFactory</para></entry>
- <entry><para>Create one pool per MetaMatrix user. Subclasses must determine how to obtain each user’s authentication information from the connector properties or trusted payloads.</para></entry>
- <entry><para>DriverManager</para></entry>
- <entry><para>Uses a per-user pool when pooling connections.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>For more information on how to subclass and use these abstract classes, see the examples later in this chapter.</para>
+ <title>Translator 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>
+
+ <para>The most common example is adding
+ support for a scalar function – this requires both declaring that the translator has the capability
+ to execute the function and often modifying the SQL Translator to translate the function appropriately for the source.</para>
+ <para>Another common example is turning off unsupported SQL capabilities (such as outer joins or subqueries)
+ for less sophisticated JDBC sources. </para>
</sect2>
-
- <sect2>
- <title>Connector Capabilities Extension</title>
- <para>This extension must implement the com.metamatrix.data.api.ConnectorCapabilities interface, which is the standard Connector API interface for describing connector capabilities. </para>
- <para>It is strongly recommended that any implementation of the ConnectorCapabilities interface should subclass the JDBC version com.metamatrix.connector.jdbc.extension.JDBCCapabilities or minimally, the com.metamatrix.data.basic.BasicConnectorCapabilities base class. Subclassing these will protect custom implementations from breaking when new capabilities are added to the API. </para>
- <para>This extension often must be modified in tandem with the SQL Translation Extension to modify the capabilities of the connector. The most common example is adding support for a scalar function – this requires both declaring that the connector has the capability to execute the function and often modifying the SQL Translator to translate the function appropriately for the source.</para>
- <para>Another common example is turning off unsupported SQL capabilities (such as outer joins or subqueries) for less sophisticated JDBC sources. </para>
- </sect2>
<sect2>
<title>SQL Translation Extension</title>
- <para>The com.metamatrix.connector.jdbc.extension.SQLTranslator interface defines this extension. It provides ways to modify the command entering the JDBC Connector (in object form) before it is sent to the JDBC driver (as an SQL string). The JDBC Connector defines a base class that should be subclassed when implementing this extension</para>
+ <para>It provides ways to modify the command entering the JDBC Connector (in object form) before it is sent to the
+ JDBC driver (as an SQL string).</para>
- <para><emphasis>com.metamatrix.connector.jdbc.extension.impl.BasicSQLTranslator</emphasis></para>
-
- <para>The SQLTranslator implementation class is constructed once and reused throughout the life of the connector, so it must not maintain any query-specific state. </para>
<para>Common functions that the SQLTranslator can perform are:</para>
<orderedlist>
@@ -140,7 +75,9 @@
<sect2>
<title>Results Translation Extension</title>
- <para>The com.metamatrix.connector.jdbc.extension.ResultsTranslator interface defines ways to modify the results as they are read and returned from the JDBC driver to the MetaMatrix Server. The ResultsTranslator implementation class is constructed once and reused throughout the life of the connector, so it should generally not maintain any query-specific state. Common functions that the ResultsTranslator can perform are:</para>
+ <para>This defines ways to modify the results
+ as they are read and returned from the JDBC driver to the Teiid Server. Common functions that the
+ ResultsTranslator can perform are:</para>
<orderedlist>
<listitem>
<para>Execute a stored procedure against the driver</para>
@@ -168,62 +105,17 @@
<sect1>
<title>Developing Extensions</title>
- <para>When developing a new JDBC Connector extension, you should start with the development environment used to develop any connector, as defined in the Connector Developer’s Guide. Standard connector development requires the inclusion of the following jar: </para>
- <orderedlist>
- <listitem>
- <para>metamatrix-cdk.jar – This jar contains the complete environment needed for developing custom connectors. It can be found in the MetaMatrix Tools kit.</para>
- </listitem>
- <listitem>
- <para>jdbcconn.jar – The JDBC Connector jar, which can be found in the MetaMatrix Server’s installation directory under SERVER\config\extensions or exported from the pre-installed extension modules in the MetaMatrix Console.</para>
- </listitem>
- <listitem>
- <para>MetaMatrixLicense.xml – A valid license for the MetaMatrix JDBC Connector. Your classpath should include a directory containing this file. </para>
- </listitem>
- <listitem>
- <para>MJjdbc.jar – OPTIONAL – If extending an existing MetaMatrix JDBC Connector for access to Oracle, SQL Server, DB2, or Sybase, you may need this jar that contains the actual JDBC drivers for those sources.</para>
- </listitem>
- </orderedlist>
+ <para>When developing a new JDBC Translator extension, you should start with the development environment used to develop
+ any translator, as defined in the Translator Developer’s Guide.</para>
</sect1>
<sect1>
<title>Installing Extensions</title>
- <para>Once you have developed an extension to the JDBC Connector, you must install it into the MetaMatrix Server. This process involves creating and installing a Connector Archive File (CAF). Refer to the Connector Developer’s Guide for instructions on creating and installing CAF files.</para>
-
- <sect2>
- <title>Connector Archive File Contents</title>
- <para>When creating your Connector Archive File, you need to include the following jars:</para>
- <orderedlist>
- <listitem>
- <para>jdbcconn.jar (described above) – This contains the base JDBC Connector code.</para>
- </listitem>
- <listitem>
- <para>JDBC drivers – Any drivers needed to access the data source must be included. If you are extending the MetaMatrix JDBC Connector for Oracle, SQL Server, DB2, or Sybase, you will need to include MJjdbc.jar.</para>
- </listitem>
- <listitem>
- <para>Connector jars – Any custom code that extends the JDBC Connector must be compiled and placed in a JAR file for inclusion in the CAF.</para>
- </listitem>
- <listitem>
- <para>External libraries – Any additional JAR files that are needed by your connector must be included.</para>
- </listitem>
- <listitem>
- <para>Other JDBC jars – OPTIONAL – If extending an existing MetaMatrix JDBC Connector other than those whose drivers are found in MJjdbc.jar (see list above), you will need the JDBC jar provided by that vendor. For example to extend the MySQL connector you would need their mysql-connector-java-5.1.5-bin.jar (5.1.5 is the version number and will vary).</para>
- </listitem>
- </orderedlist>
- </sect2>
-
- <sect2>
- <title>Connector Type Definition</title>
- <para>In addition to the JAR files, you will need to create a Connector Type Definition file as described in the Connector Developer’s Guide. This Connector Type Definition file (.cdk file extension) is an XML file describing the properties needed by your JDBC Connector. </para>
- <para>Typically, the easiest way to create a new Connector Type Definition file to extend the JDBC Connector is to export the JDBC Connector Type from the MetaMatrix Console and modify it. When doing this, you will need to modify the following items:</para>
- <orderedlist>
- <listitem>
- <para>ComponentType Name – name your Connector Type</para>
- </listitem>
- <listitem>
- <para>ComponentType SuperComponent – should be an existing Connector Type such as “JDBC Connector”. If you are extending an existing connector type, that should be specified as the SuperComponent</para>
- </listitem>
- </orderedlist>
- <para>Property value defaults – each property’s default value should be reviewed and updated. In particular the extension class properties should be updated to activate your extension classes.</para>
- </sect2>
- </sect1>
+ <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
+ 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>
+ </sect1>
</chapter>
\ No newline at end of file
Copied: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml (from rev 2217, trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/examples.xml)
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml (rev 0)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml 2010-06-11 00:22:28 UTC (rev 2220)
@@ -0,0 +1,183 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="examples">
+ <title>JDBC Extension Examples</title>
+ <para>This chapter contains a series of examples showing how to extend the JDBC Connector for different common scenarios. </para>
+ <sect1>
+ <title>Adding Support for a Scalar Function</title>
+ <sect2>
+ <title>Overview</title>
+ <para>For this example we consider how a translator might provide support for accepting
+ a function supported by Teiid. See the following section for adding support for a new
+ function unknown 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 the steps in supporting a new scalar function:</para>
+ <orderedlist>
+ <listitem>
+ <para>Override the capabilities method to declare support for the function (REQUIRED)</para>
+ </listitem>
+ <listitem>
+ <para>Implement a FunctionModifier to change how a function is translated (OPTIONAL)</para>
+ </listitem>
+ <listitem>
+ <para>Implement a SQLTranslator extension and register the new function modifier (OPTIONAL)</para>
+ </listitem>
+ </orderedlist>
+ <para>The capabilities class has a method getSupportedFunctions() that declares all the scalar functions that can be supported by the connector. To add support for a new function, extend an existing capabilities class (like the base JDBC class JDBCCapabilities or the provided base class in the Connector API, BasicConnectorCapabilities). </para>
+ <para>Below is an example of an extended capabilities class to add support for the “abs” absolute value function:</para>
+ <programlisting><![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;
+ }
+ }
+ ]]></programlisting>
+ <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>
+ </sect2>
+ <sect2>
+ <title>Using FunctionModifiers</title>
+ <para>In some cases you may need to translate the function differently or even insert
+ additional function calls above or below the function being translated. The JDBC translator provides
+ an abstract class <emphasis>FunctionModifier</emphasis> can be used to register function
+ translations in a SQLTranslator extension. </para>
+
+ <para>The FunctionModifier has method called "translate". Generally, it is recommended
+ to subclass FunctionModifier and override the method.
+ Use the translate method to change the way the function is represented;
+ this is typically only necessary when using a non-standard function form with special operators or
+ ways of representing parameters. </para>
+
+ <para>Below is an example of overriding just the translate method to translate the MOD(a, b) function into an operator form 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>
+
+ <para>You can also extend the <emphasis>AliasModifier</emphasis> that defines a method called "modify"
+ using which you can modify in coming function from Teiid server into some thing that is source specific.</para>
+
+ <para>Below is an example of using a AliasFunctionModifier to modify the incoming function. This particular
+ example is from the Oracle JDBC Translator and is translating the Teiid function HOUR(ts) which takes a
+ timestamp and returns the hour part into the Oracle equivalent TO_NUMBER(TO_CHAR(ts, ‘HH24’)).
+ It demonstrates the use of the LanguageFactory to construct new functions and literal values.</para>
+ <programlisting><![CDATA[
+ /**
+ * Convert the HOUR function into an equivalent Oracle function.
+ * HOUR(ts) --> TO_NUMBER(TO_CHAR(ts, 'HH24'))
+ */
+ public class HourFunctionModifier extends AliasFunctionModifier {
+
+ private LanguageFactory langFactory;
+
+ public HourFunctionModifier(LanguageFactory langFactory) {
+ this.langFactory = langFactory;
+ }
+
+ public Expression modify(Function function) {
+ Expression[] args = function.getParameters();
+
+ Function innerFunction = langFactory.createFunction("TO_CHAR",
+ new Expression[] {
+ args[0],
+ langFactory.createLiteral("HH24", String.class)}, String.class);
+
+ Function outerFunction = langFactory.createFunction("TO_NUMBER",
+ new Expression[] { innerFunction },Integer.class);
+
+ return outerFunction;
+ }
+ }
+ ]]></programlisting>
+
+ <para>In addition to building your own FunctionModifiers, there are a number of pre-built generic
+ function modifiers that are provided with the translator. </para>
+
+ <table frame='all'>
+ <title>Connection Factories</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth=".5*"/>
+ <thead>
+ <row>
+ <entry><para>Modifier</para></entry>
+ <entry><para>Description</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>AliasModifier</para></entry>
+ <entry><para>Handles simply renaming a function (“ucase” to “upper” for example)</para></entry>
+ </row>
+ <row>
+ <entry><para>DropFunctionModifier</para></entry>
+ <entry><para>Replaces a function with the function’s first argument, effectively dropping the function call if it is unnecessary – useful with unneeded type conversions</para></entry>
+ </row>
+ <row>
+ <entry><para>EscapeSyntaxModifier</para></entry>
+ <entry><para>Wraps a function in the standard JDBC escape syntax for functions: {fn xxxx()}</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>To register the function modifiers for your supported functions,
+ you must implement call " public void registerFunctionModifier(String name, FunctionModifier modifier)" method.
+ Below is an example that registers some functions.</para>
+ <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>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>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>Pushdown Scalar Functions</title>
+ <para>“Pushdown” scalar functions are special in that they are functions new to Teiid that can be “pushed down”
+ to the translator. Implementing support for a pushdown scalar function is identical to implementing support
+ for a standard Teiid function except that the function must be declared to Teiid as such. This allows
+ Teiid to properly parse and resolve queries using the pushdown function.</para>
+ <para>Pushdown scalar functions are modeled as user-defined functions with a special attribute.
+ They differ from normal user-defined functions in that no code is provided and the
+ Teiid engine does not how to execute the function. Pushdown functions typically must be passed
+ to the translator for evaluation. User-defined scalar functions have a special pushdown attribute that should be
+ set to “Required” when modeling a pushdown function. </para>
+ <para>For more information on modeling user-defined scalar functions, see the Reference manual.</para>
+ </sect1>
+
+</chapter>
\ No newline at end of file
Property changes on: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/jdbc-translator-examples.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain
14 years, 7 months
- 1
- 0
teiid SVN: r2219 - in trunk: documentation/connector-developer-guide/src/main/docbook/en-US and 1 other directories.
by teiid-commits＠lists.jboss.org
Author: rareddy
Date: 2010-06-10 19:14:14 -0400 (Thu, 10 Jun 2010)
New Revision: 2219
Added:
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml
Removed:
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml
Modified:
trunk/api/src/main/java/org/teiid/resource/spi/BasicConnection.java
trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnection.java
trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnectionFactory.java
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-a.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml
trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml
Log:
TEIID-315: Updating the translator developers guide. Added a section for developing the "resource adapters" into the same guide. Also made few changes to adapter api, to better support XA and security. These changes do not modify any behaviour.
Modified: trunk/api/src/main/java/org/teiid/resource/spi/BasicConnection.java
===================================================================
--- trunk/api/src/main/java/org/teiid/resource/spi/BasicConnection.java 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/api/src/main/java/org/teiid/resource/spi/BasicConnection.java 2010-06-10 23:14:14 UTC (rev 2219)
@@ -28,6 +28,7 @@
import javax.resource.cci.LocalTransaction;
import javax.resource.cci.ResultSetInfo;
import javax.resource.spi.ManagedConnection;
+import javax.transaction.xa.XAResource;
public abstract class BasicConnection implements Connection {
@@ -51,6 +52,10 @@
throw new ResourceException("This operation not supported"); //$NON-NLS-1$
}
+ public XAResource getXAResource() throws ResourceException {
+ return null;
+ }
+
/**
* Tests the connection to see if it is still valid.
* @return
Modified: trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnection.java
===================================================================
--- trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnection.java 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnection.java 2010-06-10 23:14:14 UTC (rev 2219)
@@ -107,7 +107,7 @@
@Override
public XAResource getXAResource() throws ResourceException {
- return null;
+ return this.physicalConnection.getXAResource();
}
@Override
Modified: trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnectionFactory.java
===================================================================
--- trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnectionFactory.java 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/api/src/main/java/org/teiid/resource/spi/BasicManagedConnectionFactory.java 2010-06-10 23:14:14 UTC (rev 2219)
@@ -57,7 +57,10 @@
@Override
public ManagedConnection createManagedConnection(Subject arg0, ConnectionRequestInfo arg1) throws ResourceException {
ConnectionRequestInfoWrapper criw = (ConnectionRequestInfoWrapper)arg1;
- return new BasicManagedConnection(criw.cf.getConnection());
+ ConnectionContext.setSubject(arg0);
+ BasicConnection connection = criw.cf.getConnection();
+ ConnectionContext.setSubject(null);
+ return new BasicManagedConnection(connection);
}
@Override
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/connector_developer_guide.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -32,7 +32,7 @@
<bookinfo>
<title>Teiid - Scalable Information Integration</title>
- <subtitle>Teiid Connector Developer's Guide</subtitle>
+ <subtitle>Teiid Translator and Resource Adapter Developer's Guide</subtitle>
<releaseinfo>&versionNumber;</releaseinfo>
<productnumber>&versionNumber;</productnumber>
<issuenum>1</issuenum>
@@ -46,10 +46,9 @@
<toc/>
<xi:include href="content/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/develop-adapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/connector-api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/command-language.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/connector-deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="content/connection-pooling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/lob-support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/extending-jdbc-connector.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-a.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -1,45 +1,58 @@
<appendix id="appendix_a">
- <title>Connector Type Definition Template</title>
- <para> This appendix contains an example of the Connector Type Definition file that can be used as a template
- when creating a new Connector Type Definition.</para>
+ <title>ra.xml file Template</title>
+ <para> This appendix contains an example of the ra.xml file that can be used as a template
+ when creating a new Connector.</para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
-<ConfigurationDocument>
- <Header>
- <ApplicationCreatedBy>Connector Development Kit</ApplicationCreatedBy>
- <ApplicationVersionCreatedBy>4.0:1681</ApplicationVersionCreatedBy>
- <UserCreatedBy>MetaMatrixAdmin</UserCreatedBy>
- <DocumentTypeVersion>1.0</DocumentTypeVersion>
- <MetaMatrixSystemVersion>4.0</MetaMatrixSystemVersion>
- <Time>2008-01-30T15:22:05.296-06:00</Time>
- </Header>
- <ComponentTypes>
- <ComponentType Name="My Connector" ComponentTypeCode="2" Deployable="true" Deprecated="false" Monitorable="false" SuperComponentType="Connector" ParentComponentType="Connectors">
- <!-- Required by Connector API -->
- <ComponentTypeDefn Deprecated="false">
- <PropertyDefinition Name="ConnectorClass" DisplayName="Connector Class" ShortDescription="" DefaultValue="com.mycode.Connector" IsRequired="true" IsMasked="false" IsModifiable="false" />
- </ComponentTypeDefn>
- <ComponentTypeDefn Deprecated="false">
- <PropertyDefinition Name="ConnectorClassPath" DisplayName="Class Path" ShortDescription="" DefaultValue="extensionjar:mycode.jar" IsRequired="true" IsMasked="false" />
- </ComponentTypeDefn>
- <!-- Example properties - replace with custom properties -->
- <ComponentTypeDefn Deprecated="false">
- <PropertyDefinition Name="ExampleOptional" DisplayName="Example Optional Property" ShortDescription="This property is optional due to not being marked as IsRequired" IsMasked="false" />
- </ComponentTypeDefn>
- <ComponentTypeDefn Deprecated="false">
- <PropertyDefinition Name="ExampleDefaultValue" DisplayName="Example Default Value Property" ShortDescription="This property has a default value" DefaultValue="Default value" IsRequired="true" IsMasked="false" />
- </ComponentTypeDefn>
- <ComponentTypeDefn Deprecated="false">
- <PropertyDefinition Name="ExampleEncrypted" DisplayName="Example Encrypted Property" ShortDescription="This property is encrypted in storage due to Masked=true" IsRequired="true" IsMasked="true" />
- </ComponentTypeDefn>
+<connector xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
+ http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"
+ version="1.5">
- <ChangeHistory>
- <Property Name="LastChangedBy">ConfigurationStartup</Property>
- <Property Name="CreatedBy">ConfigurationStartup</Property>
- </ChangeHistory>
- </ComponentType>
- </ComponentTypes>
-</ConfigurationDocument>
+ <vendor-name>${comapany-name}</vendor-name>
+ <eis-type>${type-of-connector}</eis-type>
+ <resourceadapter-version>1.0</resourceadapter-version>
+ <license>
+ <description>
+ ${license text}
+ </description>
+ <license-required>true</license-required>
+ </license>
+ <resourceadapter>
+ <resourceadapter-class>org.teiid.resource.spi.BasicResourceAdapter</resourceadapter-class>
+
+ <outbound-resourceadapter>
+ <connection-definition>
+ <managedconnectionfactory-class>${connection-factory-class}</managedconnectionfactory-class>
+
+ <!-- repeat for every configuration property -->
+ <config-property>
+ <description>{$display:"Invocation Type",$description:"Service Invocation type (HTTP or SOAP)", $allowed="HTTP_GET, HTTP_POST, SOAP11, SOAP12", $required="true", $defaultValue="SOAP12"}</description>
+ <config-property-name>${property-name}</config-property-name>
+ <config-property-type>${property-type}</config-property-type>
+ <config-property-value>${optioal-property-value}</config-property-value>
+ </config-property>
+
+ <!-- use the below as is if you used the Connection Factory interface -->
+
+ <connectionfactory-interface>javax.resource.cci.ConnectionFactory</connectionfactory-interface>
+ <connectionfactory-impl-class>org.teiid.resource.spi.WrappedConnectionFactory</connectionfactory-impl-class>
+ <connection-interface>javax.resource.cci.Connection</connection-interface>
+ <connection-impl-class>org.teiid.resource.spi.WrappedConnection</connection-impl-class>
+
+ </connection-definition>
+
+ <transaction-support>NoTransaction</transaction-support>
+
+ <authentication-mechanism>
+ <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
+ <credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface>
+ </authentication-mechanism>
+ <reauthentication-support>false</reauthentication-support>
+ </outbound-resourceadapter>
+ </resourceadapter>
+</connector>
]]></programlisting>
</appendix>
\ No newline at end of file
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/command-language.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -8,28 +8,34 @@
<sect1>
<title>Language Interfaces</title>
<para>
- Teiid sends commands to your connector in object form. The interfaces
- for these objects are all defined in the org.teiid.connector.language
+ Teiid sends commands to your Translator in object form. The interfaces
+ for these objects are all defined in the "org.teiid.language"
package. These interfaces can be combined to represent any possible
- command that Teiid may send to the connector. However, it is possible
- to notify Teiid that your connector can only accept certain kinds of
- commands via the ConnectorCapabilities class. See the section on using
- <link linkend="connector_capabilities">Connector Capabilities</link>
+ command that Teiid may send to the Translator. However, it is possible
+ to notify Teiid that your Translator can only accept certain kinds of
+ commands via the capabilities defined on the "ExecutionFactory" class. See the section on using
+ <link linkend="translator_capabilities">Translator Capabilities</link>
for more information.
</para>
- <para>The language interfaces all extend from the ILanguageObject interface.
+ <para>The language interfaces all extend from the <emphasis>LanguageObject</emphasis> interface.
Language objects should be thought of as a tree where each node is a
language object that has zero or more child language objects of types
that are dependent on the current node.</para>
- <para>All commands sent to your connector are in the form of these
- language trees, where the root of the tree is a subclass of ICommand.
- ICommand has several sub-interfaces, namely: IQueryCommand, IInsert, IUpdate,
- IDelete, IBatchedUpdate, and IProcedure.
- Important components of
- these commands are expressions, criteria, and
- joins, which are examined
- in closer detail below. Also see the
- <ulink url="&javaDocUrl;">Teiid JavaDocs</ulink>
+ <para>All commands sent to your Translator are in the form of these
+ language trees, where the root of the tree is a subclass of <emphasis>Command</emphasis>.
+ Command has several sub-interfaces, namely:
+
+ <itemizedlist>
+ <listitem><para><code>QueryExpression</code></para></listitem>
+ <listitem><para><code>Insert</code></para></listitem>
+ <listitem><para><code>Update</code></para></listitem>
+ <listitem><para><code>Delete</code></para></listitem>
+ <listitem><para><code>BatchedUpdate</code></para></listitem>
+ <listitem><para><code>Call</code></para></listitem>
+ </itemizedlist>
+
+ Important components of these commands are expressions, criteria, and joins, which are examined
+ in closer detail below. Also see the <ulink url="&javaDocUrl;">Teiid JavaDocs</ulink>
for more on the classes and interfaces described here.
</para>
<sect2>
@@ -43,45 +49,44 @@
<itemizedlist>
<listitem>
<para>
- <code>IExpression</code>
+ <code>Expression</code>
– base expression interface
</para>
</listitem>
<listitem>
<para>
- <code>IElement</code>
+ <code>Element</code>
– represents an element in the data source
</para>
</listitem>
<listitem>
<para>
- <code>ILiteral</code>
+ <code>Literal</code>
– represents a literal scalar value, but may also be multi-valued in
the case of bulk updates.
</para>
</listitem>
<listitem>
<para>
- <code>IFunction</code>
- – represents a scalar function with parameters that are also
- IExpressions
+ <code>Function</code>
+ – represents a scalar function with parameters that are also Expressions
</para>
</listitem>
<listitem>
<para>
- <code>IAggregate</code>
+ <code>Aggregate</code>
– represents an aggregate function which holds a single expression
</para>
</listitem>
<listitem>
<para>
- <code>IScalarSubquery</code>
+ <code>ScalarSubquery</code>
– represents a subquery that returns a single value
</para>
</listitem>
<listitem>
<para>
- <code>ISearchedCaseExpression</code>
+ <code>SearchedCase, SearchedWhenClause</code>
– represents a searched CASE expression. The searched CASE
expression evaluates the criteria in WHEN clauses till one evaluates
to TRUE, then evaluates the associated THEN clause.
@@ -90,110 +95,111 @@
</itemizedlist>
</sect2>
<sect2>
- <title>Criteria</title>
+ <title>Condition</title>
<para>A criteria is a combination of expressions and operators that
evaluates to true, false, or unknown. Criteria are most commonly used in the
WHERE or HAVING clauses.</para>
<itemizedlist>
- <listitem><para><code>ICriteria</code> – the base criteria interface</para></listitem>
- <listitem><para><code>ILogicalCriteria</code> – used to logically combine other criteria</para></listitem>
- <listitem><para><code>INotCriteria</code> – used to NOT another criteria</para></listitem>
- <listitem><para><code>ICompoundCriteria</code> – used to combine other criteria via AND or OR</para></listitem>
- <listitem><para><code>IPredicateCriteria</code> – a predicate that evaluates to true, false, or unknown</para></listitem>
- <listitem><para><code>ISubuqeryCompareCriteria</code> – represents a comparison criteria with a subquery including a quantifier such as SOME or ALL</para></listitem>
- <listitem><para><code>ICompareCriteria</code> – represents a comparison criteria with =, >, <, etc.</para></listitem>
- <listitem><para><code>IBaseInCriteria</code> – base class for an IN criteria</para></listitem>
- <listitem><para><code>IInCriteria</code> – represents an IN criteria that has a set of expressions for values</para></listitem>
- <listitem><para><code>ISubqueryInCriteria</code> – represents an IN criteria that uses a subquery to produce the value set</para></listitem>
- <listitem><para><code>IIsNullCriteria</code> – represents an IS NULL criteria</para></listitem>
- <listitem><para><code>IExistsCriteria</code> – represents an EXISTS criteria that determines whether a subquery will return any values</para></listitem>
- <listitem><para><code>ILikeCriteria</code> – represents a LIKE criteria that compares string values</para></listitem>
+ <listitem><para><code>Condition</code> – the base criteria interface</para></listitem>
+ <listitem><para><code>Not</code> – used to NOT another criteria</para></listitem>
+ <listitem><para><code>AndOr</code> – used to combine other criteria via AND or OR</para></listitem>
+ <listitem><para><code>SubuqeryComparison</code> – represents a comparison criteria with a subquery including a quantifier such as SOME or ALL</para></listitem>
+ <listitem><para><code>Comparison</code> – represents a comparison criteria with =, >, <, etc.</para></listitem>
+ <listitem><para><code>BaseInCondition</code> – base class for an IN criteria</para></listitem>
+ <listitem><para><code>In</code> – represents an IN criteria that has a set of expressions for values</para></listitem>
+ <listitem><para><code>SubqueryIn</code> – represents an IN criteria that uses a subquery to produce the value set</para></listitem>
+ <listitem><para><code>IsNull</code> – represents an IS NULL criteria</para></listitem>
+ <listitem><para><code>Exists</code> – represents an EXISTS criteria that determines whether a subquery will return any values</para></listitem>
+ <listitem><para><code>Like</code> – represents a LIKE criteria that compares string values</para></listitem>
</itemizedlist>
</sect2>
<sect2>
<title>The FROM Clause</title>
- <para>The FROM clause contains a list of IFromItems. Each IFomItem can
- either represent a group or a join between two other IFromItems. This
- allows joins to be composed into a join tree.</para>
+ <para>The FROM clause contains a list of <emphasis>TableReference</emphasis>. </para>
<itemizedlist>
- <listitem><para><code>IGroup</code> – represents a single group</para></listitem>
- <listitem><para><code>IJoin</code> – has a left and right <code>IFromItem</code> and information on the join between the items</para></listitem>
- <listitem><para><code>IInlineView</code> – represents a group defined by an inline <code>IQueryCommand</code></para></listitem>
+ <listitem><para><code>TableReference</code> – represents a single Table</para></listitem>
+ <listitem><para><code>Join</code> – has a left and right <code>TableReference</code> and information on the join between the items</para></listitem>
+ <listitem><para><code>DerivedTable</code> – represents a table defined by an inline <code>QueryExpression</code></para></listitem>
</itemizedlist>
- <para>A list of IFromItems is used by default in the pushdown query
- when no outer joins are used. If an outer join is used anywhere in the
- join tree, there will be a tree of IJoins with a single root. This latter form
- is the ANSI perfered style. If you wish all pushdown queries
- containing joins to be in ANSI style have the
- ConnectorCapability.useAnsiJoin return true. See <link linkend="command_form_capabilities">Command Form Capabilities</link> for more.</para>
+ <para>
+ A list of <emphasis>TableReference</emphasis>
+ are used by default, in the pushdown query
+ when no outer joins are used. If an outer join is used anywhere in the
+ join tree, there will be a tree of
+ <code>Join</code>
+ s with a single root. This latter form
+ is the ANSI perfered style. If you wish all pushdown queries containing joins to be in ANSI style have the
+ capability "useAnsiJoin" return true. See
+ <link linkend="command_form_capabilities">Command Form Capabilities</link>
+ for more information.
+ </para>
</sect2>
<sect2>
- <title>IQueryCommand Structure</title>
- <para>IQueryCommand (refered to in SQL as a Query Expression) is the base for both queries and set queries. It may optionally take an IOrderBy (representing a SQL ORDER BY clause) and a ILimit (represent a SQL LIMIT clause)</para>
- </sect2>
- <sect2>
- <title>IQuery Structure</title>
-
- <para>Each IQuery will have an ISelect describing the expressions
- (typically elements) being selected and an IFrom specifying the group
- or groups being selected from, along with any join information. The
- IQuery may optionally also supply an ICriteria (representing a SQL
- WHERE clause), an IGroupBy (representing a SQL GROUP BY clause), an
- an ICriteria (representing a SQL HAVING clause).</para>
+ <title>QueryExpression Structure</title>
+ <para><emphasis>QueryExpression</emphasis> is the base for both queries and set queries. It may optionally take an
+ <emphasis>OrderBy</emphasis> (representing a SQL ORDER BY clause) and a <emphasis>Limit</emphasis> (represent a SQL LIMIT clause)</para>
</sect2>
<sect2>
- <title>ISetQuery Structure</title>
+ <title>Select Structure</title>
- <para>An ISetQuery represents on of the SQL set operations (UNION,
- INTERSECT, EXCEPT) on two IQueryCommands. The all flag may be set to
- indicate UNION ALL (currently INTERSECT and EXCEPT ALL are not allowed
- in Teiid)</para>
+ <para>Each <emphasis>QueryExpression</emphasis> can be a <emphasis>Select</emphasis> describing the expressions
+ (typically elements) being selected and an <emphasis>TableReference</emphasis> specifying the table
+ or tables being selected from, along with any join information. The
+ <emphasis>Select</emphasis> may optionally also supply an <emphasis>Condition</emphasis> (representing a SQL
+ WHERE clause), an <emphasis>GroupBy</emphasis> (representing a SQL GROUP BY clause), an
+ an <emphasis>Condition</emphasis> (representing a SQL HAVING clause).</para>
</sect2>
+
+ <sect2>
+ <title>SetQuery Structure</title>
+
+ <para>A <emphasis>QueryExpression</emphasis> can also be a <emphasis>SetQuery</emphasis> that represents on of the SQL set operations (UNION,
+ INTERSECT, EXCEPT) on two <emphasis>QueryExpression</emphasis>. The all flag may be set to
+ indicate UNION ALL (currently INTERSECT and EXCEPT ALL are not allowed in Teiid)</para>
+ </sect2>
<sect2>
- <title>IInsert Structure</title>
+ <title>Insert Structure</title>
- <para>Each IInsert will have a single IGroup specifying the group being
- inserted into. It will also a list of
- IElements specifying the columns of the IGroup that are being inserted
- into and an IInsertValueSource, which will either be a list of IExpression (IInsertExpressionValueSource) or an IQueryCommand.</para>
+ <para>Each <emphasis>Insert</emphasis> will have a single <emphasis>NamedTable</emphasis> specifying the table being
+ inserted into. It will also has a list of <emphasis>ColumnReference</emphasis> specifying the columns
+ of the <emphasis>TableReference</emphasis> that are being inserted into. It also has
+ <emphasis>InsertValueSource</emphasis>, which will either be a list of
+ <emphasis>Expression(ExpressionValueSource)</emphasis> or <emphasis>QueryExpression</emphasis></para>
</sect2>
<sect2>
- <title>IUpdate Structure</title>
+ <title>Update Structure</title>
- <para>Each IUpdate will have a single IGroup specifying the group being
- updated. The ISetClauseList contains ISetClause entries that specify
- IElement and IExpression pairs for the update.
- The IUpdate may optionally provide a
- criteria specifying which rows should be updated.</para>
+ <para>Each <emphasis>Update</emphasis> will have a single <emphasis>NamedTable</emphasis> specifying the table being
+ updated and list of <emphasis>SetClause</emphasis> entries that specify <emphasis>ColumnReference</emphasis>
+ and <emphasis>Expression</emphasis> pairs for the update. The Update may optionally provide a criteria
+ <emphasis>Condition</emphasis> specifying which rows should be updated.</para>
</sect2>
<sect2>
- <title>IDelete Structure</title>
+ <title>Delete Structure</title>
- <para>Each IDelete will have a single IGroup specifying the group being
- deleted from. It may also optionally have a criteria specifying which
- rows should be deleted. </para>
+ <para>Each <emphasis>Delete</emphasis> will have a single <emphasis>NamedTable</emphasis> specifying the table being
+ deleted from. It may also optionally have a criteria specifying which rows should be deleted. </para>
</sect2>
<sect2>
- <title>IProcedure Structure</title>
+ <title>Call Structure</title>
- <para>Each IProcedure has zero or more IParameter objects. The
- IParameter objects describe the input parameters, the output result
+ <para>Each <emphasis>Call</emphasis> has zero or more <emphasis>Argument</emphasis> objects. The
+ <emphasis>Argument</emphasis> objects describe the input parameters, the output result
set, and the output parameters. </para>
</sect2>
<sect2>
- <title>IBatchedUpdate Structure </title>
-
- <para>Each IBatchedUpdate has a list of ICommand objects (which must be
- an IInsert, IUpdate, or IDelete) that compose the batch. </para>
+ <title>BatchedUpdates Structure </title>
+ <para>Each <emphasis>BatchedUpdates</emphasis> has a list of <emphasis>Command</emphasis> objects (which must be either
+ <emphasis>Insert</emphasis>, <emphasis>Update</emphasis> or <emphasis>Delete</emphasis>) that compose the batch. </para>
</sect2>
</sect1>
@@ -203,36 +209,36 @@
<sect2>
<title>Data Types</title>
- <para>The Connector API contains an interface TypeFacility that defines data types and provides value translation facilities. </para>
+ <para>The Translator API contains an interface <emphasis>TypeFacility</emphasis> that defines
+ data types and provides value translation facilities. This interface can be obtained from calling "getTypeFacility()"
+ method on the "ExecutionFactory" class.</para>
- <para>This ConnectorEnvironment (provided by Teiid on connector start)
- is a factory to obtain a TypeFacility instance for the connector using
- the getTypeFacility() method.
+ <para>
The TypeFacitlity interface has methods that support data type
transformation and detection of appropriate runtime or JDBC types.
The TypeFacility.RUNTIME_TYPES and TypeFacility.RUNTIME_NAMES
interfaces defines constants for all Teiid runtime data types. All
- IExpression instances define a data type based on this set of types.
- These constants are often needed in understanding or creating
- language interfaces.</para>
+ <emphasis>Expression</emphasis> instances define a data type based on this set of types.
+ These constants are often needed in understanding or creating language interfaces.</para>
</sect2>
<sect2>
<title>Language Manipulation</title>
- <para>In connectors that support a fuller set of capabilities (those
+ <para>In Translators that support a fuller set of capabilities (those
that generally are translating to a language of comparable to SQL),
there is often a need to manipulate or create language interfaces to
move closer to the syntax of choice. Some utilities are provided for
this purpose:</para>
- <para>Similar to the TypeFacility, you can use the ConnectorEnvironment
- to get a reference to the ILanguageFactory instance for your
- connector. This interface is a factory that can be used to create new
+ <para>Similar to the TypeFacility, you can call "getLanguageFactory()" method on
+ the "ExecutionFactory"
+ to get a reference to the <emphasis>LanguageFactory</emphasis> instance for your
+ translator. This interface is a factory that can be used to create new
instances of all the concrete language interface objects. </para>
- <para>Some helpful utilities for working with ICriteria objects are
- provided in the LanguageUtil class. This class has methods to combine
- ICriteria with AND or to break an ICriteria apart based on AND
+ <para>Some helpful utilities for working with <emphasis>Condition</emphasis> objects are
+ provided in the <emphasis>LanguageUtil</emphasis> class. This class has methods to combine
+ <emphasis>Condition</emphasis> with AND or to break an <emphasis>Condition</emphasis> apart based on AND
operators. These utilities are helpful for breaking apart a criteria
- into individual filters that your connector can implement.</para>
+ into individual filters that your translator can implement.</para>
</sect2>
</sect1>
@@ -241,55 +247,50 @@
<para>Teiid uses a library of metadata, known as "runtime metadata” for
each virtual database that is deployed in Teiid. The runtime metadata
is a subset of metadata as defined by models in the Teiid models that
- compose the virtual database. </para>
- <para>Connectors can access runtime metadata by using the interfaces
- defined in org.teiid.connector.metadata.runtime. This package defines
- interfaces representing a MetadataID, a MetadataObject, and ways to
- navigate those IDs and objects.</para>
+ compose the virtual database. While builing your VDB in the Designer, you can define what
+ called "Extension Model", that defines any number of arbitary properties on a model and its objects.
+ At runtime, using this runtime metadata interface, you get access to those set properties defined during the
+ design time, to define/hint any execution behavior. For example, a XML model could define the 'xpath' as
+ one of the property on Column of a Table.</para>
+
+ <para>Translator gets access to the <emphasis>RuntimeMetadata</emphasis> interface at the time of <emphasis>Excecution</emphasis> creation.
+ Translators can access runtime metadata by using the interfaces
+ defined in <emphasis>org.teiid.metadata</emphasis> package. This package defines
+ API representing a Schema, Table, Columns and Procedures, and ways to navigate these objects.</para>
<sect2>
<title>Language Objects</title>
- <para>One language interface, IMetadataReference describes whether a language object has a reference to a MetadataObject. The following interfaces extend IMetadataReference:</para>
+ <para>All the language objects extend <emphasis>AbstractMetadataRecord</emphasis> class</para>
<itemizedlist>
- <listitem><para>IElement</para> - returns an Element MetadataObject</listitem>
- <listitem><para>IGroup</para> - returns a Group MetadataObject</listitem>
- <listitem><para>IProcedure</para> - returns a Procedure MetadataObject</listitem>
- <listitem><para>IParameter</para> - returns a Parameter MetadataObject</listitem>
+ <listitem><para>Column - returns Column metadata record</para></listitem>
+ <listitem><para>Table - returns a Table metadata record</para></listitem>
+ <listitem><para>Procedure - returns a Procedure metadata record</para></listitem>
+ <listitem><para>ProcedureParameter - returns a Procedure Parameter metadata record</para></listitem>
</itemizedlist>
- <para>Once a MetadataObject has been obtained, it is possible to use it metadata about that object or to find other related or objects.</para>
+ <para>Once a metadata record has been obtained, it is possible to use its metadata about that object or to find other related or objects.</para>
</sect2>
<sect2>
<title>Access to Runtime Metadata</title>
- <para>As mentioned in the previous section, a MetadataID is obtained
- from one of the language objects. That MetadataID can then be used
- directly to obtain information about the ID, such as the full name or
- short name. </para>
- <para>The RuntimeMetadata interface is passed in for the creation of an Execution. It provides the ability to look up
- MetadataObjects based on their fully qualified names in the VDB. There are several kinds of
- MetadataObjects and they can be used to find more information about
- the object in runtime metadata. </para>
- <para>Currently, only a subset of the most commonly used runtime
- metadata is available through these interfaces. In the future, more
- complete information will be available.</para>
+ <para>The RuntimeMetadata interface is passed in for the creation of an "Execution". See "createExecution"
+ method on the "ExecutionFactory" class. It provides the ability to look up
+ metadta records based on their fully qualified names in the VDB. There are several kinds of
+ metadata objects and they can be used to find more information about
+ the objects in runtime metadata. </para>
+
- <para><emphasis>Obtaining MetadataObject Properties Example</emphasis></para>
+ <para><emphasis>Obtaining Metadata Properties Example</emphasis></para>
- <para>The process of getting an element's properties is sometimes needed for connector development. For example to get the NameInSource property or all extension properties:</para>
+ <para>The process of getting an Table's properties is sometimes needed for translator development. For example
+ to get the "NameInSource" property or all extension properties:</para>
<programlisting><![CDATA[
-//getting the Group metadata from an IGroup is straight-forward
-IGroup igroup = ... //some group on a command
-Group group = igroup.getMetadataObject();
+//getting the Table metadata from an Table is straight-forward
+Table table = runtimeMetadata.getTable("table-name");
+String contextName = table.getNameInSource();
-//we could also use the runtime metadata
-RuntimeMetadata rm = ... //Obtained from the creation of the Execution
-
-group = rm.getGroup("fully.qualified.name");
-String contextName = group.getNameInSource();
-
//The props will contain extension properties
-Properties props = group.getProperties();
+Properties props = table.getProperties();
]]></programlisting>
</sect2>
@@ -300,8 +301,8 @@
<sect2>
<title>Framework</title>
- <para>The Connector API provides a language visitor framework in the
- org.teiid.connector.visitor.framework package. The framework
+ <para>The API provides a language visitor framework in the
+ <emphasis>org.teiid.language.visitor</emphasis> package. The framework
provides utilities useful in navigating and extracting information
from trees of language objects.</para>
@@ -313,7 +314,7 @@
interface objects and the graph is really a tree rooted at some node.
The provided framework allows for customization of both aspects of
visiting.</para>
- <para>The base LanguageObjectVisitor class defines the visit methods
+ <para>The base <emphasis>AbstractLanguageVisitor</emphasis> class defines the visit methods
for all leaf language interfaces that can exist in the tree. The
LanguageObject interface defines an acceptVisitor() method – this
method will call back on the visit method of the visitor to complete
@@ -321,31 +322,31 @@
AbstractLanguageVisitor. The AbstractLanguageVisitor is just a
visitor shell – it performs no actions when visiting nodes and does
not provide any iteration.</para>
- <para>The HierarchyVisitor provides the basic code for walking a
- language object tree. The HierarchyVisitor performs no action as it
+ <para>The <emphasis>HierarchyVisitor</emphasis> provides the basic code for walking a
+ language object tree. <emphasis>The HierarchyVisitor</emphasis> performs no action as it
walks the tree – it just encapsulates the knowledge of how to walk it.
- If your connector wants to provide a custom iteration that walks the
+ If your translator wants to provide a custom iteration that walks the
objects in a special order (to exclude nodes, include nodes multiple
times, conditionally include nodes, etc) then you must either extend
HierarchyVisitor or build your own iteration visitor. In general,
that is not necessary.</para>
- <para>The DelegatingHierarchyVisitor is a special subclass of the
+ <para>The <emphasis>DelegatingHierarchyVisitor</emphasis> is a special subclass of the
HierarchyVisitor that provides the ability to perform a different
visitor’s processing before and after iteration. This allows users of
this class to implement either pre- or post-order processing based on
the HierarchyVisitor. Two helper methods are provided on
- DelegatingHierarchyVisitor to aid in executing pre- and post-order
+ <emphasis>DelegatingHierarchyVisitor</emphasis> to aid in executing pre- and post-order
visitors. </para>
</sect2>
<sect2>
<title>Provided Visitors</title>
- <para>The SQLStringVisitor is a special visitor that can traverse a
+ <para>The <emphasis>SQLStringVisitor</emphasis> is a special visitor that can traverse a
tree of language interfaces and output the equivalent Teiid SQL. This
visitor can be used to print language objects for debugging and
- logging. The SQLStringVisitor does not use the HierarchyVisitor
+ logging. The <emphasis>SQLStringVisitor</emphasis> does not use the <emphasis>HierarchyVisitor</emphasis>
described in the last section; it provides both iteration and
processing type functionality in a single custom visitor. </para>
- <para>The CollectorVisitor is a handy utility to collect all language
+ <para>The <emphasis>CollectorVisitor</emphasis> is a handy utility to collect all language
objects of a certain type in a tree. Some additional helper methods
exist to do common tasks such as retrieving all elements in a tree,
retrieving all groups in a tree, and so on. </para>
@@ -358,7 +359,7 @@
<para>Create a subclass of AbstractLanguageVisitor. Override any visit
methods needed for your processing. For instance, if you wanted to
count the number of elements in the tree, you need only override the
- visit(IElement) method. Collect any state in local variables and
+ <emphasis>visit(ColumnReference)</emphasis> method. Collect any state in local variables and
provide accessor methods for that state.</para>
<para>Decide whether to use pre-order or post-order iteration. Note
that visitation order is based upon syntax ordering of SQL clauses -
@@ -367,7 +368,7 @@
DelegatingHierarchyVisitor:</para>
<programlisting><![CDATA[
// Get object tree
-ILanguageObject objectTree = …
+LanguageObject objectTree = …
// Create your visitor initialize as necessary
MyVisitor visitor = new MyVisitor();
@@ -380,32 +381,27 @@
]]></programlisting>
</sect2>
</sect1>
- <sect1 id="connector_capabilities">
- <title>Connector Capabilities</title>
- <para>All connectors must return a ConnectorCapabilities class from the
- <code>Connection.getCapabilities()</code> or <code>Connector.getCapabilities()</code> method. This class is used by the
- Connector Manager to determine what kinds of commands the connector is
- capable of executing. A basic implementation of the
- ConnectorCapabilities interface is supplied at
- BasicConnectorCapabilities. This
- capabilities class specifies that the connector does not support any capability. You should extend
- this class and override the necessary methods to specify which
- capabilities your connector supports. </para>
+ <sect1 id="translator_capabilities">
+ <title>Translator Capabilities</title>
+ <para>The <emphasis>ExecutionFactory</emphasis> class defines all the methods that describe the capabilities of a Translator.
+ These are used by the Connector Manager to determine what kinds of commands the translator is
+ capable of executing. A base <emphasis>ExecutionFactory</emphasis> class implements all the basic capabilities, which says
+ your translator does not support any cpabilities. Your extended
+ <emphasis>ExecutionFactory</emphasis> class must override the the necessary methods to specify which
+ capabilities your translator supports. </para>
<sect2>
<title>Capability Scope</title>
<para>
Note that if your capabilities will remain unchanged for the lifetime
- of the connector, you should return them via
- <code>Connector.getCapabilities()</code>
- since the engine will cache them for reuse by all connections to the
- connector. Capabilities returned by the connection will only be cached for the duration of the user request.
+ of the translator, since the engine will cache them for reuse by all instances of that
+ translator. Capabilities based on connection/user are not supported.
</para>
</sect2>
<sect2>
<title>Capabilities</title>
- <para>The following table lists the capabilities that can be specified in the ConnectorCapabilities class.</para>
+ <para>The following table lists the capabilities that can be specified in the <emphasis>ExecutionFactory</emphasis> class.</para>
<table frame='all'>
- <title>Available Connector Capabilities</title>
+ <title>Available Capabilities</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' colwidth="1.5*" />
<colspec colname='c2' colwidth="1*" />
@@ -432,7 +428,7 @@
<para />
</entry>
<entry>
- <para>Connector can support SELECT DISTINCT in queries.</para>
+ <para>Translator can support SELECT DISTINCT in queries.</para>
</entry>
</row>
<row>
@@ -443,44 +439,30 @@
<para />
</entry>
<entry>
- <para>Connector can support SELECT of more than just element references.</para>
+ <para>Translator can support SELECT of more than just column references.</para>
</entry>
</row>
<row>
<entry>
- <para>AliasedGroup</para>
+ <para>AliasedTable</para>
</entry>
<entry>
<para />
</entry>
<entry>
- <para>Connector can support groups in the FROM clause that have an alias.
+ <para>Translator can support Tables in the FROM clause that have an alias.
</para>
</entry>
</row>
<row>
<entry>
- <para>SupportedJoinCriteria</para>
- </entry>
- <entry>
- <para>At least one of the join type supports.</para>
- </entry>
- <entry>
- <para>Returns one of the SupportedJoinCriteria enum types: ANY, THETA,
- EQUI, KEY. KEY is the most restrictive, indicating that the source
- only supports equi-join criteria specified on the primary key of at
- least one of the tables in join.</para>
- </entry>
- </row>
- <row>
- <entry>
<para>InnerJoins</para>
</entry>
<entry>
<para/>
</entry>
<entry>
- <para>Connector can support inner and cross joins</para>
+ <para>Translator can support inner and cross joins</para>
</entry>
</row>
<row>
@@ -491,8 +473,8 @@
<para>AliasedGroups and at least on of the join type supports.</para>
</entry>
<entry>
- <para>Connector can support a self join between two aliased versions of the
- same group.</para>
+ <para>Translator can support a self join between two aliased versions of the
+ same Table.</para>
</entry>
</row>
<row>
@@ -503,7 +485,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support LEFT and RIGHT OUTER JOIN.</para>
+ <para>Translator can support LEFT and RIGHT OUTER JOIN.</para>
</entry>
</row>
<row>
@@ -514,7 +496,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support FULL OUTER JOIN.</para>
+ <para>Translator can support FULL OUTER JOIN.</para>
</entry>
</row>
<row>
@@ -522,10 +504,10 @@
<para>InlineViews</para>
</entry>
<entry>
- <para>AliasedGroup</para>
+ <para>AliasedTable</para>
</entry>
<entry>
- <para>Connector can support a named subquery in the FROM clause.</para>
+ <para>Translator can support a named subquery in the FROM clause.</para>
</entry>
</row>
<row>
@@ -547,7 +529,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support comparison criteria with the operator "=”.</para>
+ <para>Translator can support comparison criteria with the operator "=”.</para>
</entry>
</row>
<row>
@@ -558,7 +540,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support comparison criteria with the operator ">” or "<".</para>
+ <para>Translator can support comparison criteria with the operator ">” or "<".</para>
</entry>
</row>
<row>
@@ -569,7 +551,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support LIKE criteria.</para>
+ <para>Translator can support LIKE criteria.</para>
</entry>
</row>
<row>
@@ -580,7 +562,7 @@
<para>LikeCriteria</para>
</entry>
<entry>
- <para>Connector can support LIKE criteria with an ESCAPE character clause.</para>
+ <para>Translator can support LIKE criteria with an ESCAPE character clause.</para>
</entry>
</row>
<row>
@@ -588,10 +570,10 @@
<para>InCriteria</para>
</entry>
<entry>
- <para/>
+ <para>MaxInCriteria</para>
</entry>
<entry>
- <para>Connector can support IN predicate criteria.</para>
+ <para>Translator can support IN predicate criteria.</para>
</entry>
</row>
<row>
@@ -602,7 +584,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support IN predicate criteria where values are supplied by a
+ <para>Translator can support IN predicate criteria where values are supplied by a
subquery.</para>
</entry>
</row>
@@ -614,7 +596,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support IS NULL predicate criteria.</para>
+ <para>Translator can support IS NULL predicate criteria.</para>
</entry>
</row>
<row>
@@ -625,7 +607,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the OR logical criteria.</para>
+ <para>Translator can support the OR logical criteria.</para>
</entry>
</row>
<row>
@@ -636,7 +618,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the NOT logical criteria. IMPORTANT: This
+ <para>Translator can support the NOT logical criteria. IMPORTANT: This
capability also applies to negation of predicates, such as specifying
IS NOT NULL, "<=" (not ">"), ">=" (not "<"), etc.</para>
</entry>
@@ -649,7 +631,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support EXISTS predicate criteria.</para>
+ <para>Translator can support EXISTS predicate criteria.</para>
</entry>
</row>
<row>
@@ -660,7 +642,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support a quantified comparison criteria using the ALL
+ <para>Translator can support a quantified comparison criteria using the ALL
quantifier.</para>
</entry>
</row>
@@ -672,7 +654,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support a quantified comparison criteria using the SOME or ANY
+ <para>Translator can support a quantified comparison criteria using the SOME or ANY
quantifier.</para>
</entry>
</row>
@@ -684,7 +666,7 @@
<para />
</entry>
<entry>
- <para>Connector can support the ORDER BY clause in queries.</para>
+ <para>Translator can support the ORDER BY clause in queries.</para>
</entry>
</row>
<row>
@@ -695,7 +677,7 @@
<para>OrderBy</para>
</entry>
<entry>
- <para>Connector can support the ORDER BY items that are not directly specified in the select clause.</para>
+ <para>Translator can support the ORDER BY items that are not directly specified in the select clause.</para>
</entry>
</row>
<row>
@@ -706,7 +688,7 @@
<para />
</entry>
<entry>
- <para>Connector can support an explict GROUP BY clause.</para>
+ <para>Translator can support an explict GROUP BY clause.</para>
</entry>
</row>
<row>
@@ -717,7 +699,7 @@
<para>GroupBy</para>
</entry>
<entry>
- <para>Connector can support the HAVING clause.</para>
+ <para>Translator can support the HAVING clause.</para>
</entry>
</row>
<row>
@@ -728,7 +710,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the AVG aggregate function.</para>
+ <para>Translator can support the AVG aggregate function.</para>
</entry>
</row>
<row>
@@ -739,7 +721,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the COUNT aggregate function.</para>
+ <para>Translator can support the COUNT aggregate function.</para>
</entry>
</row>
<row>
@@ -750,7 +732,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the COUNT(*) aggregate function.</para>
+ <para>Translator can support the COUNT(*) aggregate function.</para>
</entry>
</row>
<row>
@@ -761,7 +743,7 @@
<para>At least one of the aggregate functions.</para>
</entry>
<entry>
- <para>Connector can support the keyword DISTINCT inside an aggregate function. This
+ <para>Translator can support the keyword DISTINCT inside an aggregate function. This
keyword indicates that duplicate values within a group of rows will be ignored.</para>
</entry>
</row>
@@ -773,7 +755,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the MAX aggregate function.</para>
+ <para>Translator can support the MAX aggregate function.</para>
</entry>
</row>
<row>
@@ -784,7 +766,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the MIN aggregate function.</para>
+ <para>Translator can support the MIN aggregate function.</para>
</entry>
</row>
<row>
@@ -795,7 +777,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the SUM aggregate function.</para>
+ <para>Translator can support the SUM aggregate function.</para>
</entry>
</row>
<row>
@@ -806,7 +788,7 @@
<para />
</entry>
<entry>
- <para>Connector can support the use of a subquery in a scalar context (wherever an
+ <para>Translator can support the use of a subquery in a scalar context (wherever an
expression is valid).</para>
</entry>
</row>
@@ -818,7 +800,7 @@
<para>At least one of the subquery pushdown capabilities.</para>
</entry>
<entry>
- <para>Connector can support a correlated subquery that refers to an element in
+ <para>Translator can support a correlated subquery that refers to an element in
the outer query.</para>
</entry>
</row>
@@ -841,7 +823,7 @@
<para />
</entry>
<entry>
- <para>Connector can support "searched” CASE expressions anywhere that expressions are
+ <para>Translator can support "searched” CASE expressions anywhere that expressions are
accepted.</para>
</entry>
</row>
@@ -853,7 +835,7 @@
<para />
</entry>
<entry>
- <para>Connector support UNION and UNION ALL</para>
+ <para>Translator support UNION and UNION ALL</para>
</entry>
</row>
<row>
@@ -864,7 +846,7 @@
<para/>
</entry>
<entry>
- <para>Connector supports INTERSECT</para>
+ <para>Translator supports INTERSECT</para>
</entry>
</row>
<row>
@@ -875,7 +857,7 @@
<para/>
</entry>
<entry>
- <para>Connector supports Except</para>
+ <para>Translator supports Except</para>
</entry>
</row>
<row>
@@ -886,7 +868,7 @@
<para>Unions, Intersect, or Except</para>
</entry>
<entry>
- <para>Connector supports set queries with an ORDER BY</para>
+ <para>Translator supports set queries with an ORDER BY</para>
</entry>
</row>
<row>
@@ -897,7 +879,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the limit portion of the limit clause</para>
+ <para>Translator can support the limit portion of the limit clause</para>
</entry>
</row>
<row>
@@ -908,7 +890,7 @@
<para/>
</entry>
<entry>
- <para>Connector can support the offset portion of the limit clause</para>
+ <para>Translator can support the offset portion of the limit clause</para>
</entry>
</row>
<row>
@@ -930,34 +912,55 @@
<para/>
</entry>
<entry>
- <para>Connector supports INSERT statements with values specified by an IQueryCommand.</para>
+ <para>Translator supports INSERT statements with values specified by an QueryExpression.</para>
</entry>
</row>
+ <row>
+ <entry>
+ <para>supportsBatchedUpdates</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator supports a batch of INSERT, UPDATE and DELETE commands to be executed together.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>supportsBulkUpdate</para>
+ </entry>
+ <entry>
+ <para/>
+ </entry>
+ <entry>
+ <para>Translator supports updates with multiple value sets</para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</table>
- <para>Note that any pushdown subquery must itself be compliant with the
- connector capabilities.</para>
+ <para>Note that any pushdown subquery must itself be compliant with the Translator capabilities.</para>
</sect2>
<sect2 id="command_form_capabilities">
<title>Command Form</title>
- <para>The method ConnectorCapabilities.useAnsiJoin() should return true
- if the Connector prefers the use of ANSI style join structure for
+ <para>The method <emphasis>ExecutionFactory.useAnsiJoin()</emphasis> should return true
+ if the Translator prefers the use of ANSI style join structure for
join trees that contain only INNER and CROSS joins.</para>
- <para>The method ConnectorCapabilities.requiresCriteria() should return
- true if the Connector requires criteria for any Query, Update, or
+ <para>The method <emphasis>ExecutionFactory.requiresCriteria()</emphasis> should return
+ true if the Translator requires criteria for any Query, Update, or
Delete. This is a replacement for the model support property "Where
All".</para>
</sect2>
<sect2>
<title>Scalar Functions</title>
- <para>The method ConnectorCapabilities.getSupportedFunctions() can be
- used to specify which scalar functions the connector supports. The
+ <para>The method <emphasis>ExecutionFactory.getSupportedFunctions()</emphasis> can be
+ used to specify which scalar functions the Translator supports. The
set of possible functions is based on the set of functions supported
by Teiid. This set can be found in the <ulink url="&docUrl;">Reference</ulink>
- documentation. If the connector states that it supports a function,
+ documentation. If the Translator states that it supports a function,
it must support all type combinations and overloaded forms of that
function.</para>
<para>There are also five standard operators that can also be specified in the
@@ -971,27 +974,25 @@
<sect2>
<title>Physical Limits</title>
- <para>The method ConnectorCapabilities.getMaxInCriteriaSize() can be
+ <para>The method <emphasis>ExecutionFactory.getMaxInCriteriaSize()</emphasis> can be
used to specify the maximum number of values that can be passed in an
IN criteria. This is an important constraint as an IN criteria is
frequently used to pass criteria between one source and another using
a dependent join.</para>
- <para>The method ConnectorCapabilities.getMaxFromGroups() can be used
+ <para>The method <emphasis>ExecutionFactory.getMaxFromGroups()</emphasis> can be used
to specify the maximum number of FROM Clause groups that can used in a
join. -1 indicates there is no limit.</para>
</sect2>
<sect2>
<title>Update Execution Modes</title>
- <para>The method ConnectorCapabilities.supportsBatchedUpdates() can be
- used to indicate that the connector supports executing the
- IBatchedUpdates command.
+ <para>The method <emphasis>ExecutionFactory.supportsBatchedUpdates()</emphasis> can be
+ used to indicate that the Translator supports executing the <emphasis>BatchedUpdates</emphasis> command.
</para>
- <para>The method ConnectorCapabilities.supportsBulkUpdate() can be used
- to indicate that the connector accepts update commands containg multi valued ILiterals.</para>
- <para>Note that if the connector does not support either of these
- update modes, the query engine will compensate by issuing the updates
- individually.</para>
+ <para>The method <emphasis>ExecutionFactory.supportsBulkUpdate()</emphasis> can be used
+ to indicate that the Translator accepts update commands containg multi valued Literals.</para>
+ <para>Note that if the translator does not support either of these
+ update modes, the query engine will compensate by issuing the updates individually.</para>
</sect2>
</sect1>
Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connection-pooling.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -1,357 +0,0 @@
-<chapter id="connection_pooling">
- <title>Connection Pooling</title>
- <sect1>
- <title>Overview</title>
- <para>The Query Engine logically obtains and closes a connection
- for each command.</para>
- <para>However many enterprise sources connections can be persistent
- and expensive to create. For these situations,
- Teiid provides a transparent connection pool to reuse, rather than
- constantly close, connections. The connection pool is highly
- configurable through configuration properties and extension APIs for
- Connections and Connectors</para>
- <para>Many built-in connector types take advantage of pooling,
- including JDBC, Salesforce, and LDAP connectors.</para>
- </sect1>
- <sect1>
- <title>Framework Overview</title>
- <para>The table below lists the role of each class in the
- framework.</para>
- <table frame="all">
- <title>Responsibilities of Connection Pool Classes
- </title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*" />
- <colspec colname='c2' colwidth=".5*" />
- <colspec colname='c3' colwidth="2*" />
- <thead>
- <row>
- <entry>
- <para>Class</para>
- </entry>
- <entry>
- <para>Type</para>
- </entry>
- <entry>
- <para>Description</para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>Connection</para>
- </entry>
- <entry>
- <para>Interface</para>
- </entry>
- <entry>
- <para>The isAlive and closeCalled methods are used for pool interaction.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>ConnectorIdentity</para>
- </entry>
- <entry>
- <para>Interface</para>
- </entry>
- <entry>
- <para>This interface corresponds to an identifier for a
- connection in the pool. Changing the identity implementation
- changes the basis on which connections are pooled. Connections
- that have equal identity objects (based on the equals() method)
- will be in the same pool.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>SingleIdentity</para>
- </entry>
- <entry>
- <para>Class</para>
- </entry>
- <entry>
- <para>This implementation of ConnectorIdentity makes all
- connections equivalent, thus user scoping of connection is ignored.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>MappedUserIdentity</para>
- </entry>
- <entry>
- <para>Class</para>
- </entry>
- <entry>
- <para>This implementation of ConnectorIdentity makes all
- connections equivalent for a particular user allowing for per-user connection pools.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>ConnectionPooling</para>
- </entry>
- <entry>
- <para>Annotation</para>
- </entry>
- <entry>
- <para>This optional Annotation can be used on the Connector
- implementation class to indicate configure pooling. This can be
- especially useful to indicate that automatic ConnectionPooing
- should not be used regardless of the connector binding property
- settings.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect1>
- <sect1>
- <title>Using Connection Pooling</title>
- <para>Automatic connection pooling does not require any
- changes to basic Connector development. It can be enabled by setting
- the Connector binding Property ConnectionPoolEnabled=true or by
- adding the ConnectionPooling annotation, which defaults to
- enabled=true, to the Connector implementation class. Automatic
- Connection pooling can be disabled if either setting is false.</para>
- <para>
- It is important
- to consider providing an implementation for
- Connection.isAlive to indicate that a Connection is no
- longer viable and should be purged from the pool. Connection testing
- is performed upon leases from the pool and optionally at a regular
- interval that will purge idle Connections. It is also important to
- consider having the concrete Connector class implement
- ConnectorIdentity factory if Connections are made for multiple
- identities. Note that setting connector binding property
- UseCredentialMap to true will allow connectors extending BasicConnector
- to have their ConnectorIdentity automatically set based upon the user
- CredentialMap.</para>
- </sect1>
- <sect1>
- <title>The Connection Lifecycle</title>
- <para>These steps occur when connection pooling is enabled:
- </para>
- <orderedlist>
- <listitem>
- <para>The
- ConnectorManager asks the Connector to generate a ConnectorIdentity
- for the given ExecutionContext. The
- ConnectorIdentity is then stored on the ExecutionContext.</para>
- </listitem>
- <listitem>
- <para>The ConnectorManager asks for a Connection from the pool
- that pertains to the ConnectorIdentity.</para>
- </listitem>
- <listitem>
- <para>The ConnectionPool returns a Connection that was either
- pulled from the pool (and passes the isAlive check) or was created
- by the Connector if necessary.</para>
- </listitem>
- <listitem>
- <para>After the ConnectorManager has used the Connection to
- execute a command, it releases the Connection. This call is
- intercepted by the pool and the method
- Connection.closeCalled is invoked on the Connection
- instead. Note that for many sources no action is necessary on closeCalled.</para>
- </listitem>
- <listitem>
- <para>When the Connection fails an isAlive check or becomes too
- old with pool shrinking enabled, it is purged from the pool and
- Connection.close is called.</para>
- </listitem>
- </orderedlist>
- <sect2>
- <title>XAConnection Pooling</title>
- <para>
- The usage of XAConnections (that provide XAResources) typically come
- with additional limitations about how those Connections can be used
- once they are enlisted in a transaction. When enabled, automatic
- connection pooling will perform these additional features with
- XAConnections:
- <itemizedlist>
- <listitem>
- <para>The pool will return the same XAConnection for all
- executions under a given transaction until that transaction
- completes. This implies that all executions to a given
- XAConnector under the same connection will happen serially.
- </para>
- </listitem>
- <listitem>
- <para>XAConnections enlisted in a transaction will
- return to the pool once a transaction completes.</para>
- </listitem>
- <listitem>
- <para>Two separate pools will be maintained. One for
- Connections that have not and will not be used in a transaction,
- and one for XAConnections that have an will be used in a
- transaction. Each pool will be configured based upon the same set
- of configuration properties - it is not possible to independently
- control pool sizes, etc.</para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
- </sect1>
- <sect1>
- <title>Configuring the Connection Pool</title>
- <para>The ConnectionPool has a number of properties that can be
- configured via the connector binding expert properties. Note *. indicates that the property prefix is com.metamatrix.data.pool.</para>
- <table frame="all">
- <title>Connection Pool Properties</title>
- <tgroup cols='4' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth=".5*" />
- <colspec colname='c2' colwidth="1*" />
- <colspec colname='c3' colwidth=".25*" />
- <colspec colname='c4' colwidth="1*" />
- <thead>
- <row>
- <entry>
- <para>Name</para>
- </entry>
- <entry>
- <para>Key</para>
- </entry>
- <entry>
- <para>Default Value</para>
- </entry>
- <entry>
- <para>Description</para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>Connection Pool Enabled</para>
- </entry>
- <entry>
- <para>ConnectionPoolEnabled</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- <entry>
- <para>Explicitly enables or disables connection
- pooling.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Data Source Test Connect Interval (seconds)</para>
- </entry>
- <entry>
- <para>SourceConnectionTestInterval
- </para>
- </entry>
- <entry>
- <para>600</para>
- </entry>
- <entry>
- <para>How often (in seconds) to create test connections to the
- underlying source to see if it is available.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Pool Maximum Connections</para>
- </entry>
- <entry>
- <para>*.max_connections
- </para>
- </entry>
- <entry>
- <para>20</para>
- </entry>
- <entry>
- <para>Maximum number of connections total in the pool.
- This value should be greater than 0.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Pool Maximum Connections for Each ID</para>
- </entry>
- <entry>
- <para>*.max_connections_for_each_id
- </para>
- </entry>
- <entry>
- <para>20</para>
- </entry>
- <entry>
- <para>Maximum number of connections per ConnectorIdentity
- object. This value should be greater than 0.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Pool Connection Idle Time (seconds)</para>
- </entry>
- <entry>
- <para>*.live_and_unused_time
- </para>
- </entry>
- <entry>
- <para>60</para>
- </entry>
- <entry>
- <para>Maximum idle time (in seconds) before a connection
- is closed if shrinking is enabled.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Pool Connection Waiting Time (milliseconds)</para>
- </entry>
- <entry>
- <para>*.wait_for_source_time
- </para>
- </entry>
- <entry>
- <para>120000</para>
- </entry>
- <entry>
- <para>Maximum time to wait (in milliseconds) for a
- connection to become available.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Pool cleaning Interval (seconds)</para>
- </entry>
- <entry>
- <para>*.cleaning_interval
- </para>
- </entry>
- <entry>
- <para>60</para>
- </entry>
- <entry>
- <para>Interval (in seconds) between checking for idle
- connections if shrinking is enabled.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Enable Pool Shrinking</para>
- </entry>
- <entry>
- <para>*.enable_shrinking
- </para>
- </entry>
- <entry>
- <para>true</para>
- </entry>
- <entry>
- <para>Indicate whether the pool is allowed to shrink.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect1>
-</chapter>
\ No newline at end of file
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-api.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -2,196 +2,168 @@
<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
%CustomDTD;
]>
-<chapter id="connector_api">
- <title>Connector API</title>
+<chapter id="translator_api">
+ <title>Developing a Translator</title>
<sect1>
- <title>Overview</title>
- <para>A component called the Connector Manager is controlling access
- to your connector. This chapter reviews
- the basics of how the Connector Manager interacts with your connector
- while leaving reference details and
+ <title>Extending the ExecutionFactory Class</title>
+ <para>A component called the Connector Manager is controlling access to your translator. This chapter reviews
+ the basics of how the Connector Manager interacts with your translator while leaving reference details and
advanced topics to be covered in later chapters.</para>
- <para>
- A custom connector must implement the following interfaces to connect
- and query an enterprise Data Source.
- These interfaces are in package called
- <emphasis>org.teiid.connector.api:</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>Connector</emphasis>
- - This interface is the starting point for all interaction with
- your connector. It allows the Connector
- Manager to obtain a connection and perform lifecycle events.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Connection</emphasis>
- - This interface represents a connection to your data source. It is
- used as a starting point for actual
- command executions. Connections provided to the Connector Manager will be
- obtained and released for each
- command execution. Teiid provides for extensible automatic connection
- pooling, as discussed in the
- <link linkend="connection_pooling">Connection Pooling</link>
- chapter.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>ConnectorCapabilities</emphasis>
- - This interface allows a connector to describe the execution
- capabilities of the connector.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Execution (and sub-interfaces)</emphasis>
- - These interfaces represent a command execution with your
- Connector. There is a sub-interface for
- executing each kinds of command: ResultSetExecution, UpdateExecution, and ProcedureExecution.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Note that many of the interfaces above have base implementations in the
- <emphasis>org.teiid.connector.basic</emphasis>
- package. Consider extending the corresponding BasicXXX class rather
- than fully implementing the interface.
- </para>
- <para>The most important interfaces provided by Teiid to the connector
- are the following:</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>ConnectorEnvironment</emphasis>
- – an interface describing access to external resources for your
- connector.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>ConnectorLogger</emphasis>
- – an interface for writing logging information to Teiid logs.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>ExecutionContext</emphasis>
- – interface defining the execution context available to the connector when
- executing a command.
- </para>
- </listitem>
- </itemizedlist>
+ <para>
+ A custom translator must extend <emphasis>org.teiid.translator.ExecutionFactory</emphasis>
+ to connect and query an enterprise data source. This extended class must provide a no-arg constructor
+ that can be constructed using Java reflection libraries. This Execution Factory need define/override following elements.
+ </para>
+
+ <sect2>
+ <title>ConnectionFactory</title>
+ <para>Defines the "ConnectionFactory" interface that is expected from resource adapter. This defined as part of
+ class definition using generics while extending the "ExecutionFactory" class</para>
+ </sect2>
+
+ <sect2>
+ <title>Connection</title>
+ <para>Defines the "Connection" interface that is expected from resource adapter. This defined as part of
+ class definition using generics while extending the "ExecutionFactory" class</para>
+ </sect2>
+
+ <sect2>
+ <title>Configuration Properties</title>
+ <para>Every software program requires some external configuration, that defines ways user can alter the behavior of a program.
+ If this translator needs configurable properties define a variable for every property as an attribute in the extended
+ "ExecutionFactory" class. Then define a "get" and "set" methods for each of them. Also, annotate each "get" method with
+ <emphasis>@TranslatorProperty</emphasis> annotation and provide the metadata about the property. For example, if you need a
+ property called "foo",
+ <programlisting><![CDATA[
+String foo = "balh";
+
+@TranslatorProperty(display="Foo property", description="description about Foo")
+public String getFoo() {
+ return foo;
+}
+
+public void setFoo(String value) {
+ return this.foo = value;
+}
+ ]]> </programlisting>
+
+ by providing the annotation on these properties, the Teiid tooling will automatically interrogate and
+ provide graphical way to configure your
+ Translator. Only "java.lang" and java "primitive" types are supported as Translator properties.
+ If you do not provide the property during the configuration, the default value defined in this class will be used.
+ All the properties <emphasis>should</emphasis> have a default value. If you can not provide a default value,
+ validate all the required properties during the initialization, fail if one is not provided. Repeat this
+ process for all the properties that you require to configure the Translator.
+ </para>
+
+ <para>The <emphasis>@TranslatorProperty</emphasis> defines the following metadata that you can define about your property</para>
+ <itemizedlist>
+ <listitem>
+ <para>display: Display name of the property</para>
+ </listitem>
+ <listitem>
+ <para>description: Description about the property</para>
+ </listitem>
+ <listitem>
+ <para>required: The property is a required property; or optional and a default is supplied</para>
+ </listitem>
+ <listitem>
+ <para>advanced: This is advanced property; A default must be provided. A property can not be "advanced" and "required" at same time.</para>
+ </listitem>
+ <listitem>
+ <para>masked: The tools need to mask the property; Do not show in plain text; used for passwords</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Initializing the Translator</title>
+ <para>Override and implement the <emphasis>start</emphasis> method (be sure to call
+ "super.start()") if your translator needs to do any initializing before it is used by the Teiid engine. This method
+ will be called by Teiid, once after all the configuration properties set above are injected into the class. </para>
+ </sect2>
+
+ <sect2>
+ <title>TranslatorCapabilities</title>
+ <para>These are various methods that typically begin with method
+ signature "supports" on the "ExecutionFactory" calss. These methods need to be overridden to describe the execution
+ capabilities of the Translator. These will be used by the query engine to determine the capabilities of the Translator.
+ More information on what these are in the next chapter.</para>
+ </sect2>
+
+ <sect2>
+ <title>Execution (and sub-interfaces)</title>
+ <para>Based on types of executions you are supporting, the following methods need to be overridden
+ and need to provide implementations for these methods by extending respective interfaces.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>createResultSetExecution</emphasis> - Define if you are doing read based operation that is
+ returning a rows of results.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>createUpdateExecution</emphasis> - Define if you are doing write based operations.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>createProcedureExecution</emphasis> - Define if you are doing procedure based operations.</para>
+ </listitem>
+ </itemizedlist>
+ <para>You can choose to implement all the execution modes or just what you need. There is no restriction, but it must
+ implement at least one type of execution. See more details on this below.</para>
+ </sect2>
+
+ <sect2>
+ <title>Metadata</title>
+ <para>Override and implement the method <emphasis>getMetadata()</emphasis>, if you want to expose the
+ metadata about the source. This defines the tables with its column names, procedures with its parameter that
+ this translator exposing to the query engine. If you expect your translator to work with Dynamic VDB, you must override this
+ method, if are always going to use Designer to build the VDB then this is optional. </para>
+ </sect2>
+
+ <sect2>
+ <title>Logging</title>
+ <para>Teiid provides <emphasis>org.teiid.logging.LogManager</emphasis> class for logging purposes.
+ Create a logging context and use the LogManager to log your messages. These will be automatically
+ sent to the main Teiid logs. You can edit the "jboss-log4j.xml" inside "conf" directory of the JBoss AS's profile
+ to add the custom context. Teiid uses Log4J as its underlying logging system.</para>
+ </sect2>
+
+ <sect2>
+ <title>Exceptions</title>
+ <para>If you need to bubble up any exception use <emphasis>org.teiid.translator.TranslatorException</emphasis>
+ class.</para>
+ </sect2>
+
+ <sect2>
+ <title>Default Name</title>
+ <para>Finally, you can define a default instance of your Translator by defining the
+ annotation <emphasis>@Translator</emphasis> on the "ExecutionFactory". When you define this, and after deployment
+ a default instance of this
+ Translator is available any VDB that would like to use by just mentioning its name in its "vdb.xml" configuration file.
+ VDB can also override the default properties and define another instance of this Translator too. The name you give here is the short
+ name used every where else in the Teiid configuration to refer to this translator.</para>
+ </sect2>
+
</sect1>
+
+
<sect1>
- <title>Connector Lifecycle</title>
- <sect2>
- <title>Starting</title>
- <para>
- A Connector instance will be initialized one time via the start
- method, which passes in a
- <emphasis>ConnectorEnvironment</emphasis>
- object provided by the
- <emphasis>Connector Manager</emphasis>
- . The
- <emphasis>ConnectorEnvironment provides</emphasis>
- the following resources to the connector:
- </para>
- <itemizedlist>
- <listitem>
- <para>Configuration properties – name / value pairs as provided by
- the connector binding in
- the Teiid Console</para>
- </listitem>
- <listitem>
- <para>Logging – ConnectorLogger interface allows a Connector to log
- messages and errors to
- Teiid’s log files.</para>
- </listitem>
- <listitem>
- <para>Type facility – an interface defining runtime datatypes and
- type conversion facility.</para>
- </listitem>
- <listitem>
- <para>Scheduling facility – repeating tasks can be scheduled and managed by Teiid.</para>
- </listitem>
- <listitem>
- <para>Caching facility – easy methods for caching based upon relevant contexts, such as session or query scope.</para>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2>
- <title>Running</title>
- <para>
- While the connector is running it is expected to return provide
- connections and capabilities information in response to system
- requests. If the source system is not available ConnectorExceptions or
- RuntimeExceptions may be thrown at any time to indicate failure. The
- connector should handle failure internally in a graceful manner, since
- the system will not automatically perform a stop/start.
- </para>
- </sect2>
- <sect2>
- <title>Stopping</title>
- <para>The stop method will be called on system shutdown or on an
- administrative call that to stop the connector. Once a connector has
- been stopped the instance is removed from the system. A new Connector
- instance will be created prior to the start call.</para>
- </sect2>
- </sect1>
- <sect1>
<title>Connections to Source</title>
<sect2>
<title>Obtaining connections</title>
- <para>The connector must implement the getConnection() method to
- allow the Connector Manager to obtain a
- connection. The getConnection() method is passed a ExecutionContext, which
- contains information about the
- context in which this query is being executed.</para>
- <para>The ExecutionContext provides the following:</para>
- <itemizedlist>
- <listitem>
- <para>User name</para>
- </listitem>
- <listitem>
- <para>Virtual database name</para>
- </listitem>
- <listitem>
- <para>Virtual database version</para>
- </listitem>
- <listitem>
- <para>The ability to add execution warnings.</para>
- </listitem>
- <listitem>
- <para>Trusted token</para>
- </listitem>
- </itemizedlist>
- <para>The trusted token is used to pass security information specific
- to your application through the
- Teiid. The client can pass the trusted token when they connect via
- JDBC. This token is then
- passed to the Membership Service and may be created, replaced, or modified
- at that time. In some cases, you
- may wish to provide a customer Membership Service implementation to
- handle security needs specific to your
- organization. For more information on implementing see the <ulink url='&docUrl;'>Server Extension Guide</ulink></para>
+ <para>The extended "ExecutionFactory" must implement the <emphasis>getConnection()</emphasis> method to
+ allow the Connector Manager to obtain a connection. </para>
</sect2>
<sect2>
<title>Releasing Connections</title>
- <para>Once the Connector Manager has obtained a connection, it will
- use that connection only for the
- lifetime of the request. When the request has completed, the close()
- method will be called on the
- connection.</para>
+ <para>Once the Connector Manager has obtained a connection, it will use that connection only for the
+ lifetime of the request. When the request has completed, the closeConnection() method called on the "ExecutionFactory".
+ You must also override this method to properly close the connection.</para>
<para>
In cases (such as when a connection is stateful and expensive to
- create), connections should be pooled. Teiid
- provides an extensible connection pool for this purpose, as described in
- chapter
- <link linkend="connection_pooling">Connection Pooling</link>.
+ create), connections should be pooled. If the resource adapter is JEE JCA connector based, then pooling is automatically
+ provided by the JBoss AS container. If your resource adapter does not implement the JEE JCA, then connection pooling
+ sematics are left to the user to define on their own.
</para>
</sect2>
</sect1>
@@ -200,13 +172,10 @@
<sect2>
<title>Execution Modes</title>
<para>
- The Connector API uses a Connection to obtain an execution
- interface for the command it is
- executing. The actual queries themselves are sent to connectors in the form of a
- set of objects, which are further
- described in Chapter
- <link linkend="command_language">Command Language</link>. Connectors are allowed to support any subset of the available
- execution modes.
+ The Teiid query engine uses the "ExecutionFactory" class to obtain the "Execution" interface for the command it is
+ executing. The actual queries themselves are sent to translators in the form of a set of objects, which are further
+ described in Chapter <link linkend="command_language">Command Language</link>.
+ translators are allowed to support any subset of the available execution modes.
</para>
<table frame='all'>
<title>Types of Execution Modes</title>
@@ -227,7 +196,7 @@
<code>ResultSetExecution</code>
</entry>
<entry>
- <code>IQueryCommand</code>
+ <code>QueryExpression</code>
</entry>
<entry>A query corresponding to a SQL SELECT or set query statement.</entry>
</row>
@@ -236,10 +205,9 @@
<code>UpdateExecution</code>
</entry>
<entry>
- <code>IInsert, IUpdate, IDelete, IBatchedUpdates</code>
+ <code>Insert, Update, Delete, BatchedUpdates</code>
</entry>
- <entry>An insert, update, or delete, corresponding to a SQL
- INSERT, UPDATE, or DELETE command
+ <entry>An insert, update, or delete, corresponding to a SQL INSERT, UPDATE, or DELETE command
</entry>
</row>
<row>
@@ -247,10 +215,9 @@
<code>ProcedureExecution</code>
</entry>
<entry>
- <code>IProcedure</code>
+ <code>Call</code>
</entry>
- <entry>A procedure execution that may return a result set and/or
- output values.</entry>
+ <entry>A procedure execution that may return a result set and/or output values.</entry>
</row>
</tbody>
</tgroup>
@@ -262,10 +229,9 @@
<sect2>
<title>ResultSetExecution</title>
<para>
- Typically most commands executed against connectors are IQueryCommands.
- While the command is being executed, the connector provides
- results via the
- ResultSetExecution next method. The next method should return null to indicate the end
+ Typically most commands executed against translators are QueryExpression.
+ While the command is being executed, the translator provides results via the
+ ResultSetExecution's "next" method. The "next" method should return null to indicate the end
of results. Note: the expected batch size can be obtained from the
ExecutionContext and used as a hint in fetching results from the EIS.
</para>
@@ -273,28 +239,24 @@
<sect2>
<title>Update Execution</title>
<para>Each execution returns the update count(s) expected by the update command.
- If possible IBatchedUpdates should be executed atomically.
+ If possible BatchedUpdates should be executed atomically.
The ExecutionContext can be used to determine if the execution is already under a transaction.</para>
</sect2>
<sect2>
<title>Procedure Execution</title>
- <para>Procedure commands correspond to the execution of a stored
- procedure or some other functional
+ <para>Procedure commands correspond to the execution of a stored procedure or some other functional
construct. A procedure takes zero or more input values and can return a result
- set and zero or more output
- values. Examples of procedure execution would be a stored procedure in a
- relational database or a call to
- a web service.</para>
- <para>If a result set is expected when a procedure is executed, all
- rows from it will be retrieved via the
+ set and zero or more output values. Examples of procedure execution would be a stored procedure in a
+ relational database or a call to a web service.</para>
+ <para>If a result set is expected when a procedure is executed, all rows from it will be retrieved via the
ResultSetExecution interface first. Then, if any output values are expected, they will
- be retrieved via the
- getOutputParameterValues() method.
+ be retrieved via the getOutputParameterValues() method.
</para>
</sect2>
+ <!--
<sect2>
<title>Asynchronous Executions</title>
- <para>In some scenarios, a connector needs to execute
+ <para>In some scenarios, a translator needs to execute
asynchronously and allow the executing thread to perform other work. To allow this, you should:
</para>
<itemizedlist>
@@ -316,29 +278,24 @@
</listitem>
</itemizedlist>
</sect2>
+ -->
<sect2>
<title>Bulk Execution</title>
- <para>
- Non batched
- <code>IInsert, IUpdate, IDelete</code>
- commands may have Iliteral values marked as multiValued if the
- ConnectorCapabilities shows support for BulkUpdate. Commands with
- multiValued Iliterals represent multiple executions of the same
- command with different values. As with IBatchedUpdates, bulk operations should be executed atomically if possible.
+ <para> Non batched <code>Insert, Update, Delete</code>
+ commands may have <code>Literal</code> values marked as multiValued if the
+ capabilities shows support for BulkUpdate. Commands with
+ multiValued <code>Literal</code>s represent multiple executions of the same
+ command with different values. As with BatchedUpdates, bulk operations should be executed atomically if possible.
</para>
</sect2>
<sect2>
<title>Command Completion</title>
- <para>All normal command executions end with the calling of close()
- on the Execution object. Your
- implementation of this method should do the appropriate clean-up work for all
- state in the Execution
- object.</para>
+ <para>All normal command executions end with the calling of <code>close()</code> on the Execution object. Your
+ implementation of this method should do the appropriate clean-up work for all state in the Execution object.</para>
</sect2>
<sect2>
<title>Command Cancellation</title>
- <para>Commands submitted to Teiid may be aborted in several
- scenarios:</para>
+ <para>Commands submitted to Teiid may be aborted in several scenarios:</para>
<itemizedlist>
<listitem>
<para>Client cancellation via the JDBC API (or other client APIs)
@@ -354,74 +311,55 @@
<para>Clean-up if a query fails during processing</para>
</listitem>
</itemizedlist>
- <para>Unlike the other execution methods, which are handled in a single-threaded manner, calls to cancel happen asynchronously with respect to the execution thread.</para>
- <para>Your connector implementation may choose to do nothing in
- response to this cancellation message. In
+ <para>Unlike the other execution methods, which are handled in a single-threaded manner,
+ calls to cancel happen asynchronously with respect to the execution thread.</para>
+ <para>Your connector implementation may choose to do nothing in response to this cancellation message. In
this instance, Teiid will call close() on the execution object after
- current processing
- has completed. Implementing the cancel() method allows for faster
- termination of queries being processed
- and may allow the underlying data source to terminate its operations
+ current processing has completed. Implementing the cancel() method allows for faster
+ termination of queries being processed and may allow the underlying data source to terminate its operations
faster as well.</para>
</sect2>
</sect1>
- <sect1>
- <title>Monitored Connectors</title>
- <para>Teiid can automatically monitor connectors, which will update a
- status flag on the connector. This status can be checked via the
- AdminApi and is exposed in the console. To use connector
- monitoring
- effectively:
- </para>
- <itemizedlist>
- <listitem>
- <para>Set a positive test interval value on
- on the connector binding
- (default is 600) indicating the number of
- seconds between status
- checks. These checks are useful in idle
- periods.
- </para>
- </listitem>
- <listitem>
- <para>Implement a meaningful isAlive method on your Connector
- Connections.
- </para>
- </listitem>
- <listitem>
- <para>Use either a pooled Connector or a Connector that supports
- single identity.
- </para>
- </listitem>
- </itemizedlist>
- <para>Possible status results include:</para>
- <itemizedlist>
- <listitem>
- <para>Not initialized - to indicate not yet started.
- </para>
- </listitem>
- <listitem>
- <para>Init failed - to indicate start failed.
- </para>
- </listitem>
- <listitem>
- <para>Open - to indicate the running state and that connections can
- be obtained form the source.
- </para>
- </listitem>
- <listitem>
- <para>Unable to check - to indicate the running state but
- connections cannot be obtained administratively.
- </para>
- </listitem>
- <listitem>
- <para>Data Source Unavailable - to indicate the running state.
- </para>
- </listitem>
- <listitem>
- <para>Closed - to indicate that the Connector has been stopped.
- </para>
- </listitem>
- </itemizedlist>
- </sect1>
+
+ <sect1>
+ <title>Packaging</title>
+ <para>Once the "ExecutionFactory" class is implemented, package it in a JAR file. The only
+ additional requirement is provide a file called "jboss-beans.xml" in the "META-INF" directory of the JAR file, with
+ following contents.
+ <programlisting><![CDATA[
+ <?xml version="1.0" encoding="UTF-8"?>
+ <deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="translator-${name}-template" class="org.teiid.templates.TranslatorDeploymentTemplate">
+ <property name="info"><inject bean="translator-${name}"/></property>
+ <property name="managedObjectFactory"><inject bean="ManagedObjectFactory"/></property>
+ </bean>
+
+ <bean name="translator-${name}" class="org.teiid.templates.TranslatorTemplateInfo">
+ <constructor factoryMethod="createTemplateInfo">
+ <factory bean="TranslatorDeploymentTemplateInfoFactory"/>
+ <parameter class="java.lang.Class">org.teiid.templates.TranslatorTemplateInfo</parameter>
+ <parameter class="java.lang.Class">${execution-factory-class}</parameter>
+ <parameter class="java.lang.String">translator-${name}</parameter>
+ <parameter class="java.lang.String">${name}</parameter>
+ </constructor>
+ </bean>
+
+ </deployment>
+ ]]> </programlisting>
+
+ replace ${name} with name of your translator, and replace ${execution-factory-class} with your
+ overridden Execution Factory class name. This will create Java bean in the JBoss AS, that facilitates to interrogate
+ available properties in configuration for this Translator for tooling and Admin API.</para>
+ </sect1>
+
+ <sect1>
+ <title>Deployment</title>
+ <para>Copy the JAR file that defines the Translator into "deploy" directory of the JBoss AS's chosen profile, and
+ Translator will be deployed automatically. There is no restriction that, JBoss AS need to be restarted. However, if your Translator
+ has external dependencies to other JAR libraries, they need to be placed inside the "lib" directory of the JBoss AS's profile.
+ This will require a restart of the JBoss Server. Another option to avoid the restart is to bundle all the required JAR files into
+ the same JAR file as the Translator. It is user's responsibility to make sure they are not running into any conflicts with their
+ dependent libraries with those already exist in the JBoss environment.</para>
+ </sect1>
</chapter>
\ No newline at end of file
Deleted: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/connector-deployment.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -1,371 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
-%CustomDTD;
-]>
-<chapter id="connector_deployment">
- <title>Connector Deployment</title>
-
- <sect1>
- <title>Overview</title>
- <para>Once you have written and compiled the code for your connector, there are several
- steps to deploy your connector to Teiid:</para>
- <itemizedlist>
- <listitem>
- <para>Creating a Connector Type Definition file that defines the properties required
- to initialize your connector.</para>
- </listitem>
- <listitem>
- <para>Identifying the Extension Modules (jars and resources) required for the
- Connector to run.</para>
- </listitem>
- <listitem>
- <para>Creating the Connector Archive file to bundle the Connector Type Definition
- file and the Extension Modules.</para>
- </listitem>
- <listitem>
- <para>Creating a Connector Binding using your Connector Type.</para>
- </listitem>
- </itemizedlist>
- <para>This chapter will help you perform these steps. </para>
- </sect1>
-
- <sect1>
- <title>Connector Type Definition File</title>
- <para>A Connector Type Definition file defines a connector in Teiid. The
- Connector Type Definition file defines some key properties that allow Teiid to
- use your connector as well as specifying other properties your connector might need. </para>
- <para>A Connector Type Definition file is in XML format and typically has the extension “.cdk”.
- It defines a default name for the connector type, the properties expected by the connector,
- and other information that allows the properties to be displayed correctly in the Console when
- a Connector Binding is created from the Connector Type. </para>
- <para> An example of this file can be found in <link linkend="appendix-a">Appendix A.</link>
- It may be helpful to refer to this file while reading this section. The template file can
- also be created using the Connector Development Kit.</para>
-
- <sect2>
- <title>Connector Binding Properties</title>
- <para>The Connector API has built-in mechanisms for using the
- properties defined in the Connector ComponentType definition in the
- configuration.xml located in your deploy directory. For custom
- connectors the following properties are of primary importance:</para>
- <table frame='all'>
- <title>Connector Properties</title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth="1*"/>
- <colspec colname='c3' colwidth="2*" />
- <thead>
- <row>
- <entry>
- <para>Property Name</para>
- </entry>
- <entry>
- <para>Example Value</para>
- </entry>
- <entry>
- <para>Description</para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>ConnectorClass</para>
- </entry>
- <entry>
- <para>foo.MyConnector</para>
- </entry>
- <entry>
- <para>Fully-qualified name of class implementing the Connector interface.</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>ConnectorClassPath</para>
- </entry>
- <entry>
- <para>extensionjar:foo.jar</para>
- </entry>
- <entry>
- <para>Semi-colon delimited list of jars defining the classpath of this
- connector. Typically this includes the actual code for your connector as well as
- any 3rd party dependencies.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>For more information on the Connector Classpath, see the section <link linkend="understanding_classpath">Understanding the Connector Classpath</link></para>
- </sect2>
-
- <sect2>
- <title>Connector Properties</title>
- <para>Most connectors require some initialization parameters to connect to the
- underlying enterprise information system. These properties can be defined in the Connector
- Type Definition file along with their default values and other property metadata. The actual
- property values can be changed when the connector is deployed in the Teiid Console.</para>
- <para>Each connector property carries with it several attributes that are used by the
- Teiid Console to integrate the connector seamlessly into Teiid.</para>
-
- <table frame='all'>
- <title>All Attributes</title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth="1*"/>
- <colspec colname='c3' colwidth="2*"/>
- <thead>
- <row>
- <entry>
- <para>Attribute Name</para>
- </entry>
- <entry>
- <para>Example Value</para>
- </entry>
- <entry>
- <para>Description</para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>Name</para>
- </entry>
- <entry>
- <para>ExampleProperty</para>
- </entry>
- <entry>
- <para>Property name – should only contain letters, no spaces or other
- punctuation. This is the name of the property as it will be passed to the connector
- in the ConnectorEnvironment.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>DisplayName</para>
- </entry>
- <entry>
- <para>Example property</para>
- </entry>
- <entry>
- <para>The property name as displayed in the Console. Typically this is a nicely
- formatted version of the Name attribute.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>ShortDescription</para>
- </entry>
- <entry>
- <para>The example property is used to control something.</para>
- </entry>
- <entry>
- <para>A short description that is displayed as a tooltip of the property in the
- Teiid Console.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>DefaultValue</para>
- </entry>
- <entry>
- <para>Xyz</para>
- </entry>
- <entry>
- <para>A default value for the property. This value will be auto-filled when a
- connector binding is created from the Connector Type.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>IsRequired</para>
- </entry>
- <entry>
- <para>false</para>
- </entry>
- <entry>
- <para>If true, then this property is required. Any required property without a value
- is displayed in red in the connector binding properties panel.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>IsModifiable</para>
- </entry>
- <entry>
- <para>true</para>
- </entry>
- <entry>
- <para>If set to “false”, the property is visible only when viewing all properties and is
- not modifiable in the properties panel. </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>IsMasked</para>
- </entry>
- <entry>
- <para>false</para>
- </entry>
- <entry>
- <para>If set to “true”, the property will be masked with *’s when it is entered and
- saved in an encrypted form. This attribute is typically used with passwords.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>IsExpert</para>
- </entry>
- <entry>
- <para>true</para>
- </entry>
- <entry>
- <para>Depending on the property display, the property can be optionally
- displayed for advanced users.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>PropertyType</para>
- </entry>
- <entry>
- <para>String</para>
- </entry>
- <entry>
- <para>The short name of a built-in Java primitive wrapper Object type. Other
- possible values include Integer, Boolean, etc.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>A property may also be constrained to a set of allowed values by
- adding child AllowedValue elements, i.e.
- <AllowedValue>value</AllowedValue>.
- Adding allowed values will cause the property to be displayed with a
- dropdown that limits the user selection to the allowed values.
- </para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Extension Modules</title>
- <para>Extension Modules are used in Teiid to store code that extends
- Teiid in a central managed location. Extension Module JAR files are stored in
- the repository database and all Teiid processes access this database to obtain extension
- code. Custom connector code is typically deployed as extension models.</para>
- <sect2 id="understanding_classpath">
- <title>Understanding the Connector Classpath</title>
- <para>By default each connector binding is loaded using the Teiid
- common classloader. Any needed extension modules are automatically
- added to common classpath. The common classloader is also a delegating
- classloader, so it's possible for classes to be found from the
- classpath set for Teiid or it's containing application.</para>
- <para>
- If class conflicts would arise from delegation or shared classloading,
- each connector binding
- can be loaded in an isolated classloader (shared only by connectors
- with the same classpath), by setting the connector binding property
- UsePostDelegation to true. This classloading mode loads
- classes via the Teiid Extension Modules before loading classes from higher
- level classloaders.</para>
-
- <para>The ConnectorClasspath property of your connector defines the
- extension module jars
- that are included in your connector’s classpath. The connector classpath
- is defined as a
- semi-colon delimited list of extension modules. Extension module jar files must
- be prefixed
- with "extensionjar:"</para>
- </sect2>
- </sect1>
- <sect1>
- <title>Connector Archive File</title>
- <para>The Connector Archive file is a bundled version of all files needed by this Connector
- to execute in Teiid. This file includes the Connector Type Definition file and
- all the Extension Modules required by the Connector to create a connector archive file (CAF)..
- </para>
- <itemizedlist>
- <listitem>
- <para>The archive is a standard zip file.</para>
- </listitem>
- <listitem>
- <para>Start the CDK tool by executing cdk.bat</para>
- </listitem>
- <listitem>
- <para>Execute “CreateArchive” command by supplying:</para>
- <orderedlist>
- <listitem>
- <para>Path to the name of the archive file to create</para>
- </listitem>
- <listitem>
- <para>Path to the Connector Type Definition file</para>
- </listitem>
- <listitem>
- <para>Path to the directory where the required Extension Modules (jar files) are stored
- (note that only .jar files specified in the ConnectorClassPath property of the Connector
- Type definition file are bundled.</para>
- </listitem>
- </orderedlist>
- </listitem>
- </itemizedlist>
-
- <para>The file created by the CDK can be opened with any zip file utility to verify the
- required files are included.</para>
- <para>The archive file can be tested in the CDK tool by loading it using the command
- “loadArchive”. Refer <link linkend="connector_development_kit">CDK chapter</link> for more information.</para>
- </sect1>
- <sect1>
- <title>Importing the Connector Archive</title>
-
- <sect2>
- <title>Into Teiid</title>
- <para>To use a new connector type definition in Teiid, the Connector Archive
- file must be imported via the AdminAPI via the addConnectorArchive method.</para>
- </sect2>
-
- <sect2>
- <title>Into Teiid Designer</title>
- <para>To use the new connector type during the development of the VDB for testing using the
- SQLExplorer, Connector Archive File must be imported into the Designer tools. To perform this
- task, perform the following steps.</para>
- <orderedlist>
- <listitem>
- <para>Start Designer</para>
- </listitem>
- <listitem>
- <para>Open the project and in the “vdb” execute panel, click on the “Open the
- Configuration Manager” link. For more information consult the designer’s guide.</para>
- </listitem>
- </orderedlist>
- <orderedlist>
- <listitem>
- <para>In the result window, click “Import a Connector Type (.cdk,.caf)” link and follow
- directions.</para>
- </listitem>
- </orderedlist>
- <para>The Connector Type can now be used to create Connector Bindings. </para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Creating a Connector Binding</title>
-
- <sect2>
- <title>In Designer</title>
- <para>Connector Binding properties can also be defined in the Designer for the given
- Connector Type, if the corresponding Connector Archive File is imported into the Designer. If
- you try to execute your VDB with SQLExplorer in the Designer, this tool will present you with
- a window to specify such Connector Bindings. The user is required specify these binding
- properties before they can test using the SQLExplorer. For more information on how this can be
- accomplished please refer to the <ulink url="&desDocUrl;">Designer User’s Guide</ulink>.</para>
- <para>Also, note that the bindings specified in the Designer tool are automatically bundled
- into the VDB for deployment, so if there are any properties that needs to be changed from
- development environment to the production environment, those properties need to be modified
- when a VDB is later deployed.</para>
- </sect2>
- </sect1>
-</chapter>
\ No newline at end of file
Added: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml (rev 0)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -0,0 +1,288 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
+%CustomDTD;
+]>
+<chapter id="develop_adapter">
+ <title>Developing JEE JCA Adapters for Teiid Translators</title>
+ <para>This chapter examines how to use facilities provided by the Teiid
+ API to develop a JEE JCA Connector that can be used with the Teiid Translator. Please note that these are
+ standard JEE JCA connectors, nothing special needs to be done for Teiid. As an aid to our Translator
+ developers, we provided some base implementation framework to ease the development of these Connectors.
+ If you already have a JCA Connector or some other mechanism to get data from your source system, you can skip this chapter.</para>
+
+ <para>If you are not familiar with JCA API, please read the <ulink url="http://java.sun.com/j2ee/connector/">JCA 1.5 Specification</ulink>.
+ There are lot of online tutorials on how to design and build a JCA Connector. The below we show you to build very simple connector,
+ however building actual connector that supports transactions, security can get much more complex.</para>
+
+ <para>Check out the following links <ulink url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch7.chapt.html">Connectors on JBoss</ulink> </para>
+
+ <sect1>
+ <title>Develop Adapter using the Teiid Framework</title>
+ <para>If you are going to use the Teiid framework for developing a JCA connector, follow these steps. The required classes are in
+ <emphasis>org.teiid.resource.api</emphasis> package. Please note that Teiid framework does not make use JCA's CCI framework. It
+ only uses the JCA's SPI interfaces. </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Define Managed Connection Factory</para>
+ </listitem>
+ <listitem>
+ <para>Define the Connection Factory class</para>
+ </listitem>
+ <listitem>
+ <para>Define the Connection class</para>
+ </listitem>
+ <listitem>
+ <para>Define the configuration properties in a "ra.xml" file</para>
+ </listitem>
+ </itemizedlist>
+
+ <sect2 id="managed_connection_factory">
+ <title>Define Managed Connection Factory</title>
+ <para>Extend the <emphasis>BasicManagedConnectionFactory</emphasis>, and provide a implementation for the
+ "createConnectionFactory()" method. This method defines a factory method that can create connections.</para>
+
+ <para>This class also defines configuration variables, like user, password, URL etc to connect to the EIS system. Define an
+ attribute for each configuration variable, and then provide both "getter" and "setter" methods for them.
+ Note to use only "java.lang" objects as the attributes, DO NOT use Java primitives for defining and accessing the properties.
+ See the following code for an example.</para>
+ <programlisting><![CDATA[
+ public class MyManagedConnectionFactory extends BasicManagedConnectionFactory {
+ @Override
+ public Object createConnectionFactory() throws ResourceException {
+ return new MyConnectionFactory();
+ }
+
+ // config property name (metadata for these are defined inside the ra.xml)
+ String userName;
+ public String getUserName() {
+ return this.userName;
+ }
+ public void setUserName(String name) {
+ this.userName = name;
+ }
+
+ // config property count (metadata for these are defined inside the ra.xml)
+ Integer count;
+ public Integer getCount() {
+ return this.count;
+ }
+ public void setCount(Integer value) {
+ this.count = value;
+ }
+ }
+ ]]></programlisting>
+ </sect2>
+ <sect2>
+ <title>Define the Connection Factory class</title>
+ <para>Extend the <emphasis>BasicConnectionFactory</emphasis> class, and provide a implementation for the "getConnection()" method.</para>
+ <programlisting><![CDATA[
+ public class MyConnectionFactory extends BasicConnectionFactory {
+ @Override
+ public MyConnection getConnection() throws ResourceException {
+ return new MyConnection();
+ }
+ }
+ ]]></programlisting>
+ <para>Since the Managed connection object created the "ConnectionFactory" class it has access to all the configuration
+ parameters, if "getConnection" method needs to do pass any of credentials to the underlying EIS system.
+ The Connection Factory class can also get reference to the calling user's <emphasis>javax.security.auth.Subject</emphasis> during
+ "getConnection" method by calling
+
+ <programlisting><![CDATA[
+ Subject subject = ConnectionContext.getSubject();
+ ]]></programlisting>
+ This "Subject" object can give access to logged-in user's credentials and roles that are defined. Note that this may be null.
+ </para>
+ <para>Note that you can define "security-domain" for this resource adapter, that is separate from
+ the Teiid defined "security-domain" for validating the JDBC end user. However, it is users responsibility to make the necessary
+ logins before the Container's thread accesses this resource adapter, and this can get overly complex.</para>
+ </sect2>
+
+ <sect2 id="connection">
+ <title>Define the Connection class</title>
+ <para>Extend the <emphasis>BasicConnection</emphasis> class, and provide a implementation based on your access
+ of the Connection object in the Translator. If your
+ connection is stateful, then override "isAlive()" and "cleanup()" methods and provide proper implementations. These are called
+ to check if a Connection is stale or need to flush them from the connection pool etc. by the Container.</para>
+ <programlisting><![CDATA[
+ public class MyConnection extends BasicConnection {
+
+ public void doSomeOperation(command){
+ // do some operation with EIS system..
+ // This is method you use in the Translator, you should know
+ // what need to be done here for your source..
+ }
+
+ @Override
+ public boolean isAlive() {
+ return true;
+ }
+ @Override
+ public void cleanUp() {
+
+ }
+ }
+ ]]></programlisting>
+ </sect2>
+
+ <sect2>
+ <title>XA Transactions</title>
+ <para>If you EIS source can participate in XA transactions, then on your <link linkend="connection">Connection</link> object,
+ override the "getXAResource()" method and provide the "XAResource" object for the EIS system.
+ Also, You need to extend the "BasicResourceAdapter" class and provide implementation for method
+ "public XAResource[] getXAResources(ActivationSpec[] specs)" to participate in crash recovery. </para>
+
+ <para>Note that, only when the resource adapters are XA capable, then Teiid can make them participate in a distributed
+ transactions. If they are not XA capable, then source can participate in distributed query but will not participate
+ in the transaction. Transaction semantics at that time defined by how you defined "-ds.xml" file. i.e. with local-tx or no-tx</para>
+ </sect2>
+
+ <sect2>
+ <title>Define the configuration properties in a "ra.xml" file</title>
+ <para>Define a "ra.xml" file (sample shown in the <link linkend="appendix_a">appendix-a</link>) in "META-INF" directory of your RAR file.
+ For every configuration property defined inside the <link linkend="managed_connection_factory">ManagedConnectionFactory</link>
+ class, define the following XML configuration
+ fragment inside the "ra.xml" file. These properties are used by user to configure instance of this Connector inside a
+ Container. Also, during the startup the Container reads these properties from this file and knows how to inject
+ provided values in the "-ds.xml" file into a instance of "ManagedConnectionFactory" to create the Connection.</para>
+ <programlisting><![CDATA[
+ <config-property>
+ <description>{$display:"${display-name}",$description:"${description}", $allowed="${allowed}", $required="${true|false}", $defaultValue="${default-value}"}</description>
+ <config-property-name>${property-name}</config-property-name>
+ <config-property-type>${property-type}</config-property-type>
+ <config-property-value>${optioal-property-value}</config-property-value>
+ </config-property>
+ ]]></programlisting>
+
+ <para>The format and contents of "<description>" element is a Teiid extension to provide the extended metadata for tooling purpose. The
+ JCA specification does not define enough metadata on these properties so Teiid fills in the gap with its own extension.
+ For every property define the following properties
+
+ <itemizedlist>
+ <listitem>
+ <para>$display: Display name of the property</para>
+ </listitem>
+ <listitem>
+ <para>$description: Description about the property</para>
+ </listitem>
+ <listitem>
+ <para>$required: The property is a required property; or optional and a default is supplied</para>
+ </listitem>
+ <listitem>
+ <para>$allowed: If property value must be in certain set of legal values, this defines all the allowed values</para>
+ </listitem>
+ <listitem>
+ <para>$masked: The tools need to mask the property; Do not show in plain text; used for passwords</para>
+ </listitem>
+ <listitem>
+ <para>$advanced: Notes this as Advanced property</para>
+ </listitem>
+ <listitem>
+ <para>$editable: Property can be modified; or read-only</para>
+ </listitem>
+ </itemizedlist>
+
+ Note that all these are optional properties; however in the absence of this metadata, tooling will not work as expected.
+
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Packaging the Adapter</title>
+ <para>Once all the required code is developed, it is time to package them into a RAR artifact, that can be deployed
+ into a Conainer. A RAR artifact is lot more similar to a WAR. To put together a RAR file it really depends upon
+ build system you are using.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Eclipse: You can start out with building Java Connector project, it will produce the RAR file</para>
+ </listitem>
+ <listitem>
+ <para>Ant: If you are using "ant" build tool, there is "rar" build task available</para>
+ </listitem>
+ <listitem>
+ <para>Maven: If you are using maven, use <packaging> element value as "rar". Teiid uses maven, you can look at any of
+ the "connector" projects for sample "pom.xml" file. Here is sample pom.xml file.</para>
+
+ <programlisting><![CDATA[
+ <?xml version="1.0" encoding="UTF-8"?>
+ <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <modelVersion>4.0.0</modelVersion>
+ <artifactId>connector-{name}</artifactId>
+ <groupId>org.company.project</groupId>
+ <name>Name Connector</name>
+ <packaging>rar</packaging>
+ <description>This connector is a sample</description>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss.teiid</groupId>
+ <artifactId>teiid-api</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss.teiid</groupId>
+ <artifactId>teiid-common-core</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>javax.resource</groupId>
+ <artifactId>connector-api</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ </dependencies>
+ </project>
+ ]]></programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>Make sure that the RAR file, under its "META-INF" directory has the "ra.xml" file. If you are using maven
+ see <ulink url="http://maven.apache.org/plugins/maven-rar-plugin/"></ulink>In the root of the RAR file,
+ you can embed the JAR file containing your connector code and any dependent library JAR files. </para>
+ </sect1>
+
+ <sect1>
+ <title>Deploying the Adapter</title>
+ <para>Once the RAR file is built, deploy it by copying the RAR file into "deploy" directory of JBoss AS's choosen profile.
+ Typically the server does not need to be restarted when a new RAR file is being added. Alternatively, you can also use
+ "admin-console" a web based monitoring and configuration tool to deploy this file into the container. </para>
+
+ <para>Once the Connector's RAR file is deployed into the JBoss container, now you can start creating a instance of this
+ connector to be used with your Translator. Creating a instance of this Connector is no different than creating a
+ "Connection Factory" in JBoss AS. Again, you have have two ways you can create a "ConnectionFactory".</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Create "${name}-ds.xml" file, and copy it into "deploy" directory of JBoss AS.
+ <programlisting><![CDATA[
+ <!DOCTYPE connection-factories PUBLIC
+ "-//JBoss//DTD JBOSS JCA Config 1.5//EN"
+ "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd">
+
+ <connection-factories>
+ <no-tx-connection-factory>
+ <jndi-name>${jndi-name}</jndi-name>
+ <rar-name>${name}.rar</rar-name>
+ <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
+
+ <!-- define all the properties defined in the "ra.xml" that required or needs to be modified from defaults -->
+ <!-- each property is defined in single element -->
+ <config-property name="prop-name" type="java.lang.String">prop-value</config-property>
+
+ </no-tx-connection-factory>
+ </connection-factories>
+ ]]></programlisting>
+ There are lot more properties that you can define for pooling, transactions, security etc in this file.
+ Check JBoss AS documentation for all the avaialble properties.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Alternatively you can use the web based "admin-console" configration and monitoring program, to create a new
+ Connection Factory. Just have your RAR file name and needed configuration properties handly and fill out web form
+ and create the ConnectionFactory.</para>
+ </listitem>
+
+ </itemizedlist>
+ </sect1>
+</chapter>
\ No newline at end of file
Property changes on: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/develop-adapter.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/introduction.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -1,137 +1,211 @@
<chapter id="introduction">
- <title>Connectors in Teiid</title>
- <para>A connector handles all communications with individual enterprise information sources, which can include
- databases, data feeds, flat files, etc.</para>
- <para>A connector is used to:</para>
+ <title>Translators and Resource Adapters in Teiid</title>
+
+ <para>To integrate data from a Enterprise Information System (EIS) into Teiid, Teiid requires two separate modules </para>
<itemizedlist>
<listitem>
+ <para>Translator</para>
+ </listitem>
+ <listitem>
+ <para>Resource Adapter (also sometimes called as Connector or J2EE Connector or JCA Connector or RAR file) </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A Translator is used to:</para>
+ <itemizedlist>
+ <listitem>
<para>Translate a Teiid-specific command into a native command.</para>
</listitem>
<listitem>
<para>Execute the command.</para>
</listitem>
<listitem>
- <para>Return batches of results.</para>
+ <para>Return batches of results in relational form.</para>
</listitem>
</itemizedlist>
- <para>Teiid is responsible for reassembling the results from one or more connectors into an
- answer for the user’s command.</para>
- <para>
- For a more detailed workflow, see the chapter
- <link linkend="connector_api">
- <emphasis>“Connector API.”</emphasis>
- </link>
- </para>
+
+ <para>A Resource Adapter is:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Handle all communications with individual enterprise information system(EIS), which can include databases, data feeds, flat files, etc.</para>
+ </listitem>
+ <listitem>
+ <para>This adapter can be a <ulink url="http://java.sun.com/j2ee/connector/">JEE JCA Connector</ulink> or any other custom connection provider.
+ The reason Teiid uses JEE JCA is, this specification defines how one can write, package and configure access to EIS system in consistent manner.
+ Also, there are various commercial/open source software vendors already provide JCA Connectors that provide
+ access mechanisms to variety of back-end systems.</para>
+ </listitem>
+ <listitem>
+ <para>Helps to execute the command and fetch results from source systems for a given Translator</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Given a combination of a Translator + Resource Adapter, one can connect any EIS system to Teiid for their data integration needs</para>
+
<sect1>
- <title>Do You Need a New Connector?</title>
- <para>Teiid provides several connectors for common enterprise information system types. If
+ <title>Do You Need a New Translator?</title>
+ <para>Teiid provides several translators for common enterprise information system types. If
you can use one of these enterprise information systems, you do not need to develop a custom one.
</para>
- <para>Teiid offers the following connectors:</para>
+ <para>Teiid offers the following translators:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>JDBC:</emphasis>
- Connects to many relational databases. The JDBC Connector is validated against the following database
- systems: Oracle, Microsoft SQL Server, IBM DB2, MySQL, Postgres, Derby, Sybase, H2, and HSQL. In addition, the JDBC Connector can
+ Works with many relational databases. The JDBC translator is validated against the following database
+ systems: Oracle, Microsoft SQL Server, IBM DB2, MySQL, Postgres, Derby, Sybase, H2, and HSQL. In addition, the JDBC Translator can
often be used with other 3rd-party drivers and provides a wide range of extensibility options to
specialize behavior against those drivers.
</para>
</listitem>
<listitem>
<para>
- <emphasis>Text:</emphasis>
- Connects to text files.
+ <emphasis>File:</emphasis>
+ Provides a procedural way to access the file system to handle text files.
</para>
</listitem>
<listitem>
<para>
- <emphasis>XML</emphasis>
- Connects to XML files on disk or by invoking Web services on other enterprise systems.
+ <emphasis>XML:</emphasis> Provides a procedural way to access XML content on the File system or in a Web-Service.
</para>
</listitem>
<listitem>
<para>
- <emphasis>LDAP</emphasis>
- Connects to LDAP directory services.
+ <emphasis>LDAP:</emphasis> Accesses to LDAP directory services.
</para>
</listitem>
<listitem>
<para>
- <emphasis>Salesforce</emphasis>
- Connects to Salesforce.
+ <emphasis>Salesforce:</emphasis> Works with Salesforce interfaces.
</para>
</listitem>
</itemizedlist>
+
</sect1>
<sect1>
- <title>Required Items to Write a Custom Connector</title>
- <para>To write a connector, follow this procedure:</para>
+ <title>Do You Need a New Resource Adapter?</title>
+ <para>As mentioned above, for every Translator that needs to gather data from external source systems, it requires a resource adapter.
+ The following resource adapters are provided by Teiid distribution to work with above Translators.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Data Source:</emphasis> This is provided by the JBoss AS container. This is used by the JDBC Translator.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>File:</emphasis> Provides a JEE JCA based Connector to access defined directory on the file system. This used by XML and File Translators</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>XML:</emphasis> Provides JEE JCA Connector to invoke Web Services using JBoss Web services stack. This is used by the XML Translator</para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>LDAP:</emphasis> Provides JEE JCA connector to access LDAP; Used by the LDAP Translator.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Salesforce:</emphasis> Provides JEE JCA connector to access Salesforce by invoking their Web Service interface. Used by the SalesForce Translator.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Required Items to Write a Custom Translator</title>
+ <para>To write a translator, follow this procedure:</para>
<orderedlist numeration="arabic">
<listitem>
- <para>Gather all necessary information about your Enterprise Information System (EIS). You will need
- to know:</para>
+ <para>Create a new or use a Resource Adapater for the EIS system, to be used with this Translator</para>
+ </listitem>
+ <listitem>
+ <para>Implement the required interfaces defined by the Translator API.</para>
<itemizedlist>
<listitem>
- <para>API for accessing the system</para>
+ <para>ExecutionFactory – Extend org.teiid.translator.ExecutionFactory class</para>
</listitem>
<listitem>
- <para>Configuration and connection information for the system</para>
+ <para>Execution (and sub-interfaces) – specifies how to execute each type of command</para>
</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Define the Template for exposing configuration properties</para>
+ </listitem>
+ <listitem>
+ <para>Deploy your Translator into Teiid.</para>
+ <itemizedlist>
<listitem>
- <para>Expectation for incoming queries/metadata</para>
+ <para>Deploy a Virtual Database (VDB) with metadata corresponding to your Translator</para>
</listitem>
- <listitem>
- <para>The processing constructs, or capabilities, supported by information system.</para>
- </listitem>
- <listitem>
- <para>Required properties for the connector, such as URL, user name, etc.</para>
- </listitem>
</itemizedlist>
</listitem>
<listitem>
- <para>Implement the required interfaces defined by the Connector API.</para>
+ <para>Execute queries via Teiid.</para>
+ </listitem>
+ </orderedlist>
+ <para>
+ This guide covers how to do each of these steps in detail. It also provides additional information for
+ advanced topics, such as connection pooling, streaming large objects, and transactions. For a sample
+ Translator code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">Teiid source code</ulink>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Required Items to write a JEE JCA based Custom Resource Adaptor</title>
+ <para>To write a resource adaptor, follow this procedure:</para>
+ <orderedlist numeration="arabic">
+ <listitem>
+ <para>The specification is defined by the <ulink url="http://java.sun.com/j2ee/connector/">JEE JCA Connector</ulink>.
+ You need to have basic idea about what JCA connectors are how they are developed and packaged.</para>
+ </listitem>
+ <listitem>
+ <para>Gather all necessary information about your Enterprise Information System (EIS). You will need
+ to know:</para>
<itemizedlist>
<listitem>
- <para>Connector – starting point.</para>
+ <para>API for accessing the system</para>
</listitem>
<listitem>
- <para>Connection – represents a connection to the source.</para>
+ <para>Configuration and connection information for the system</para>
</listitem>
<listitem>
- <para>ConnectorCapabilities – specifies what kinds of commands your connector can
- execute</para>
+ <para>Expectation for incoming queries/metadata</para>
</listitem>
<listitem>
- <para>Execution (and sub-interfaces) – specifies how to execute each type of command</para>
+ <para>The processing constructs, or capabilities, supported by information system.</para>
</listitem>
+ <listitem>
+ <para>Required properties for the connection, such as URL, user name, etc.</para>
+ </listitem>
</itemizedlist>
</listitem>
<listitem>
- <para>Test your connector with Connector Development Kit (CDK) test utilities.</para>
- </listitem>
- <listitem>
- <para>Deploy your connector type into Teiid.</para>
+ <para>All the required supporting JCA SPI classes provided by the Teiid API. The JCA CCI support is not provided from Teiid</para>
<itemizedlist>
<listitem>
- <para>Create and import your connector type definition file.</para>
+ <para>BasicConnectionFactory – Defines the Connection Factory</para>
</listitem>
<listitem>
- <para>Create a connector binding using the connector type</para>
+ <para>BasicConnection – represents a connection to the source.</para>
</listitem>
<listitem>
- <para>Deploy a Virtual Database with metadata corresponding to your EIS</para>
+ <para>BasicResourceAdapter – Specifies the resource adapter class</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
- <para>Execute queries via Teiid.</para>
+ <para>Package your resource adapter.</para>
+ </listitem>
+ <listitem>
+ <para>Deploy your resource adapter into Teiid.</para>
</listitem>
</orderedlist>
<para>
This guide covers how to do each of these steps in detail. It also provides additional information for
- advanced topics, such as connection pooling, streaming large objects, and transactions. For a sample
- connector code, please check the <ulink url="http://teiid.org">Teiid community</ulink>
+ advanced topics such as streaming large objects and transactions. For a sample
+ connector code, please check the <ulink url="http://anonsvn.jboss.org/repos/teiid/trunk/connectors/">Teiid Source code</ulink>
</para>
- </sect1>
+ </sect1>
</chapter>
\ No newline at end of file
Modified: trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml
===================================================================
--- trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml 2010-06-10 23:09:17 UTC (rev 2218)
+++ trunk/documentation/connector-developer-guide/src/main/docbook/en-US/content/lob-support.xml 2010-06-10 23:14:14 UTC (rev 2219)
@@ -1,9 +1,8 @@
<chapter id="lob_support">
<title>Handling Large Objects</title>
<para>This chapter examines how to use facilities provided by the Teiid
- Connector API to
- use large objects such as blobs, clobs, and xml in
- your connector.</para>
+ API to use large objects such as blobs, clobs, and xml in
+ your Translator.</para>
<sect1>
<title>Large Objects</title>
@@ -11,115 +10,68 @@
<sect2>
<title>Data Types</title>
<para>Teiid supports three large object runtime data types: blob,
- clob, and xml.
- A blob is a “binary large object”, a clob is a
- “character large
- object”, and “xml” is a “xml
- document”. Columns
- modeled as a blob, clob, or xml are treated similarly by
- the
- connector
- framework to support memory-safe streaming. </para>
+ clob, and xml. A blob is a “binary large object”, a clob is a
+ “character large object”, and “xml” is a “xml
+ document”. Columns modeled as a blob, clob, or xml are treated similarly by
+ the translator framework to support memory-safe streaming. </para>
</sect2>
<sect2>
<title>Why Use Large Object Support?</title>
- <para>Teiid allows a Connector to return a large object through the
- Teiid Connector API by just returning a reference to the actual
+ <para>Teiid allows a Translator to return a large object through the
+ Teiid translator API by just returning a reference to the actual
large object. Access to that LOB will be streamed as appropriate rather
- than retrieved all at once. This
- is useful for several reasons:</para>
+ than retrieved all at once. This is useful for several reasons:</para>
<orderedlist>
<listitem>
- <para>Reduces memory usage when returning the result set to the
- user.</para>
+ <para>Reduces memory usage when returning the result set to the user.</para>
</listitem>
<listitem>
- <para>Improves performance by passing less data in the result set.
- </para>
+ <para>Improves performance by passing less data in the result set.</para>
</listitem>
<listitem>
- <para>Allows access to large objects when needed rather than
- assuming that users will
+ <para>Allows access to large objects when needed rather than assuming that users will
always use the large object data.</para>
</listitem>
<listitem>
<para>Allows the passing of arbitrarily large data values.</para>
</listitem>
</orderedlist>
- <para>However, these benefits can only truly be gained if the
- Connector itself does not
- materialize an entire large object all at
- once. For example, the Java JDBC API
- supports a
- streaming interface
- for blob and clob data. </para>
+ <para>However, these benefits can only truly be gained if the Translator itself does not
+ materialize an entire large object all at once. For example, the Java JDBC API
+ supports a streaming interface for blob and clob data.</para>
</sect2>
</sect1>
<sect1>
<title>Handling Large Objects</title>
- <para>The Connector API automatically handles large objects
- (Blob/Clob/SQLXML) through
- the creation of special purpose wrapper
- objects when it retrieves results.
+ <para>The Translator API automatically handles large objects (Blob/Clob/SQLXML) through
+ the creation of special purpose wrapper objects when it retrieves results.
</para>
<para>Once the wrapped object is returned, the streaming of LOB is
- automatically supported. These LOB objects then can
- for example appear
- in client results, in user defined functions, or sent
- to other
- connectors.</para>
+ automatically supported. These LOB objects then can for example appear
+ in client results, in user defined functions, or sent to other translators.</para>
- <para>A connector execution is usually closed and the underlying
- connection is either
- closed/released as soon as all rows for that
- execution have been retrieved.
- However, LOB
- objects may need to be
- read after their initial retrieval of results. When
- LOBs are detected
- the default closing behavior
- is prevented by setting a flag on the
- ExecutionContext.</para>
+ <para>A Execution is usually closed and the underlying
+ connection is either closed/released as soon as all rows for that
+ execution have been retrieved. However, LOB objects may need to be
+ read after their initial retrieval of results. When LOBs are detected
+ the default closing behavior is prevented by setting a flag on the
+ ExecutionContext. See ExecutionContext.keepAlive() method. </para>
- <para>Now the connector execution
- only when the user Statement object
- is closed.
- Note that connectors may at their discretion have
- executions delayed in their closure by directly setting the keep
- alive on the ExecutionContext
- </para>
+ <para>When the "keepAlive" alive flag is set, then the execution object is only closed when user's Statement is closed.</para>
<programlisting><![CDATA[
executionContext.keepExecutionAlive(true);
]]></programlisting>
- <para>An important limitation of using the LOB type objects
- is that
- streaming is not supported from remote connectors.
- This is an issue in
- clustered environments if connectors intended to return
- LOBs are
- deployed on only
- a subset of the hosts or in failover situations. The
- most appropriate
- workaround to this
- limitation is to deploy connectors
- intended to return LOBs on each host in the
- cluster.</para>
</sect1>
<sect1>
<title>Inserting or Updating Large Objects</title>
- <para>LOBs will be passed to the Connector in the
- language objects as
- an
- ILiteral containing a java.sql.Blob, java.sql.Clob, or
- java.sql.SQLXML. You
- can use these interfaces to retrieve the data in
- the large object and
- use it for insert or
- update.</para>
+ <para>LOBs will be passed to the Translator in the
+ language objects as Literal containing a java.sql.Blob, java.sql.Clob, or
+ java.sql.SQLXML. You can use these interfaces to retrieve the data in
+ the large object and use it for insert or update.</para>
</sect1>
</chapter>
\ No newline at end of file
14 years, 7 months
- 1
- 0
teiid SVN: r2218 - trunk.
by teiid-commits＠lists.jboss.org
Author: rareddy
Date: 2010-06-10 19:09:17 -0400 (Thu, 10 Jun 2010)
New Revision: 2218
Modified:
trunk/pom.xml
Log:
misc: adding "dev" profile for quick builds for testing
Modified: trunk/pom.xml
===================================================================
--- trunk/pom.xml 2010-06-10 21:59:07 UTC (rev 2217)
+++ trunk/pom.xml 2010-06-10 23:09:17 UTC (rev 2218)
@@ -97,6 +97,32 @@
<module>documentation</module>
</modules>
</profile>
+ <profile>
+ <!--
+ This is to enable faster build for development time.
+ -->
+ <id>dev</id>
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <version>2.2-beta-2</version>
+ <configuration>
+ <descriptors>
+ <descriptor>build/assembly/client-jar.xml</descriptor>
+ <descriptor>build/assembly/jboss-container/dist.xml</descriptor>
+ <descriptor>build/assembly/adminshell/adminshell-dist.xml</descriptor>
+ </descriptors>
+ <outputDirectory>target/distribution</outputDirectory>
+ <workDirectory>target/assembly/work</workDirectory>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ <modules>
+ <module>build</module>
+ </modules>
+ </profile>
</profiles>
<build>
<!-- This section defines the default plugin settings inherited by child projects. -->
14 years, 7 months
- 1
- 0