From teiid-commits at lists.jboss.org Wed Nov 16 11:53:42 2011
Content-Type: multipart/mixed; boundary="===============3125102585569529651=="
MIME-Version: 1.0
From: teiid-commits at lists.jboss.org
To: teiid-commits at lists.jboss.org
Subject: [teiid-commits] teiid SVN: r3655 - in trunk:
 documentation/developer-guide/src/main/docbook/en-US/content and 1 other
 directory.
Date: Wed, 16 Nov 2011 11:53:42 -0500
Message-ID: <201111161653.pAGGrgAM032606@svn01.web.mwc.hst.phx2.redhat.com>

--===============3125102585569529651==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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/BaseDelegatingExecutionFact=
ory.java
   trunk/documentation/developer-guide/src/main/docbook/en-US/content/trans=
lator-api.xml
Log:
TEIID-1833 adding better documentation for the delegating translator

Modified: trunk/api/src/main/java/org/teiid/translator/BaseDelegatingExecut=
ionFactory.java
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/api/src/main/java/org/teiid/translator/BaseDelegatingExecutionFac=
tory.java	2011-11-15 18:52:28 UTC (rev 3654)
+++ trunk/api/src/main/java/org/teiid/translator/BaseDelegatingExecutionFac=
tory.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 thei=
r own and have this translator =

- * delegate all the calls to that class. Please note that your 'vdb.xml' f=
ile will contain
- * an xml fragment like the following to configure a delegating translator.
+ * Base delegating translator. Will proxy all calls to another {@link Exec=
utionFactory}. =

+ * You will create a custom translator as a subclass of this class contain=
ing overrides for
+ * any method you wish to intercept.
+ * Given that subclass is given a {@link Translator} name of 'custom-deleg=
ator', your 'vdb.xml' file will
+ * contain an XML fragment like the following to assign the delegate:
  * <pre>
  * {@code
-    <translator type=3D"delegate" name=3D"my-translator" description=3D"cu=
stom translator">
-        <property value=3D"delegateName" name=3D"name of the delegate inst=
ance"/>
-    </translator>
-   }
+ <translator type=3D"custom-delegator" name=3D"my-translator" description=
=3D"custom translator">
+    <property value=3D"delegateName" name=3D"name of the delegate instance=
"/>
+    <!-- any custom properties will also appear here -->
+ </translator>}
  * </pre>
  *  =

  */

Modified: trunk/documentation/developer-guide/src/main/docbook/en-US/conten=
t/translator-api.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/documentation/developer-guide/src/main/docbook/en-US/content/tran=
slator-api.xml	2011-11-15 18:52:28 UTC (rev 3654)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/tran=
slator-api.xml	2011-11-16 16:53:41 UTC (rev 3655)
@@ -1532,6 +1532,49 @@
 	</section>
 		=

 	</section>
+	=

+	<section id=3D"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 t=
he delegating translator framework which provides you with a proxying mecha=
nism to override translator behavior.
+		It implement a delegating translator, your common translator logic shoul=
d be added to a subclass of BaseDelegatingExecutionFactory where you can ov=
erride any of the delegation methods to perform whatever logic you want.
+        <example>
+        	<title>Example BaseDelegatingExecutionFactory Subclass</title>
+        	<programlisting language=3D"JAVA"><![CDATA[@Translator(name=3D"cu=
stom-delegator")
+public class MyTranslator extends BaseDelegatingExecutionFactory<Object, O=
bject> {
+	=

+	@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, connec=
tion);
+	}
+	...	=

+}]]></programlisting>
+		</example>
+		</para>
+		<para>You will bundle and deploy your custom delegating translator is ju=
st 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=3D"JAVA"><![CDATA[<translator type=3D"cu=
stom-delegator" name=3D"my-translator">
+
+     <property value=3D"delegateName" name=3D"name of the delegate instanc=
e"/>
+
+     <!-- 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 instan=
ce, whether configured by it's own translator entry or just the name of a s=
tandard translator type.</para></note>
+		</para>
+	</section>
     =

     <section id=3D"translator_package">
         <title>Packaging</title>


--===============3125102585569529651==--