10:53 a.m.
Author: shawkins
Date: 2011-11-16 11:53:41 -0500 (Wed, 16 Nov 2011)
New Revision: 3655
Modified:
trunk/api/src/main/java/org/teiid/translator/BaseDelegatingExecutionFactory.java
trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml
Log:
TEIID-1833 adding better documentation for the delegating translator
Modified:
trunk/api/src/main/java/org/teiid/translator/BaseDelegatingExecutionFactory.java
===================================================================
---
trunk/api/src/main/java/org/teiid/translator/BaseDelegatingExecutionFactory.java 2011-11-15
18:52:28 UTC (rev 3654)
+++
trunk/api/src/main/java/org/teiid/translator/BaseDelegatingExecutionFactory.java 2011-11-16
16:53:41 UTC (rev 3655)
@@ -33,15 +33,17 @@
import org.teiid.metadata.RuntimeMetadata;
/**
- * Delegate translator. User can define a {@link ExecutionFactory} of their own and have
this translator
- * delegate all the calls to that class. Please note that your 'vdb.xml' file
will contain
- * an xml fragment like the following to configure a delegating translator.
+ * Base delegating translator. Will proxy all calls to another {@link ExecutionFactory}.
+ * You will create a custom translator as a subclass of this class containing overrides
for
+ * any method you wish to intercept.
+ * Given that subclass is given a {@link Translator} name of 'custom-delegator',
your 'vdb.xml' file will
+ * contain an XML fragment like the following to assign the delegate:
* <pre>
* {@code
- <translator type="delegate" name="my-translator"
description="custom translator">
- <property value="delegateName" name="name of the delegate
instance"/>
- </translator>
- }
+ <translator type="custom-delegator" name="my-translator"
description="custom translator">
+ <property value="delegateName" name="name of the delegate
instance"/>
+ <!-- any custom properties will also appear here -->
+ </translator>}
* </pre>
*
*/
Modified:
trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml
===================================================================
---
trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml 2011-11-15
18:52:28 UTC (rev 3654)
+++
trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml 2011-11-16
16:53:41 UTC (rev 3655)
@@ -1532,6 +1532,49 @@
</section>
</section>
+
+ <section id="delegating_translator">
+ <title>Delegating Translator</title>
+ <para>In some instances you may wish to extend several differnt kinds of
translators with the same functionality.
+ Rather than create separate subclasses for each extension, you can use the delegating
translator framework which provides you with a proxying mechanism to override translator
behavior.
+ It implement a delegating translator, your common translator logic should be added to a
subclass of BaseDelegatingExecutionFactory where you can override any of the delegation
methods to perform whatever logic you want.
+ <example>
+ <title>Example BaseDelegatingExecutionFactory Subclass</title>
+ <programlisting
language="JAVA"><![CDATA[@Translator(name="custom-delegator")
+public class MyTranslator extends BaseDelegatingExecutionFactory<Object, Object> {
+
+ @Override
+ public Execution createExecution(Command command,
+ ExecutionContext executionContext, RuntimeMetadata metadata,
+ Object connection) throws TranslatorException {
+ if (command instanceof Select) {
+ //modify the command or return a different execution
+ ...
+
+ }
+ //the super call will be to the delegate instance
+ return super.createExecution(command, executionContext, metadata, connection);
+ }
+ ...
+}]]></programlisting>
+ </example>
+ </para>
+ <para>You will bundle and deploy your custom delegating translator is just like
any other custom translator development.
+ To you use your delegating translator in a vdb, you define a translator override that
wires in the delegate.
+ <example>
+ <title>Example Translator Override</title>
+ <programlisting language="JAVA"><![CDATA[<translator
type="custom-delegator" name="my-translator">
+
+ <property value="delegateName" name="name of the delegate
instance"/>
+
+ <!-- any custom properties you may have on your custom translator -->
+
+</translator>]]></programlisting>
+ <para>From the previous example the translator type is custom-delegator. Now
my-translator can be used as a translator-name on a source and will proxy all calls to
whatever delegate instance you assign.</para>
+ </example>
+ <note><para>Note that the delegate instance can be any translator instance,
whether configured by it's own translator entry or just the name of a standard
translator type.</para></note>
+ </para>
+ </section>
<section id="translator_package">
<title>Packaging</title>