[teiid-commits] teiid SVN: r3655 - in trunk: documentation/developer-guide/src/main/docbook/en-US/content and 1 other directory.

[teiid-commits at lists.jboss.org]

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>