[teiid-commits] teiid SVN: r3625 - in trunk: documentation/developer-guide/src/main/docbook/en-US/content and 1 other directories.
teiid-commits at lists.jboss.org
teiid-commits at lists.jboss.org
Wed Nov 9 15:55:18 EST 2011
Author: shawkins
Date: 2011-11-09 15:55:17 -0500 (Wed, 09 Nov 2011)
New Revision: 3625
Modified:
trunk/build/kits/jboss-container/teiid-releasenotes.html
trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml
trunk/documentation/reference/src/main/docbook/en-US/content/federated_planning.xml
Log:
TEIID-1726 adding the ability to pass source hints through the teiid system
Modified: trunk/build/kits/jboss-container/teiid-releasenotes.html
===================================================================
--- trunk/build/kits/jboss-container/teiid-releasenotes.html 2011-11-09 20:06:24 UTC (rev 3624)
+++ trunk/build/kits/jboss-container/teiid-releasenotes.html 2011-11-09 20:55:17 UTC (rev 3625)
@@ -38,6 +38,7 @@
<LI><B>View removal hint</B> - the NO_UNNEST hint now also applies to from clause views and subqueries. It will instruct the planner to not perform view flattening.
<LI><B>Non-blocking statement execution</B> - Teiid JDBC extensions TeiidStatement and TeiidPreparedStatement can be used to submit queries against embedded connections with a callback to process results in a non-blocking manner.
<LI><B>NON_STRICT limit hint</B> - the NON_STRICT hint can be used with unordered limits to tell the optimizer to not inhibit push operations even if the results will not be consistent with the logical application of the limit.
+ <LI><B>Source Hints</B> - user and transformation queries can specify a meta source hint, e.g. SELECT /*+ sh my-oracle:'leading' */ * FROM TBL. The hint information will be passed to the passed to the translator. The Oracle translator will by default treat the source hint as an Oracle hint.
</UL>
<h2><a name="Compatibility">Compatibility Issues</a></h2>
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-09 20:06:24 UTC (rev 3624)
+++ trunk/documentation/developer-guide/src/main/docbook/en-US/content/translator-api.xml 2011-11-09 20:55:17 UTC (rev 3625)
@@ -227,21 +227,37 @@
interface that defines how executions are
cancelled and closed. ProcedureExecution also extends ResultSetExecution, since procedures may also return resultsets.</para>
</section>
+
<section>
+ <title>ExecutionContext</title>
+ <para>The <code>org.teiid.translator.ExecutionContext</code> provides a considerable amount of information related to the current execution.
+ An <code>ExecutionContext</code> instance is made available to each <code>Execution</code>. Specific usage is highlighted in this guide where applicable, but you may use any informational getter method as desired.
+ Example usage would include calling <code>ExecutionContext.getRequestIdentifier()</code>, <code>ExecutionContext.getSession()</code>, etc. for logging purposes.</para>
+
+ <section>
+ <title>Source Hints</title>
+ <para>The Teiid source meta-hint is used to provide hints directly to source executions via user or transformation queries. See the reference for more on source hints. If specified and applicable, the general and source specific
+ hint will be supplied via the ExecutionContext methods <code>getGeneralHint</code> and <code>getSourceHint</code>. See the source for the <code>OracleExecutionFactory</code> for an example of how this source hint information
+ can be utilized.</para>
+ </section>
+
+ </section>
+
+ <section>
<title>ResultSetExecution</title>
<para>
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.
+ <code>ExecutionContext.getBatchSize()</code> method and used as a hint in fetching results from the EIS.
</para>
</section>
<section>
<title>Update Execution</title>
<para>Each execution returns the update count(s) expected by the update command.
If possible BatchedUpdates should be executed atomically.
- The ExecutionContext can be used to determine if the execution is already under a transaction.</para>
+ The <code>ExecutionContext.isTransactional()</code> method can be used to determine if the execution is already under a transaction.</para>
</section>
<section>
<title>Procedure Execution</title>
@@ -271,7 +287,7 @@
The
<code>DataNotAvailableException.NO_POLLING</code>
exception (or any DataNotAvailableException with a negative delay) can be thrown to indicate that
- the execution will call <code>ExecutionContext.dataAvailable</code> to indicate processing should resume.
+ the execution will call <code>ExecutionContext.dataAvailable()</code> to indicate processing should resume.
</para>
</note>
</para>
@@ -320,6 +336,7 @@
termination of queries being processed and may allow the underlying data source to terminate its operations
faster as well.</para>
</section>
+
</section>
<section id="command_language">
@@ -1497,8 +1514,8 @@
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>
+ the default closing behavior is prevented by setting a flag via the
+ <code>ExecutionContext.keepAlive</code> method. </para>
<para>When the "keepAlive" alive flag is set, then the execution object is only closed when user's Statement is closed.</para>
Modified: trunk/documentation/reference/src/main/docbook/en-US/content/federated_planning.xml
===================================================================
--- trunk/documentation/reference/src/main/docbook/en-US/content/federated_planning.xml 2011-11-09 20:06:24 UTC (rev 3624)
+++ trunk/documentation/reference/src/main/docbook/en-US/content/federated_planning.xml 2011-11-09 20:55:17 UTC (rev 3625)
@@ -712,9 +712,20 @@
</tbody>
</tgroup>
</informaltable>
- <para />
</section>
</section>
+ <section>
+ <title>Source Hints</title>
+ <para>Teiid user and transformation queries can contain a meta source hint that can provide additional information to source queries.
+ The source hint has the form /*+ sh(:'arg') source-name:'arg1' ... */ and is expected to appear after the query keyword, e.g. "SELECT /*+ sh:'general hint' my-oracle:'oracle hint' */.
+ The sh arg is optional and is passed to all source queries via the <code>ExecutionContext.getGeneralHint</code> method. See the Developer's Guide for more onThe additional args should have source-name that matches
+ the source name assigned to the translator in the VDB. If the source-name matches the hint value will be supplied via the <code>ExecutionContext.getSourceHint</code> method.
+ See the Developer's Guide for more on using an ExecutionContext.
+ Each of the arg values has the form of a string literal - it must be surrounded in single quotes and a single quote can be escaped with another signle quote.
+ Only the Oracle translator does anything with source hints by default. The Oracle translator will use either the source hint or the general hint (in that order) if available to form an Oracle hint enclosed in
+ /*+ ... */. Source hints in views will not be passed to the source if the view is used as a pushdown subquery, is joined, or is in a set operation.
+ </para>
+ </section>
</section>
<section id="query_planner">
<title>Query Planner</title>
More information about the teiid-commits
mailing list