<html>
<head>
<base href="https://docs.jboss.org/author">
<link rel="stylesheet" href="/author/s/en/2172/19/5/_/styles/combined.css?spaceKey=TEIID&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://docs.jboss.org/author/display/TEIID/Executing+Commands">Executing Commands</a></h2>
<h4>Page <b>edited</b> by <a href="https://docs.jboss.org/author/display/~shawkins">Steven Hawkins</a>
</h4>
<br/>
<h4>Changes (2)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >The {{org.teiid.translator.ExecutionContext}} provides a considerable amount of information related to the current execution. An {{ExecutionContext}} instance is made available to each {{Execution}}. Specific usage is highlighted in this guide where applicable, but you may use any informational getter method as desired. Example usage would include calling {{ExecutionContext.getRequestId()}}, {{ExecutionContext.getSession()}}, etc. for logging purposes. <br> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h2. A {{org.teiid.CommandContext}} is available via the {{ExecutionContext.getCommandContext()}} method. The CommandContext contains information about the current user query, including the {{VDB}}, the ability to add client warnings - {{addWarning}}, or handle generated keys - {{isReturnAutoGeneratedKeys}}, {{returnGeneratedKeys}}, and {{getGeneratedKeys}}. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Generated Keys <br> <br>To see if the user query expects generated keys to be returned, consult the {{CommandContext.isReturnAutoGeneratedKeys()}} method. If you wish to return generated keys, you must first create a {{GeneratedKeys}} instance to hold the keys with the {{returnGeneratedKeys}} method passing the column names and types of the key columns. Only one {{GeneratedKeys}} may be associated with the {{CommandContext}} at any given time. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h2. Source Hints <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="ExecutingCommands-ExecutionModes"></a>Execution Modes</h1>
<p>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 Command Language. Refer to <a href="/author/display/TEIID/Command+Language" title="Command Language">Command Language</a>. Translators are allowed to support any subset of the available execution modes.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Execution Interface </th>
<th class='confluenceTh'> Command interface(s) </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>ResultSetExecution</tt> </td>
<td class='confluenceTd'> <tt>QueryExpression</tt> </td>
<td class='confluenceTd'> A query corresponding to a SQL SELECT or set query statement. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>UpdateExecution</tt> </td>
<td class='confluenceTd'> <tt>Insert, Update, Delete, BatchedUpdates</tt> </td>
<td class='confluenceTd'> An insert, update, or delete, corresponding to a SQL INSERT, UPDATE, or DELETE command </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ProcedureExecution</tt> </td>
<td class='confluenceTd'> <tt>Call</tt> </td>
<td class='confluenceTd'> A procedure execution that may return a result set and/or output values. </td>
</tr>
</tbody></table>
</div>
<p><b>Types of Execution Modes</b>
<br class="atl-forced-newline" /></p>
<p>All of the execution interfaces extend the base <tt>Execution</tt> interface that defines how executions are cancelled and closed. ProcedureExecution also extends ResultSetExecution, since procedures may also return resultsets.</p>
<h1><a name="ExecutingCommands-ExecutionContext"></a>ExecutionContext</h1>
<p>The <tt>org.teiid.translator.ExecutionContext</tt> provides a considerable amount of information related to the current execution. An <tt>ExecutionContext</tt> instance is made available to each <tt>Execution</tt>. Specific usage is highlighted in this guide where applicable, but you may use any informational getter method as desired. Example usage would include calling <tt>ExecutionContext.getRequestId()</tt>, <tt>ExecutionContext.getSession()</tt>, etc. for logging purposes.</p>
<h2><a name="ExecutingCommands-A%7B%7Borg.teiid.CommandContext%7D%7Disavailableviathe%7B%7BExecutionContext.getCommandContext%28%29%7D%7Dmethod.TheCommandContextcontainsinformationaboutthecurrentuserquery%2Cincludingthe%7B%7BVDB%7D%7D%2Ctheabilitytoaddclientwarnings%7B%7BaddWarning%7D%7D%2C..."></a>A <tt>org.teiid.CommandContext</tt> is available via the <tt>ExecutionContext.getCommandContext()</tt> method. The CommandContext contains information about the current user query, including the <tt>VDB</tt>, the ability to add client warnings - <tt>addWarning</tt>, or handle generated keys - <tt>isReturnAutoGeneratedKeys</tt>, <tt>returnGeneratedKeys</tt>, and <tt>getGeneratedKeys</tt>.</h2>
<h3><a name="ExecutingCommands-GeneratedKeys"></a>Generated Keys</h3>
<p>To see if the user query expects generated keys to be returned, consult the <tt>CommandContext.isReturnAutoGeneratedKeys()</tt> method. If you wish to return generated keys, you must first create a <tt>GeneratedKeys</tt> instance to hold the keys with the <tt>returnGeneratedKeys</tt> method passing the column names and types of the key columns. Only one <tt>GeneratedKeys</tt> may be associated with the <tt>CommandContext</tt> at any given time.</p>
<h2><a name="ExecutingCommands-SourceHints"></a>Source Hints</h2>
<p>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 <tt>getGeneralHint</tt> and <tt>getSourceHint</tt>. See the source for the <tt>OracleExecutionFactory</tt> for an example of how this source hint information can be utilized.</p>
<h1><a name="ExecutingCommands-ResultSetExecution"></a>ResultSetExecution</h1>
<p>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 <tt>ExecutionContext.getBatchSize()</tt> method and used as a hint in fetching results from the EIS.</p>
<h1><a name="ExecutingCommands-UpdateExecution"></a>Update Execution</h1>
<p>Each execution returns the update count(s) expected by the update command. If possible BatchedUpdates should be executed atomically. The <tt>ExecutionContext.isTransactional()</tt> method can be used to determine if the execution is already under a transaction.</p>
<h1><a name="ExecutingCommands-ProcedureExecution"></a>Procedure Execution</h1>
<p>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.</p>
<p>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.</p>
<h1><a name="ExecutingCommands-AsynchronousExecutions"></a>Asynchronous Executions</h1>
<p>In some scenarios, a translator needs to execute asynchronously and allow the executing thread to perform other work. To allow asynchronous execution, you should throw a <tt>DataNotAvailableExecption</tt> during a retrieval method, rather than explicitly waiting or sleeping for the results. The <tt>DataNotAvailableException</tt> may take a delay parameter or a <tt>Date</tt> in its constructor to indicate when to poll next for results. Any non-negative delay value indicates the time in milliseconds until the next polling should be performed. The <tt>DataNotAvailableException.NO_POLLING</tt> exception (or any DataNotAvailableException with a negative delay) can be thrown to indicate that the execution will call <tt>ExecutionContext.dataAvailable()</tt> to indicate processing should resume.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/author/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>A <tt>DataNotAvailableException</tt> should not be thrown by the execute method, as that can result in the execute method being called multiple times.</td></tr></table></div>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/author/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Since the execution and the associated connection are not closed until the work has completed, care should be taken if using asynchronous executions that hold a lot of state.</td></tr></table></div>
<p>A positive retry delay is not a guarantee of when the translator will be polled next. If the <tt>DataNotAvailableException</tt> is consumed while the engine thinks more work can be performed or there are other shorter delays issued from other translators, then the plan may be re-queued earlier than expected. You should simply rethrow a <tt>DataNotAvailableException</tt> if your execution is not yet ready. Alternatively the <tt>DataNotAvailableException</tt> may be marked as strict, which does provide a guarantee that the <tt>Execution</tt> will not be called until the delay has expired or the given <tt>Date</tt> has been reached. Using the <tt>Date</tt> constructor makes the <tt>DataNotAvailableException</tt> automatically strict. Due to engine thread pool contention, platform time resolution, etc. a strict <tt>DataNotAvailableException</tt> is not a real-time guarantee of when the next poll for results will occur, only that it will not occur before then.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/author/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>If your <tt>ExecutionFactory</tt> returns only asynch executions that perform minimal work, then consider having <tt>ExecutionFactory.isForkable</tt> return false so that the engine knows not to spawn a separate thread for accessing your <tt>Execution</tt>.</td></tr></table></div>
<h1><a name="ExecutingCommands-ReusableExecutions"></a>Reusable Executions</h1>
<p>A translator may return instances of <tt>ReusableExecutions</tt> for the expected Execution objects. There can be one <tt>ReusableExecution</tt> per query executing node in the processing plan. The lifecycle of a <tt>ReusableExecution</tt> is different that a normal <tt>Execution</tt>. After a normal creation/execute/close cycle the <tt>ReusableExecution.reset</tt> is called for the next execution cycle. This may occur indefinitely depending on how many times a processing node executes its query. The behavior of the <tt>close</tt> method is no different than a regular <tt>Execution</tt>, it may not be called until the end of the statement if lobs are detected and any connection associated with the <tt>Execution</tt> will also be closed. When the user command is finished, the <tt>ReusableExecution.dispose()</tt> method will be called.</p>
<p>In general <tt>ReusableExecutions</tt> are most useful for continuous query execution and will also make use of the <tt>ExecutionCotext.dataAvailable()</tt> method for <a href="#ExecutingCommands-AsynchronousExecutions">Asynchronous Executions</a>. See the Client Developer's Guide for executing <a href="/author/display/TEIID/Non-blocking+Statement+Execution" title="Non-blocking Statement Execution">continuous statements</a>. In continuous mode the user query will be continuously re-executed. A <tt>ReusableExecution</tt> allows the same <tt>Execution</tt> object to be associated with the processing plan for a given processing node for the lifetime of the user query. This can simplify asynch resource management, such as establishing queue listeners. Returning a null result from the <tt>next()</tt> method <tt>ReusableExecution</tt> just as with normal <tt>Executions</tt> indicates that the current pushdown command results have ended. Once the <tt>reset()</tt> method has been called, the next set of results should be returned again terminated with a null result.</p>
<p>See the kit examples for a reusable execution example.</p>
<h1><a name="ExecutingCommands-BulkExecution"></a>Bulk Execution</h1>
<p>Non batched <tt>Insert, Update, Delete</tt> commands may have multi-valued <tt>Parameter</tt> objects if the capabilities shows support for BulkUpdate. Commands with multi-valued {{Parameters}}s represent multiple executions of the same command with different values. As with BatchedUpdates, bulk operations should be executed atomically if possible.</p>
<h1><a name="ExecutingCommands-CommandCompletion"></a>Command Completion</h1>
<p>All normal command executions end with the calling of <tt>close()</tt> on the Execution object. Your implementation of this method should do the appropriate clean-up work for all state created in the Execution object.</p>
<h1><a name="ExecutingCommands-CommandCancellation"></a>Command Cancellation</h1>
<p>Commands submitted to Teiid may be aborted in several scenarios:</p>
<ul>
<li>Client cancellation via the JDBC API (or other client APIs)</li>
<li>Administrative cancellation</li>
<li>Clean-up during session termination</li>
<li>Clean-up if a query fails during processing<br/>
Unlike the other execution methods, which are handled in a single-threaded manner, calls to cancel happen asynchronously with respect to the execution thread.</li>
</ul>
<p>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 faster as well.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://docs.jboss.org/author/users/removespacenotification.action?spaceKey=TEIID">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://docs.jboss.org/author/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://docs.jboss.org/author/display/TEIID/Executing+Commands">View Online</a>
|
<a href="https://docs.jboss.org/author/pages/diffpagesbyversion.action?pageId=18646168&revisedVersion=7&originalVersion=6">View Changes</a>
|
<a href="https://docs.jboss.org/author/display/TEIID/Executing+Commands?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>